Skip to content

Commit 65771dd

Browse files
peterschmidt85peterschmidt85
authored
[Docs] Reflect the repo and working directory changes
Relates to #3041
1 parent fdd8646 commit 65771dd

3 files changed

Lines changed: 174 additions & 35 deletions

File tree

‎docs/docs/concepts/dev-environments.md‎

Lines changed: 47 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -288,11 +288,23 @@ If you don't assign a value to an environment variable (see `HF_TOKEN` above),
288288
??? info "System environment variables"
289289
The following environment variables are available in any run by default:
290290

291-
| Name | Description |
292-
|-------------------------|-----------------------------------------|
293-
| `DSTACK_RUN_NAME` | The name of the run |
294-
| `DSTACK_REPO_ID` | The ID of the repo |
295-
| `DSTACK_GPUS_NUM` | The total number of GPUs in the run |
291+
| Name | Description |
292+
|-------------------------|--------------------------------------------------|
293+
| `DSTACK_RUN_NAME` | The name of the run |
294+
| `DSTACK_REPO_ID` | The ID of the repo |
295+
| `DSTACK_GPUS_NUM` | The total number of GPUs in the run |
296+
| `DSTACK_WORKING_DIR` | The working directory of the run |
297+
| `DSTACK_REPO_DIR` | The directory where the repo is mounted (if any) |
298+
299+
### Working directory
300+
301+
If `working_dir` is not specified, it defaults to `/workflow`.
302+
303+
The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`).
304+
305+
<!-- TODO: In a future version, the default working directory will be taken from `image`. -->
306+
307+
<!-- TODO: Elaborate on `entrypoint` -->
296308

297309
### Files
298310

@@ -333,7 +345,7 @@ ide: vscode
333345
334346
</div>
335347
336-
??? info "Upload limit and excludes"
348+
??? info "File size"
337349
Whether its a file or folder, each entry is limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files
338350
by listing it via `.gitignore` or `.dstackignore`.
339351
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
364376

365377
The local path can be either relative to the configuration file or absolute.
366378

367-
??? info "Path"
368-
Currently, `dstack` always mounts the repo to `/workflow` inside the container. It's the default working directory.
369-
Starting with the next release, it will be possible to specify a custom container path.
379+
??? info "Repo directory"
380+
By default, `dstack` mounts the repo to `/workflow` (the default working directory).
381+
382+
<!-- TODO: In a future version, the default working directory will come from the image, so this should be revisited. -->
383+
384+
You can override the repo directory using either a relative or an absolute path:
385+
386+
<div editor-title="examples/.dstack.yml">
387+
388+
```yaml
389+
type: dev-environment
390+
name: vscode
391+
392+
repos:
393+
# Mounts the parent directory of `examples` (must be a Git repo)
394+
# to `/my-repo`
395+
- ..:/my-repo
396+
397+
ide: vscode
398+
```
399+
400+
</div>
401+
402+
If the path is relative, it is resolved against [working directory](#working-directory).
403+
370404
371-
??? info "Local diff limit and excludes"
372-
The local diff size is limited to 2MB. To avoid exceeding this limit, exclude unnecessary files
373-
via `.gitignore` or `.dstackignore`.
374-
The 2MB local diff limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.
405+
??? info "Repo size"
406+
The repo size is not limited. However, local changes are limited to 2MB.
407+
To avoid exceeding this limit, exclude unnecessary files using `.gitignore` or `.dstackignore`.
408+
You can increase the 2MB limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.
375409

376410
??? info "Repo URL"
377411
Sometimes you may want to mount a Git repo without cloning it locally. In this case, simply provide a URL in `repos`:

‎docs/docs/concepts/services.md‎

Lines changed: 63 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,9 @@ If [authorization](#authorization) is not disabled, the service endpoint require
115115

116116
## Configuration options
117117

118+
!!! info "No commands"
119+
If `commands` are not specified, `dstack` runs `image`’s entrypoint (or fails if none is set).
120+
118121
### Replicas and scaling
119122

120123
By default, `dstack` runs a single replica of the service.
@@ -578,14 +581,29 @@ resources:
578581
??? info "System environment variables"
579582
The following environment variables are available in any run by default:
580583

581-
| Name | Description |
582-
|-------------------------|-----------------------------------------|
583-
| `DSTACK_RUN_NAME` | The name of the run |
584-
| `DSTACK_REPO_ID` | The ID of the repo |
585-
| `DSTACK_GPUS_NUM` | The total number of GPUs in the run |
584+
| Name | Description |
585+
|-------------------------|--------------------------------------------------|
586+
| `DSTACK_RUN_NAME` | The name of the run |
587+
| `DSTACK_REPO_ID` | The ID of the repo |
588+
| `DSTACK_GPUS_NUM` | The total number of GPUs in the run |
589+
| `DSTACK_WORKING_DIR` | The working directory of the run |
590+
| `DSTACK_REPO_DIR` | The directory where the repo is mounted (if any) |
586591

587592
<!-- TODO: Ellaborate on using environment variables in `registry_auth` -->
588593

594+
### Working directory
595+
596+
If `working_dir` is not specified, it defaults to `/workflow`.
597+
598+
!!! info "No commands"
599+
If you’re using a custom `image` without `commands`, then `working_dir` is taken from `image`.
600+
601+
The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`).
602+
603+
<!-- TODO: In a future version, the default working directory will be taken from `image`. -->
604+
605+
<!-- TODO: Elaborate on `entrypoint` -->
606+
589607
### Files
590608

591609
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:
652670
653671
</div>
654672
655-
??? info "Upload limit and excludes"
673+
??? info "File size"
656674
Whether its a file or folder, each entry is limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files
657675
by listing it via `.gitignore` or `.dstackignore`.
658676
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
696714

697715
The local path can be either relative to the configuration file or absolute.
698716

699-
??? info "Path"
700-
Currently, `dstack` always mounts the repo to `/workflow` inside the container. It's the default working directory.
701-
Starting with the next release, it will be possible to specify a custom container path.
717+
??? info "Repo directory"
718+
By default, `dstack` mounts the repo to `/workflow` (the default working directory).
719+
720+
<!-- TODO: In a future version, the default working directory will come from the image, so this should be revisited. -->
721+
722+
You can override the repo directory using either a relative or an absolute path:
723+
724+
<div editor-title="examples/.dstack.yml">
725+
726+
```yaml
727+
type: service
728+
name: llama-2-7b-service
729+
730+
repos:
731+
# Mounts the parent directory of `examples` (must be a Git repo)
732+
# to `/my-repo`
733+
- ..:/my-repo
734+
735+
python: 3.12
736+
737+
env:
738+
- HF_TOKEN
739+
- MODEL=NousResearch/Llama-2-7b-chat-hf
740+
commands:
741+
- uv pip install vllm
742+
- python -m vllm.entrypoints.openai.api_server --model $MODEL --port 8000
743+
port: 8000
744+
745+
resources:
746+
gpu: 24GB
747+
```
748+
749+
</div>
750+
751+
If the path is relative, it is resolved against `working_dir`.
702752

703-
??? info "Local diff limit and excludes"
704-
The local diff size is limited to 2MB. To avoid exceeding this limit, exclude unnecessary files
705-
via `.gitignore` or `.dstackignore`.
706-
The 2MB local diff limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.
753+
??? info "Repo size"
754+
The repo size is not limited. However, local changes are limited to 2MB.
755+
To avoid exceeding this limit, exclude unnecessary files using `.gitignore` or `.dstackignore`.
756+
You can increase the 2MB limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.
707757

708758
??? info "Repo URL"
709759

‎docs/docs/concepts/tasks.md‎

Lines changed: 64 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@ Launching `axolotl-train`...
6969

7070
## Configuration options
7171

72+
!!! info "No commands"
73+
If `commands` are not specified, `dstack` runs `image`’s entrypoint (or fails if none is set).
74+
7275
### Ports
7376

