diff --git a/docs/docs/concepts/dev-environments.md b/docs/docs/concepts/dev-environments.md index e5d3b9ec79..7a1ab9690b 100644 --- a/docs/docs/concepts/dev-environments.md +++ b/docs/docs/concepts/dev-environments.md @@ -296,10 +296,7 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above), ### Files -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. +Sometimes, when you run a dev environment, you may want to mount local files. This is possible via the [`files`](../reference/dstack.yml/task.md#_files) property. Each entry maps a local directory or file to a path inside the container.
@@ -316,12 +313,10 @@ ide: vscode
-Each entry maps a local directory or file to a path inside the container. Both local and container paths can be relative or absolute. - -- If the local path is relative, it’s resolved relative to the configuration file. -- If the container path is relative, it’s resolved relative to `/workflow`. +If the local path is relative, it’s resolved relative to the configuration file. +If the container path is relative, it’s resolved relative to `/workflow`. -The container path is optional. If not specified, it will be automatically calculated. +The container path is optional. If not specified, it will be automatically calculated:
@@ -338,25 +333,71 @@ ide: vscode
-Note: If you want to use `files` without mounting the entire repo directory, -make sure to pass `--no-repo` when running `dstack apply`: +??? info "Upload limit and excludes" + Whether its a file or folder, each entry is limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files + by listing it via `.gitignore` or `.dstackignore`. + The 2MB upload limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. -
+### Repos -```shell -$ dstack apply -f examples/.dstack.yml --no-repo +Sometimes, you may want to mount an entire Git repo inside the container. + +Imagine you have a cloned Git repo containing an `examples` subdirectory with a `.dstack.yml` file: + +
+ +```yaml +type: dev-environment +name: vscode + +repos: + # Mounts the parent directory of `examples` (must be a Git repo) + # to `/workflow` (the default working directory) + - .. + +ide: vscode ```
-??? info ".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. +When you run it, `dstack` fetches the repo on the instance, applies your local changes, and mounts it—so the container matches your local repo. + +The local path can be either relative to the configuration file or absolute. + +??? info "Path" + Currently, `dstack` always mounts the repo to `/workflow` inside the container. It's the default working directory. + Starting with the next release, it will be possible to specify a custom container path. + +??? info "Local diff limit and excludes" + The local diff size is limited to 2MB. To avoid exceeding this limit, exclude unnecessary files + via `.gitignore` or `.dstackignore`. + The 2MB local diff limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. + +??? info "Repo URL" + Sometimes you may want to mount a Git repo without cloning it locally. In this case, simply provide a URL in `repos`: + +
+ + ```yaml + type: dev-environment + name: vscode + + repos: + # Clone the specified repo to `/workflow` (the default working directory) + - https://github.com/dstackai/dstack + + ide: vscode + ``` + +
+ +??? info "Private repos" + If a Git repo is private, `dstack` will automatically try to use your default Git credentials (from + `~/.ssh/config` or `~/.config/gh/hosts.yml`). + + If you want to use custom credentials, you can provide them with [`dstack init`](../reference/cli/dstack/init.md). -!!! warning "Experimental" - The `files` feature is experimental. Feedback is highly appreciated. +> Currently, you can configure up to one repo per run configuration. ### Retry policy @@ -534,5 +575,5 @@ via the [`spot_policy`](../reference/dstack.yml/dev-environment.md#spot_policy) --8<-- "docs/concepts/snippets/manage-runs.ext" !!! info "What's next?" - 1. Read about [tasks](tasks.md), [services](services.md), and [repos](repos.md) + 1. Read about [tasks](tasks.md) and [services](services.md) 2. Learn how to manage [fleets](fleets.md) diff --git a/docs/docs/concepts/repos.md b/docs/docs/concepts/repos.md deleted file mode 100644 index 22356b7be1..0000000000 --- a/docs/docs/concepts/repos.md +++ /dev/null @@ -1,94 +0,0 @@ -# Repos - -Repos allow mounting remote Git repos with workloads. - -> 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. - -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). - -### Git credentials - -[`dstack init`](../reference/cli/dstack/init.md) grants the `dstack` server access by uploading the current user's default -Git credentials, ensuring that dstack can clone the Git repo when running the container. - -To use custom credentials, pass them directly with `--token` (GitHub token) or `--git-identity` (path to a private SSH -key). - -> The `dstack` server stores Git credentials individually for each `dstack` user and encrypts them if encryption is -> enabled. - -### .gitignore and folder size - -[`dstack apply`](../reference/cli/dstack/apply.md) uploads to the `dstack` server only local changes. - -Uploads are limited to 2MB. Use `.gitignore` to exclude unnecessary files from being uploaded. -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). - -## Specify the repo - -By default, `dstack apply` uses the current directory as a repo if it is already initialized. -You can change this by explicitly specifying the repo to use for `dstack apply`. - -### Pass the repo path - -To use a specific directory as the repo, specify its path using `-P` (or `--repo`): - -
- -```shell -$ dstack apply -f .dstack.yml -P ../parent_dir -``` - -
- -### Pass a remote Git repo URL - -To use a remote Git repo without cloning it locally, specify the repo URL with `-P` (or `--repo`): - -
- -```shell -$ dstack apply -f .dstack.yml -P https://github.com/dstackai/dstack.git -``` - -
- -### Automatic initialization - -When specifying the repo with `-P` (or `--repo`), the repo is initialized automatically and -`dstack init` is not required. -If you use a private Git repo, you can pass Git credentials to `dstack apply` using `--token` or `--git-identity`. - -### Do not use a repo - -To run a configuration without a repo (the `/workflow` directory inside the container will be empty) if it is already initialized, use `--no-repo`: - -
- -```shell -$ dstack apply -f .dstack.yml --no-repo -``` - -
- - - -## What's next? - -1. Read about [dev environments](../concepts/dev-environments.md), [tasks](../concepts/tasks.md), [services](../concepts/services.md) diff --git a/docs/docs/concepts/services.md b/docs/docs/concepts/services.md index 442f47618d..0f2d835688 100644 --- a/docs/docs/concepts/services.md +++ b/docs/docs/concepts/services.md @@ -588,12 +588,7 @@ resources: ### 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. - -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. +Sometimes, when you run a service, you may want to mount local files. This is possible via the [`files`](../reference/dstack.yml/task.md#_files) property. Each entry maps a local directory or file to a path inside the container. @@ -625,14 +620,12 @@ resources: Each entry maps a local directory or file to a path inside the container. Both local and container paths can be relative or absolute. -- If the local path is relative, it’s resolved relative to the configuration file. -- If the container path is relative, it’s resolved relative to `/workflow`. +If the local path is relative, it’s resolved relative to the configuration file. If the container path is relative, it’s resolved relative to `/workflow`. The container path is optional. If not specified, it will be automatically calculated. -
```yaml @@ -659,27 +652,99 @@ resources:
-Note: If you want to use `files` without mounting the entire repo directory, -make sure to pass `--no-repo` when running `dstack apply`: +??? info "Upload limit and excludes" + Whether its a file or folder, each entry is limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files + by listing it via `.gitignore` or `.dstackignore`. + The 2MB upload limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. -
+### Repos -```shell -$ dstack apply -f examples/.dstack.yml --no-repo +Sometimes, you may want to mount an entire Git repo inside the container. + +Imagine you have a cloned Git repo containing an `examples` subdirectory with a `.dstack.yml` file: + + + +
+ +```yaml +type: service +name: llama-2-7b-service + +repos: + # Mounts the parent directory of `examples` (must be a Git repo) + # to `/workflow` (the default working directory) + - .. + +python: 3.12 + +env: + - HF_TOKEN + - MODEL=NousResearch/Llama-2-7b-chat-hf +commands: + - uv pip install vllm + - python -m vllm.entrypoints.openai.api_server --model $MODEL --port 8000 +port: 8000 + +resources: + gpu: 24GB ```
-??? info ".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. +When you run it, `dstack` fetches the repo on the instance, applies your local changes, and mounts it—so the container matches your local repo. +The local path can be either relative to the configuration file or absolute. + +??? info "Path" + Currently, `dstack` always mounts the repo to `/workflow` inside the container. It's the default working directory. + Starting with the next release, it will be possible to specify a custom container path. + +??? info "Local diff limit and excludes" + The local diff size is limited to 2MB. To avoid exceeding this limit, exclude unnecessary files + via `.gitignore` or `.dstackignore`. + The 2MB local diff limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. + +??? info "Repo URL" + + Sometimes you may want to mount a Git repo without cloning it locally. In this case, simply provide a URL in `repos`: + + + +
+ + ```yaml + type: service + name: llama-2-7b-service + + repos: + # Clone the specified repo to `/workflow` (the default working directory) + - https://github.com/dstackai/dstack + + python: 3.12 + + env: + - HF_TOKEN + - MODEL=NousResearch/Llama-2-7b-chat-hf + commands: + - uv pip install vllm + - python -m vllm.entrypoints.openai.api_server --model $MODEL --port 8000 + port: 8000 + + resources: + gpu: 24GB + ``` + +
+ +??? info "Private repos" + If a Git repo is private, `dstack` will automatically try to use your default Git credentials (from + `~/.ssh/config` or `~/.config/gh/hosts.yml`). + + If you want to use custom credentials, you can provide them with [`dstack init`](../reference/cli/dstack/init.md). + +> Currently, you can configure up to one repo per run configuration. -!!! warning "Experimental" - The `files` feature is experimental. Feedback is highly appreciated. - ### Retry policy By default, if `dstack` can't find capacity, or the service exits with an error, or the instance is interrupted, the run will fail. @@ -858,7 +923,7 @@ The rolling deployment stops when all replicas are updated or when a new deploym ??? info "Supported properties" - Rolling deployment supports changes to the following properties: `port`, `probes`, `resources`, `volumes`, `docker`, `files`, `image`, `user`, `privileged`, `entrypoint`, `working_dir`, `python`, `nvcc`, `single_branch`, `env`, `shell`, `commands`, as well as changes to [repo](repos.md) or [file](#files) contents. + Rolling deployment supports changes to the following properties: `port`, `probes`, `resources`, `volumes`, `docker`, `files`, `image`, `user`, `privileged`, `entrypoint`, `working_dir`, `python`, `nvcc`, `single_branch`, `env`, `shell`, `commands`, as well as changes to [repo](#repos) or [file](#files) contents. Changes to `replicas` and `scaling` can be applied without redeploying replicas. @@ -870,7 +935,7 @@ The rolling deployment stops when all replicas are updated or when a new deploym --8<-- "docs/concepts/snippets/manage-runs.ext" !!! info "What's next?" - 1. Read about [dev environments](dev-environments.md), [tasks](tasks.md), and [repos](repos.md) + 1. Read about [dev environments](dev-environments.md) and [tasks](tasks.md) 2. Learn how to manage [fleets](fleets.md) 3. See how to set up [gateways](gateways.md) 4. Check the [TGI :material-arrow-top-right-thin:{ .external }](../../examples/inference/tgi/index.md){:target="_blank"}, diff --git a/docs/docs/concepts/tasks.md b/docs/docs/concepts/tasks.md index e5925044d1..df0e6e056f 100644 --- a/docs/docs/concepts/tasks.md +++ b/docs/docs/concepts/tasks.md @@ -462,10 +462,7 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above), ### Files -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. +Sometimes, when you run a task, you may want to mount local files. This is possible via the [`files`](../reference/dstack.yml/task.md#_files) property. Each entry maps a local directory or file to a path inside the container.
@@ -500,8 +497,7 @@ resources: Each entry maps a local directory or file to a path inside the container. Both local and container paths can be relative or absolute. -- If the local path is relative, it’s resolved relative to the configuration file. -- If the container path is relative, it’s resolved relative to `/workflow`. +If the local path is relative, it’s resolved relative to the configuration file. If the container path is relative, it’s resolved relative to `/workflow`. The container path is optional. If not specified, it will be automatically calculated. @@ -538,26 +534,108 @@ resources:
-Note: If you want to use `files` without mounting the entire repo directory, -make sure to pass `--no-repo` when running `dstack apply`: +??? info "Upload limit and excludes" + Whether its a file or folder, each entry is limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files + by listing it via `.gitignore` or `.dstackignore`. + The 2MB upload limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. -
+### Repos -```shell -$ dstack apply -f examples/.dstack.yml --no-repo +Sometimes, you may want to mount an entire Git repo inside the container. + +Imagine you have a cloned Git repo containing an `examples` subdirectory with a `.dstack.yml` file: + + + +
+ +```yaml +type: task +name: trl-sft + +repos: + # Mounts the parent directory of `examples` (must be a Git repo) + # to `/workflow` (the default working directory) + - .. + +python: 3.12 + +env: + - HF_TOKEN + - HF_HUB_ENABLE_HF_TRANSFER=1 + - MODEL=Qwen/Qwen2.5-0.5B + - DATASET=stanfordnlp/imdb + +commands: + - uv pip install trl + - | + trl sft \ + --model_name_or_path $MODEL --dataset_name $DATASET + --num_processes $DSTACK_GPUS_PER_NODE + +resources: + gpu: H100:1 ```
-??? info ".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. +When you run it, `dstack` fetches the repo on the instance, applies your local changes, and mounts it—so the container matches your local repo. + +The local path can be either relative to the configuration file or absolute. + +??? info "Path" + Currently, `dstack` always mounts the repo to `/workflow` inside the container. It's the default working directory. + Starting with the next release, it will be possible to specify a custom container path. + +??? info "Local diff limit and excludes" + The local diff size is limited to 2MB. To avoid exceeding this limit, exclude unnecessary files + via `.gitignore` or `.dstackignore`. + The 2MB local diff limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. + +??? info "Repo URL" + Sometimes you may want to mount a Git repo without cloning it locally. In this case, simply provide a URL in `repos`: + + + +
+ + ```yaml + type: task + name: trl-sft + + repos: + # Clone the specified repo to `/workflow` (the default working directory) + - https://github.com/dstackai/dstack + + python: 3.12 + + env: + - HF_TOKEN + - HF_HUB_ENABLE_HF_TRANSFER=1 + - MODEL=Qwen/Qwen2.5-0.5B + - DATASET=stanfordnlp/imdb + + commands: + - uv pip install trl + - | + trl sft \ + --model_name_or_path $MODEL --dataset_name $DATASET + --num_processes $DSTACK_GPUS_PER_NODE + + resources: + gpu: H100:1 + ``` + +
+ +??? info "Private repos" + If a Git repo is private, `dstack` will automatically try to use your default Git credentials (from + `~/.ssh/config` or `~/.config/gh/hosts.yml`). + + If you want to use custom credentials, you can provide them with [`dstack init`](../reference/cli/dstack/init.md). + +> Currently, you can configure up to one repo per run configuration. -!!! warning "Experimental" - The `files` feature is experimental. Feedback is highly appreciated. - ### Retry policy By default, if `dstack` can't find capacity, or the task exits with an error, or the instance is interrupted, @@ -720,6 +798,6 @@ via the [`spot_policy`](../reference/dstack.yml/task.md#spot_policy) property. I --8<-- "docs/concepts/snippets/manage-runs.ext" !!! info "What's next?" - 1. Read about [dev environments](dev-environments.md), [services](services.md), and [repos](repos.md) + 1. Read about [dev environments](dev-environments.md) and [services](services.md) 2. Learn how to manage [fleets](fleets.md) 3. Check the [Axolotl](/examples/single-node-training/axolotl) example diff --git a/docs/docs/guides/server-deployment.md b/docs/docs/guides/server-deployment.md index ee47f481a4..80f34a3351 100644 --- a/docs/docs/guides/server-deployment.md +++ b/docs/docs/guides/server-deployment.md @@ -224,7 +224,7 @@ To store logs using GCP Logging, set the `DSTACK_SERVER_GCP_LOGGING_PROJECT` env ## File storage -When using [repos](../concepts/repos.md), the `dstack` CLI uploads uncommitted local files and diffs to the server so that you can have access to them within runs. By default, the files are stored in the DB and each upload is limited to 2MB. You can configure an object storage to be used for uploads and increase the default limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable +When using [files](../concepts/dev-environments.md#files) or [repos](../concepts/dev-environments.md#repos), `dstack` uploads local files and diffs to the server so that you can have access to them within runs. By default, the files are stored in the DB and each upload is limited to 2MB. You can configure an object storage to be used for uploads and increase the default limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable ### S3 diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md index 60c8ea09df..5a0b3c3df7 100644 --- a/docs/docs/quickstart.md +++ b/docs/docs/quickstart.md @@ -14,9 +14,6 @@ $ mkdir quickstart && cd quickstart
-> 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. @@ -216,18 +213,6 @@ $ mkdir quickstart && cd quickstart `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. diff --git a/docs/docs/reference/cli/dstack/init.md b/docs/docs/reference/cli/dstack/init.md index e70bef6ac0..c89be94686 100644 --- a/docs/docs/reference/cli/dstack/init.md +++ b/docs/docs/reference/cli/dstack/init.md @@ -1,13 +1,10 @@ # dstack init -This command initializes the current directory as a `dstack` [repo](../../../concepts/repos.md). -The directory must be a cloned Git repository. +If you’re using private Git repos in your runs via [`repos`](../../../concepts/dev-environments.md#repos), +`dstack` will automatically try to use your default Git credentials (from +`~/.ssh/config` or `~/.config/gh/hosts.yml`). -**Git credentials** - -`dstack init` ensures that `dstack` can access a remote Git repository. -By default, the command uses the user's default Git credentials. These can be overridden with -`--git-identity` (private SSH key) or `--token` (OAuth token). +To provide custom Git credentials, run `dstack init`.
@@ -17,3 +14,7 @@ $ dstack init --help ```
+ +You can set credentials with `--git-identity` (private SSH key) or `--token` (OAuth token). + +Run `dstack init` in the repo’s directory, or pass the repo path or URL with `--repo` (or `-P`). diff --git a/examples/.dstack.yml b/examples/.dstack.yml index daded20730..dc8a9c58c3 100644 --- a/examples/.dstack.yml +++ b/examples/.dstack.yml @@ -4,9 +4,9 @@ name: cursor python: 3.12 ide: cursor -files: - - .:examples - - ~/.ssh/id_rsa:/root/.ssh/id_rsa +# Mount the repo directory to `/workflow` (the default working directory) +repos: + - .. resources: - gpu: 1 + gpu: 1 diff --git a/mkdocs.yml b/mkdocs.yml index 7d93d96239..21ae3802fc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -127,6 +127,7 @@ plugins: 'examples/fine-tuning/trl/index.md': 'examples/single-node-training/trl/index.md' 'examples/fine-tuning/axolotl/index.md': 'examples/single-node-training/axolotl/index.md' 'blog/efa.md': 'examples/clusters/efa/index.md' + 'docs/concepts/repos.md': 'docs/concepts/dev-environments.md#repos' - typeset - gen-files: scripts: # always relative to mkdocs.yml @@ -224,7 +225,6 @@ nav: - Services: docs/concepts/services.md - Fleets: docs/concepts/fleets.md - Volumes: docs/concepts/volumes.md - - Repos: docs/concepts/repos.md - Secrets: docs/concepts/secrets.md - Projects: docs/concepts/projects.md - Gateways: docs/concepts/gateways.md