From 409891f625dc98ba5469f3352791584e6ea9e23c Mon Sep 17 00:00:00 2001 From: peterschmidt85 Date: Thu, 21 Aug 2025 16:10:29 +0200 Subject: [PATCH] [Docs] Improve the docs regarding `dstack init` and repos to reflect the recent changes. --- docs/docs/concepts/dev-environments.md | 11 +++--- docs/docs/concepts/repos.md | 25 ++++++------- docs/docs/concepts/services.md | 11 +++--- docs/docs/concepts/tasks.md | 11 +++--- docs/docs/quickstart.md | 49 ++++++++++++++++++++------ 5 files changed, 67 insertions(+), 40 deletions(-) diff --git a/docs/docs/concepts/dev-environments.md b/docs/docs/concepts/dev-environments.md index 4ccfcc951b..e5d3b9ec79 100644 --- a/docs/docs/concepts/dev-environments.md +++ b/docs/docs/concepts/dev-environments.md @@ -51,8 +51,7 @@ To open in VS Code Desktop, use this link: -`dstack apply` automatically provisions an instance, uploads the contents of the repo (incl. your local uncommitted changes), -and sets up an IDE on the instance. +`dstack apply` automatically provisions an instance and sets up an IDE on it. ??? info "Windows" On Windows, `dstack` works both natively and inside WSL. But, for dev environments, @@ -297,10 +296,10 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above), ### Files -By default, `dstack` automatically mounts the [repo](repos.md) directory where you ran `dstack init` to any run configuration. +If you configured a [repo](repos.md), `dstack` automatically mounts its content (incl. your local changes) inside the container. -However, in some cases, you may not want to mount the entire directory (e.g., if it’s too large), -or you might want to mount files outside of it. In such cases, you can use the [`files`](../reference/dstack.yml/dev-environment.md#files) property. +In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using +[`files`](../reference/dstack.yml/task.md#_files) instead of repos.
@@ -351,7 +350,7 @@ $ dstack apply -f examples/.dstack.yml --no-repo
??? info ".gitignore and .dstackignore" - `dstack` automatically excludes files and folders listed in `.gitignore` and `.dstackignore`. + If you configured a [repo](repos.md) or [files](#files), `dstack` excludes files and folders listed in `.gitignore` and `.dstackignore`. Uploads are limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files. You can increase the default server limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. diff --git a/docs/docs/concepts/repos.md b/docs/docs/concepts/repos.md index 33ebe404e9..22356b7be1 100644 --- a/docs/docs/concepts/repos.md +++ b/docs/docs/concepts/repos.md @@ -1,13 +1,18 @@ # Repos -Running a dev environment, task, or service with [`dstack apply`](../reference/cli/dstack/apply.md) in a directory -mounts the contents of that directory to the container’s `/workflow` directory and sets it as the container’s current working directory. -This allows accessing the directory files from within the run. +Repos allow mounting remote Git repos with workloads. -## Initialize a repo +> Starting with 0.19.26, repos will be [configurable :material-arrow-top-right-thin:{ .external }](https://github.com/dstackai/dstack/issues/2851){:target="_blank"} in the run configuration. + +For now, to mount a repo with workloads, run [`dstack init`](../reference/cli/dstack/init.md) in the repo directory, and then execute [`dstack apply`](../reference/cli/dstack/apply.md) from the same directory. -To use a directory with `dstack apply`, it must first be initialized as a repo by running [`dstack init`](../reference/cli/dstack/init.md). -The directory must be a cloned Git repo. +In this case, `dstack` mounts the contents of the repo to the container’s `/workflow` directory and sets it as the container’s current working directory. Note that `dstack` also includes any local changes. + +??? info "Files" + In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using + [`files`](../reference/dstack.yml/task.md#_files) instead of repos. + +## Initialize a repo [`dstack init`](../reference/cli/dstack/init.md) is not required if you pass `-P` (or `--repo`) to [`dstack apply`](../reference/cli/dstack/apply.md) (see below). @@ -30,10 +35,6 @@ Uploads are limited to 2MB. Use `.gitignore` to exclude unnecessary files from b You can set the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable to increase the default server limit. Increasing the limit is recommended only if you [configure an object storage](../guides/server-deployment.md). -### Use a local directory instead of a Git repo - -If the directory is not a cloned Git repo, use [`files`](../reference/dstack.yml/task.md#_files). - ## Specify the repo By default, `dstack apply` uses the current directory as a repo if it is already initialized. @@ -81,12 +82,12 @@ $ dstack apply -f .dstack.yml --no-repo -## Store the repo on a volume + ## What's next? diff --git a/docs/docs/concepts/services.md b/docs/docs/concepts/services.md index 368e9ad8e9..442f47618d 100644 --- a/docs/docs/concepts/services.md +++ b/docs/docs/concepts/services.md @@ -63,8 +63,7 @@ Model meta-llama/Meta-Llama-3.1-8B-Instruct is published at: -`dstack apply` automatically provisions instances, uploads the contents of the repo (incl. your local uncommitted changes), -and runs the service. +`dstack apply` automatically provisions instances and runs the service. If a [gateway](gateways.md) is not configured, the service’s endpoint will be accessible at `/proxy/services///`. @@ -591,8 +590,10 @@ resources: By default, `dstack` automatically mounts the [repo](repos.md) directory where you ran `dstack init` to any run configuration. -However, in some cases, you may not want to mount the entire directory (e.g., if it’s too large), -or you might want to mount files outside of it. In such cases, you can use the [`files`](../reference/dstack.yml/dev-environment.md#files) property. +If you configured a [repo](repos.md), `dstack` automatically mounts its content (incl. your local changes) inside the container. + +In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using +[`files`](../reference/dstack.yml/task.md#_files) instead of repos. @@ -670,7 +671,7 @@ $ dstack apply -f examples/.dstack.yml --no-repo ??? info ".gitignore and .dstackignore" - `dstack` automatically excludes files and folders listed in `.gitignore` and `.dstackignore`. + If you configured a [repo](repos.md) or [files](#files), `dstack` excludes files and folders listed in `.gitignore` and `.dstackignore`. Uploads are limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files. You can increase the default server limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. diff --git a/docs/docs/concepts/tasks.md b/docs/docs/concepts/tasks.md index dd6e8d27ce..e5925044d1 100644 --- a/docs/docs/concepts/tasks.md +++ b/docs/docs/concepts/tasks.md @@ -65,8 +65,7 @@ Launching `axolotl-train`... -`dstack apply` automatically provisions instances, uploads the contents of the repo (incl. your local uncommitted changes), -and runs the commands. +`dstack apply` automatically provisions instances and runs the task. ## Configuration options @@ -463,10 +462,10 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above), ### Files -By default, `dstack` automatically mounts the [repo](repos.md) directory where you ran `dstack init` to any run configuration. +If you configured a [repo](repos.md), `dstack` automatically mounts its content (incl. your local changes) inside the container. -However, in some cases, you may not want to mount the entire directory (e.g., if it’s too large), -or you might want to mount files outside of it. In such cases, you can use the [`files`](../reference/dstack.yml/dev-environment.md#files) property. +In some cases, you don’t need to mount an entire repo and can mount only specific directories. This can be done using +[`files`](../reference/dstack.yml/task.md#_files) instead of repos.
@@ -551,7 +550,7 @@ $ dstack apply -f examples/.dstack.yml --no-repo
??? info ".gitignore and .dstackignore" - `dstack` automatically excludes files and folders listed in `.gitignore` and `.dstackignore`. + If you configured a [repo](repos.md) or [files](#files), `dstack` excludes files and folders listed in `.gitignore` and `.dstackignore`. Uploads are limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files. You can increase the default server limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md index f4b279938a..60c8ea09df 100644 --- a/docs/docs/quickstart.md +++ b/docs/docs/quickstart.md @@ -1,27 +1,33 @@ # Quickstart > Before using `dstack`, ensure you've [installed](installation/index.md) the server, or signed up for [dstack Sky :material-arrow-top-right-thin:{ .external }](https://sky.dstack.ai){:target="_blank"}. - -## Initialize a repo -Before using `dstack`'s CLI in a directory, initialize the directory as a repo with [`dstack init`](reference/cli/dstack/init.md). +## Set up a directory + +Set up a directory where you'll store you project files and `dstack` configurations.
```shell $ mkdir quickstart && cd quickstart -$ dstack init ```
-## Apply a configuration +> If the directory is a remote Git repo that you want to mount with workloads, run `dstack init`. +> Starting with 0.19.26, repos will be [configurable :material-arrow-top-right-thin:{ .external }](https://github.com/dstackai/dstack/issues/2851){:target="_blank"} in the run configuration. + +## Run your first workload + +`dstack` supports three types of workloads. === "Dev environment" A dev environment lets you provision an instance and access it with your desktop IDE. - Create the following configuration file inside the repo: +

Define a configuration

+ + Create the following run configuration inside your project folder:
@@ -42,6 +48,8 @@ $ dstack init
+

Apply the configuration

+ Apply the configuration via [`dstack apply`](reference/cli/dstack/apply.md):
@@ -73,7 +81,9 @@ $ dstack init A task allows you to schedule a job or run a web app. Tasks can be distributed and can forward ports. - Create the following configuration file inside the repo: +

Define a configuration

+ + Create the following run configuration inside your project folder:
@@ -103,6 +113,8 @@ $ dstack init By default, tasks run on a single instance. To run a distributed task, specify [`nodes`](concepts/tasks.md#distributed-tasks), and `dstack` will run it on a cluster. +

Apply the configuration

+ Run the configuration via [`dstack apply`](reference/cli/dstack/apply.md):
@@ -133,7 +145,9 @@ $ dstack init A service allows you to deploy a model or any web app as an endpoint. - Create the following configuration file inside the repo: +

Define a configuration

+ + Create the following run configuration inside your project folder:
@@ -164,6 +178,8 @@ $ dstack init
+

Apply the configuration

+ Run the configuration via [`dstack apply`](reference/cli/dstack/apply.md):
@@ -198,14 +214,25 @@ $ dstack init If you're using [dstack Sky :material-arrow-top-right-thin:{ .external }](https://sky.dstack.ai){:target="_blank"}, a gateway is pre-configured for you. -> `dstack apply` automatically provisions instances, uploads the contents of the repo (incl. your local uncommitted changes), -and runs the configuration. +`dstack apply` automatically provisions instances and runs the workload according to the configuration. + +??? info "Repo is not initialized" + + If you don't run `dstack init`, you may see the following warning: + + ``` + Repo is not initialized. Use --repo or --no-repo to initialize it. + Starting from 0.19.26, repos will be configured via YAML and this message won't appear. + ``` + + From 0.19.26 onward, this message will no longer be shown since repos can be + [configured :material-arrow-top-right-thin:{ .external }](https://github.com/dstackai/dstack/issues/2851){:target="_blank"} in the run configuration. ## Troubleshooting Something not working? See the [troubleshooting](guides/troubleshooting.md) guide. !!! info "What's next?" - 1. Read about [backends](concepts/backends.md), [dev environments](concepts/dev-environments.md), [tasks](concepts/tasks.md), and [services](concepts/services.md) + 1. Read about [backends](concepts/backends.md), [dev environments](concepts/dev-environments.md), [tasks](concepts/tasks.md), [services](concepts/services.md), and [fleets](concepts/services.md) 2. Browse [examples](../examples.md) 3. Join [Discord :material-arrow-top-right-thin:{ .external }](https://discord.gg/u8SmfwPpMd)