7477
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),
456459
| `DSTACK_NODES_NUM` | The number of nodes in the run |
457460
| `DSTACK_GPUS_PER_NODE` | The number of GPUs per node |
458461
| `DSTACK_NODE_RANK` | The rank of the node |
459-
| `DSTACK_MASTER_NODE_IP` | The internal IP address of the master node |
462+
| `DSTACK_MASTER_NODE_IP` | The internal IP address of the master node |
460463
| `DSTACK_NODES_IPS` | The list of internal IP addresses of all nodes delimited by "\n" |
461464
| `DSTACK_MPI_HOSTFILE` | The path to a pre-populated MPI hostfile |
465+
| `DSTACK_WORKING_DIR` | The working directory of the run |
466+
| `DSTACK_REPO_DIR` | The directory where the repo is mounted (if any) |
467+
468+
### Working directory
469+
470+
If `working_dir` is not specified, it defaults to `/workflow`.
471+
472+
!!! info "No commands"
473+
If you’re using a custom `image` without `commands`, then `working_dir` is taken from `image`.
474+
475+
The `working_dir` must be an absolute path. The tilde (`~`) is supported (e.g., `~/my-working-dir`).
476+
477+
<!-- TODO: In a future version, the default working directory will be taken from `image`. -->
478+
479+
<!-- TODO: Elaborate on `entrypoint` -->
462480

463481
### Files
464482

@@ -534,7 +552,7 @@ resources:
534552
535553
</div>
536554
537-
??? info "Upload limit and excludes"
555+
??? info "File size"
538556
Whether its a file or folder, each entry is limited to 2MB. To avoid exceeding this limit, make sure to exclude unnecessary files
539557
by listing it via `.gitignore` or `.dstackignore`.
540558
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
583601

584602
The local path can be either relative to the configuration file or absolute.
585603

586-
??? info "Path"
587-
Currently, `dstack` always mounts the repo to `/workflow` inside the container. It's the default working directory.
588-
Starting with the next release, it will be possible to specify a custom container path.
604+
??? info "Repo directory"
605+
By default, `dstack` mounts the repo to `/workflow` (the default working directory).
606+
607+
<!-- TODO: In a future version, the default working directory will come from the image, so this should be revisited. -->
608+
609+
You can override the repo directory using either a relative or an absolute path:
610+
611+
<div editor-title="examples/.dstack.yml">
612+
613+
```yaml
614+
type: task
615+
name: trl-sft
616+
617+
repos:
618+
# Mounts the parent directory of `examples` (must be a Git repo)
619+
# to `/my-repo`
620+
- ..:/my-repo
621+
622+
python: 3.12
623+
624+
env:
625+
- HF_TOKEN
626+
- HF_HUB_ENABLE_HF_TRANSFER=1
627+
- MODEL=Qwen/Qwen2.5-0.5B
628+
- DATASET=stanfordnlp/imdb
629+
630+
commands:
631+
- uv pip install trl
632+
- |
633+
trl sft \
634+
--model_name_or_path $MODEL --dataset_name $DATASET
635+
--num_processes $DSTACK_GPUS_PER_NODE
636+
637+
resources:
638+
gpu: H100:1
639+
```
640+
641+
</div>
642+
643+
If the path is relative, it is resolved against [working directory](#working-directory).
589644
590-
??? info "Local diff limit and excludes"
591-
The local diff size is limited to 2MB. To avoid exceeding this limit, exclude unnecessary files
592-
via `.gitignore` or `.dstackignore`.
593-
The 2MB local diff limit can be increased by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.
645+
??? info "Repo size"
646+
The repo size is not limited. However, local changes are limited to 2MB.
647+
To avoid exceeding this limit, exclude unnecessary files using `.gitignore` or `.dstackignore`.
648+
You can increase the 2MB limit by setting the `DSTACK_SERVER_CODE_UPLOAD_LIMIT` environment variable.
594649

595650
??? info "Repo URL"
596651
Sometimes you may want to mount a Git repo without cloning it locally. In this case, simply provide a URL in `repos`:

0 commit comments

Comments
 (0)