diff --git a/docs/docs/concepts/dev-environments.md b/docs/docs/concepts/dev-environments.md index 7a1ab9690b..8a8512e594 100644 --- a/docs/docs/concepts/dev-environments.md +++ b/docs/docs/concepts/dev-environments.md @@ -288,11 +288,23 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above), ??? info "System environment variables" The following environment variables are available in any run by default: - | Name | Description | - |-------------------------|-----------------------------------------| - | `DSTACK_RUN_NAME` | The name of the run | - | `DSTACK_REPO_ID` | The ID of the repo | - | `DSTACK_GPUS_NUM` | The total number of GPUs in the run | + | Name | Description | + |-------------------------|--------------------------------------------------| + | `DSTACK_RUN_NAME` | The name of the run | + | `DSTACK_REPO_ID` | The ID of the repo | + | `DSTACK_GPUS_NUM` | The total number of GPUs in the run | + | `DSTACK_WORKING_DIR` | The working directory of the run | + | `DSTACK_REPO_DIR` | The directory where the repo is mounted (if any) | + +### Working directory + +If `working_dir` is not specified, it defaults to `/workflow`. + +The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`). + + + + ### Files @@ -333,7 +345,7 @@ ide: vscode -??? info "Upload limit and excludes" +??? info "File size" 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. @@ -364,14 +376,36 @@ When you run it, `dstack` fetches the repo on the instance, applies your local c 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 "Repo directory" + By default, `dstack` mounts the repo to `/workflow` (the default working directory). + + + + You can override the repo directory using either a relative or an absolute path: + +
+ + ```yaml + type: dev-environment + name: vscode + + repos: + # Mounts the parent directory of `examples` (must be a Git repo) + # to `/my-repo` + - ..:/my-repo + + ide: vscode + ``` + +
+ + If the path is relative, it is resolved against [working directory](#working-directory). + -??? 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 size" + The repo size is not limited. However, local changes are limited to 2MB. + To avoid exceeding this limit, exclude unnecessary files using `.gitignore` or `.dstackignore`. + You can increase the 2MB limit 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`: diff --git a/docs/docs/concepts/services.md b/docs/docs/concepts/services.md index 0f2d835688..e8bef93ec9 100644 --- a/docs/docs/concepts/services.md +++ b/docs/docs/concepts/services.md @@ -115,6 +115,9 @@ If [authorization](#authorization) is not disabled, the service endpoint require ## Configuration options +!!! info "No commands" + If `commands` are not specified, `dstack` runs `image`’s entrypoint (or fails if none is set). + ### Replicas and scaling By default, `dstack` runs a single replica of the service. @@ -578,14 +581,29 @@ resources: ??? info "System environment variables" The following environment variables are available in any run by default: - | Name | Description | - |-------------------------|-----------------------------------------| - | `DSTACK_RUN_NAME` | The name of the run | - | `DSTACK_REPO_ID` | The ID of the repo | - | `DSTACK_GPUS_NUM` | The total number of GPUs in the run | + | Name | Description | + |-------------------------|--------------------------------------------------| + | `DSTACK_RUN_NAME` | The name of the run | + | `DSTACK_REPO_ID` | The ID of the repo | + | `DSTACK_GPUS_NUM` | The total number of GPUs in the run | + | `DSTACK_WORKING_DIR` | The working directory of the run | + | `DSTACK_REPO_DIR` | The directory where the repo is mounted (if any) | +### Working directory + +If `working_dir` is not specified, it defaults to `/workflow`. + +!!! info "No commands" + If you’re using a custom `image` without `commands`, then `working_dir` is taken from `image`. + +The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`). + + + + + ### Files 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. @@ -652,7 +670,7 @@ resources: -??? info "Upload limit and excludes" +??? info "File size" 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. @@ -696,14 +714,46 @@ When you run it, `dstack` fetches the repo on the instance, applies your local c 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 "Repo directory" + By default, `dstack` mounts the repo to `/workflow` (the default working directory). + + + + You can override the repo directory using either a relative or an absolute path: + +
+ + ```yaml + type: service + name: llama-2-7b-service + + repos: + # Mounts the parent directory of `examples` (must be a Git repo) + # to `/my-repo` + - ..:/my-repo + + 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 + ``` + +
+ + If the path is relative, it is resolved against `working_dir`. -??? 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 size" + The repo size is not limited. However, local changes are limited to 2MB. + To avoid exceeding this limit, exclude unnecessary files using `.gitignore` or `.dstackignore`. + You can increase the 2MB limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable. ??? info "Repo URL" diff --git a/docs/docs/concepts/tasks.md b/docs/docs/concepts/tasks.md index df0e6e056f..add535ecdb 100644 --- a/docs/docs/concepts/tasks.md +++ b/docs/docs/concepts/tasks.md @@ -69,6 +69,9 @@ Launching `axolotl-train`... ## Configuration options +!!! info "No commands" + If `commands` are not specified, `dstack` runs `image`’s entrypoint (or fails if none is set). + ### Ports A task can configure ports. In this case, if the task is running an application on a port, `dstack apply` @@ -456,9 +459,24 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above), | `DSTACK_NODES_NUM` | The number of nodes in the run | | `DSTACK_GPUS_PER_NODE` | The number of GPUs per node | | `DSTACK_NODE_RANK` | The rank of the node | - | `DSTACK_MASTER_NODE_IP` | The internal IP address of the master node | + | `DSTACK_MASTER_NODE_IP` | The internal IP address of the master node | | `DSTACK_NODES_IPS` | The list of internal IP addresses of all nodes delimited by "\n" | | `DSTACK_MPI_HOSTFILE` | The path to a pre-populated MPI hostfile | + | `DSTACK_WORKING_DIR` | The working directory of the run | + | `DSTACK_REPO_DIR` | The directory where the repo is mounted (if any) | + +### Working directory + +If `working_dir` is not specified, it defaults to `/workflow`. + +!!! info "No commands" + If you’re using a custom `image` without `commands`, then `working_dir` is taken from `image`. + +The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`). + + + + ### Files @@ -534,7 +552,7 @@ resources: -??? info "Upload limit and excludes" +??? info "File size" 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. @@ -583,14 +601,51 @@ When you run it, `dstack` fetches the repo on the instance, applies your local c 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 "Repo directory" + By default, `dstack` mounts the repo to `/workflow` (the default working directory). + + + + You can override the repo directory using either a relative or an absolute path: + +
+ + ```yaml + type: task + name: trl-sft + + repos: + # Mounts the parent directory of `examples` (must be a Git repo) + # to `/my-repo` + - ..:/my-repo + + 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 + ``` + +
+ + If the path is relative, it is resolved against [working directory](#working-directory). -??? 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 size" + The repo size is not limited. However, local changes are limited to 2MB. + To avoid exceeding this limit, exclude unnecessary files using `.gitignore` or `.dstackignore`. + You can increase the 2MB limit 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`: