From 7e950b966b72bffb67c365ec7af1c4c32e7110bc Mon Sep 17 00:00:00 2001 From: Egor Sklyarov Date: Thu, 3 Aug 2023 19:00:29 +0400 Subject: [PATCH 1/4] docs: split .dstack.yml in separate pages --- .../configurations/dev-environment.md | 77 +++++++++++++++++++ docs/docs/reference/configurations/service.md | 56 ++++++++++++++ docs/docs/reference/configurations/task.md | 64 +++++++++++++++ docs/docs/reference/dstack.yml.md | 29 +------ mkdocs.yml | 5 +- 5 files changed, 205 insertions(+), 26 deletions(-) create mode 100644 docs/docs/reference/configurations/dev-environment.md create mode 100644 docs/docs/reference/configurations/service.md create mode 100644 docs/docs/reference/configurations/task.md diff --git a/docs/docs/reference/configurations/dev-environment.md b/docs/docs/reference/configurations/dev-environment.md new file mode 100644 index 000000000..6ec42194b --- /dev/null +++ b/docs/docs/reference/configurations/dev-environment.md @@ -0,0 +1,77 @@ +# type: dev-environment (.dstack.yml) + +Dev environment allows to connect to remote virtual machine from VS Code Desktop. + +!!! info "Filename" + The configuration file must be named with the suffix `.dstack.yml`. For example, + you can name the configuration file `.dstack.yml` or `dev.dstack.yml`. You can define + these configurations anywhere within your project. + + Each folder may have one default configuration file named `.dstack.yml`. + +## Runtime properties: + +- `ide` - The IDE to run. Currently only `vscode` is supported. +- `env` - (Optional) The list or mapping of environment variables. Interpolation `PATH=/bin/my:$PATH` is supported. +- `ports` - (Optional) The list of exposed ports or mappings. Allowed formats: + - `8000` - expose port `8000` and run ssh tunnel locally on the exact same port. + - `3333:8000` - expose port `8000` and run ssh tunnel locally on port `3333`. + - `*:8000` - expose port `8000` and run ssh tunnel locally on first available port starting from `8000`. +- `python` - (Optional) The preinstalled major python version (from `3.7` to `3.11`). Mutually exclusive with `image` property. +- `setup` - (Optional) The list of commands to be executed once for the environment. +- `init` - (Optional) The list of commands to be executed every restart of the environment. + +## Custom docker image properties: + +- `image` - (Optional) The docker image. Mutually exclusive with `python` property. +- `entrypoint` - (Optional) The docker entrypoint to interpret the commands (typically `/bin/bash -i -c`). +- `registry_auth` - (Optional) The credentials to pull the image from private registry. + - `username` - The username. Supports secrets interpolation `${{ secrets.GHCR_USER }}`. + - `password` - The password or token. Supports secrets interpolation `${{ secrets.GHCR_TOKEN }}`. +- `home_dir` - (Optional) The home directory inside the container. Defaults to `/root`. + +!!! info "Requirements" + Custom docker image must have `sshd`. + You could pre-install `openssh-server` in your `Dockerfile` or use the `build` property. + +## Optimization properties: + +- `cache` - (Optional) The list of directories to cache between the environment restarts. Both absolute and relative paths are supported. +- `build` - (Optional) The list of commands to run during build stage. You must call `dstack build` first or use flag `dstack run --build`. + +!!! info "Note" + Build is an experimental feature. Performance gain depends on the type of workloads and specific cloud provider. + +## Examples: + +### Minimal configuration + +```yaml +type: dev-environment +ide: vscode +``` + +### Custom docker image + +```yaml +type: dev-environment +ide: vscode +image: ghcr.io/huggingface/text-generation-inference:0.9.3 +build: + - apt-get update + - DEBIAN_FRONTEND=noninteractive apt-get install -y openssh-server + - rm -rf /var/lib/apt/lists/* +env: + - MODEL_ID=meta-llama/Llama-2-7b-chat-hf + - HOSTNAME=0.0.0.0 + - PORT=8080 + # HUGGING_FACE_HUB_TOKEN is stored in secrets +ports: + - 8080 +``` + +[//]: # (TODO: describe profile policies defaults) + +[//]: # (TODO: Add examples) + +[//]: # (TODO: Mention here or somewhere else of how it works. What base image is used, how ports are forwarded, etc.) diff --git a/docs/docs/reference/configurations/service.md b/docs/docs/reference/configurations/service.md new file mode 100644 index 000000000..ccc0d1544 --- /dev/null +++ b/docs/docs/reference/configurations/service.md @@ -0,0 +1,56 @@ +# type: service (.dstack.yml) + +Service allows to run an application and expose it over HTTP to global internet through the gateway. + +!!! info "Filename" + The configuration file must be named with the suffix `.dstack.yml`. For example, + you can name the configuration file `.dstack.yml` or `service.dstack.yml`. You can define + these configurations anywhere within your project. + + Each folder may have one default configuration file named `.dstack.yml`. + +## Runtime properties: + +- `commands` - The list of commands to be executed every restart of the environment. +- `gateway` - The gateway IP address or domain. Supports secrets interpolation `${{ secrets.GATEWAY_IP }}`. +- `port` - The exposed port or mapping. Allowed formats: + - `8000` - expose port `8000` at gateway's port `80`. + - `3333:8000` - expose port `8000` at gateway's port `3333`. +- `env` - (Optional) The list or mapping of environment variables. Interpolation `PATH=/bin/my:$PATH` is supported. +- `python` - (Optional) The preinstalled major python version (from `3.7` to `3.11`). Mutually exclusive with `image` property. +- `setup` - (Optional) The list of commands to be executed once for the environment. + +## Custom docker image properties: + +- `image` - (Optional) The docker image. Mutually exclusive with `python` property. +- `entrypoint` - (Optional) The docker entrypoint to interpret the commands (typically `/bin/bash -i -c`). +- `registry_auth` - (Optional) The credentials to pull the image from private registry. + - `username` - The username. Supports secrets interpolation `${{ secrets.GHCR_USER }}`. + - `password` - The password or token. Supports secrets interpolation `${{ secrets.GHCR_TOKEN }}`. +- `home_dir` - (Optional) The home directory inside the container. Defaults to `/root`. + +## Optimization properties: + +- `cache` - (Optional) The list of directories to cache between the environment restarts. Both absolute and relative paths are supported. +- `build` - (Optional) The list of commands to run during build stage. You must call `dstack build` first or use flag `dstack run --build`. + +!!! info "Note" + Build is an experimental feature. Performance gain depends on the type of workloads and specific cloud provider. + +## Examples: + +### Simple web server + +```yaml +type: service +gateway: ${{ secrets.GATEWAY_IP }} +port: 8000 +commands: + - python -m http.server 8000 +``` + +[//]: # (TODO: describe profile policies defaults) + +[//]: # (TODO: Add examples) + +[//]: # (TODO: Mention here or somewhere else of how it works. What base image is used, how ports are forwarded, etc.) diff --git a/docs/docs/reference/configurations/task.md b/docs/docs/reference/configurations/task.md new file mode 100644 index 000000000..04ed19b65 --- /dev/null +++ b/docs/docs/reference/configurations/task.md @@ -0,0 +1,64 @@ +# type: task (.dstack.yml) + +Task allows to run commands non-interactively: from fine-tuning to serving. + +!!! info "Filename" + The configuration file must be named with the suffix `.dstack.yml`. For example, + you can name the configuration file `.dstack.yml` or `task.dstack.yml`. You can define + these configurations anywhere within your project. + + Each folder may have one default configuration file named `.dstack.yml`. + +## Runtime properties: + +- `commands` - The list of commands to be executed every restart of the environment. +- `env` - (Optional) The list or mapping of environment variables. Interpolation `PATH=/bin/my:$PATH` is supported. +- `ports` - (Optional) The list of exposed ports or mappings. Allowed formats: + - `8000` - expose port `8000` and run ssh tunnel locally on the exact same port. + - `3333:8000` - expose port `8000` and run ssh tunnel locally on port `3333`. + - `*:8000` - expose port `8000` and run ssh tunnel locally on first available port starting from `8000`. +- `python` - (Optional) The preinstalled major python version (from `3.7` to `3.11`). Mutually exclusive with `image` property. +- `setup` - (Optional) The list of commands to be executed once for the environment. + +## Custom docker image properties: + +- `image` - (Optional) The docker image. Mutually exclusive with `python` property. +- `entrypoint` - (Optional) The docker entrypoint to interpret the commands (typically `/bin/bash -i -c`). +- `registry_auth` - (Optional) The credentials to pull the image from private registry. + - `username` - The username. Supports secrets interpolation `${{ secrets.GHCR_USER }}`. + - `password` - The password or token. Supports secrets interpolation `${{ secrets.GHCR_TOKEN }}`. +- `home_dir` - (Optional) The home directory inside the container. Defaults to `/root`. + +## Optimization properties: + +- `cache` - (Optional) The list of directories to cache between the environment restarts. Both absolute and relative paths are supported. +- `build` - (Optional) The list of commands to run during build stage. You must call `dstack build` first or use flag `dstack run --build`. + +!!! info "Note" + Build is an experimental feature. Performance gain depends on the type of workloads and specific cloud provider. + +## Examples: + +### Hello world + +```yaml +type: task +commands: + - echo Hello world! +``` + +### Run custom python script + +```yaml +type: task +build: + - pip install --no-cache-dir -r requirements.txt +commands: + - python train.py ${{ run.args }} +``` + +[//]: # (TODO: describe profile policies defaults) + +[//]: # (TODO: Add examples) + +[//]: # (TODO: Mention here or somewhere else of how it works. What base image is used, how ports are forwarded, etc.) diff --git a/docs/docs/reference/dstack.yml.md b/docs/docs/reference/dstack.yml.md index 41d903191..6258961c7 100644 --- a/docs/docs/reference/dstack.yml.md +++ b/docs/docs/reference/dstack.yml.md @@ -10,29 +10,8 @@ types: `dev-environment`, `task`, and `service`. Each folder may have one default configuration file named `.dstack.yml`. -Below is a full reference of all available properties. +Read more about configuration types: -- `build` - (Optional) The list of bash commands to build the environment. -- `cache` - (Optional) The directories to be cached between runs. -- `commands` - (Required if `type` is `task`). The list of bash commands to run as a task. -- `entrypoint` - (Optional) The Docker entrypoint. -- `env` - (Optional) The mapping or the list of environment variables (e.g. `PYTHONPATH: src` or `PYTHONPATH=src`). -- `gateway` - (Required if `type` is `service`) Gateway IP address or domain name. -- `ide` - (Required if `type` is `dev-environment`). Can be `vscode`. -- `image` - (Optional) The name of the Docker image. -- `init` - (Optional, only for `dev-environment` type) The list of bash commands to execute on each run. -- `port` - (Required) The service port to expose (only for `service`) -- `ports` - (Optional) The list of port numbers to expose (only for `dev-environment` and `task`). -- `python` - (Optional) The major version of Python to pre-install (e.g., `"3.11"`). Defaults to the current version installed locally. Mutually exclusive with `image`. -- `registry_auth` - (Optional) Credentials to pull the private Docker image. - - `password` - (Required) Password or access token. - - `username` - (Required) Username. -- `type` - (Required) The type of the configurations. Can be `dev-environment`, `task`, or `service`. - -[//]: # (- `home_dir` - (Optional) The absolute path to the home directory inside the container) - -[//]: # (TODO: `artifacts` aren't documented) - -[//]: # (TODO: Add examples) - -[//]: # (TODO: Mention here or somewhere else of how it works. What base image is used, how ports are forwarded, etc.) +* type: [dev-environment](configurations/dev-environment.md) +* type: [task](configurations/task.md) +* type: [service](configurations/service.md) diff --git a/mkdocs.yml b/mkdocs.yml index c808e91ba..ea001a779 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -149,7 +149,10 @@ nav: # - Artifacts: docs/guides/artifacts.md - Projects: docs/guides/projects.md - Reference: - - .dstack.yml: docs/reference/dstack.yml.md + - .dstack.yml: + - "type: dev-environment": docs/reference/configurations/dev-environment.md + - "type: task": docs/reference/configurations/task.md + - "type: service": docs/reference/configurations/service.md - profiles.yml: docs/reference/profiles.yml.md - CLI: - dstack run: docs/reference/cli/run.md From 2ca0f1b3d02e4586cf58a376500cb875565e4337 Mon Sep 17 00:00:00 2001 From: Egor Sklyarov Date: Thu, 3 Aug 2023 19:37:36 +0400 Subject: [PATCH 2/4] docs: services guide --- docs/docs/guides/services.md | 87 ++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 88 insertions(+) create mode 100644 docs/docs/guides/services.md diff --git a/docs/docs/guides/services.md b/docs/docs/guides/services.md new file mode 100644 index 000000000..6bce0c7ef --- /dev/null +++ b/docs/docs/guides/services.md @@ -0,0 +1,87 @@ +# Services + +A service is an application accessible from the global internet through the gateway. +Both cloud and local backends (behind NAT) could serve these applications. + +## Gateways + +To deploy service you need a gateway — small CPU instance with public IP address and, possibly, a domain. +Currently, dstack supports AWS, Azure, and GCP backend for gateway creation. +Use command bellow to create your first gateway. + +```shell +$ dstack gateway create --project azure + +Creating gateway, it may take some time... + NAME ADDRESS + dstack-gateway-fast-walrus 23.100.30.60 + +``` + +Now you could use this gateway for services in any project configured in the same hub, +regardless of backend type. + +Use `dstack gateway list` to view gateways in the project. Use `dstack gateway delete` to free resources. + +## Configuring a service + +Create a service configuration, declaring gateway hostname and application port. + +```yaml +type: service +gateway: 23.100.30.60 +port: 8000 +commands: + - python -m http.server 8000 +``` + +If you wouldn't like to put hostname directly to a configuration file, you could use secrets interpolation. +Firstly, create secret in the project, where you are going to run your service. + +```shell +$ dstack secrets add GATEWAY_IP 23.100.30.60 --project local +``` + +Secondly, replace gateway hostname with a variable. + +```yaml +type: service +gateway: ${{ secrets.GATEWAY_IP }} +port: 8000 +commands: + - python -m http.server 8000 +``` + +By default, the service would be available on port 80, but you could configure a mapping, e.g. to port 5001. + +```yaml +type: service +gateway: ${{ secrets.GATEWAY_IP }} +port: "5001:8000" +commands: + - python -m http.server 8000 +``` + +## Running a service + +To run a service use command below. + +```shell +$ dstack run . -f service.dstack.yml --project local +``` + +The service would be available at `http://23.100.30.60:5001`. + + +## Running multiple services through the same gateway + +You can't run multiple services at the same gateway hostname and external port. +As soon as service is down, you could reuse the same gateway hostname and external port. + +If you would like to run multiple services, there are two possible solutions: + +- Use different ports +- Use different domains + +Add DNS record for your domain, pointing to the gateway IP address. +After that you could use this domain name as a gateway hostname alias. diff --git a/mkdocs.yml b/mkdocs.yml index ea001a779..8f496a492 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -146,6 +146,7 @@ nav: - Guides: - Dev environments: docs/guides/dev-environments.md - Tasks: docs/guides/tasks.md + - Services: docs/guides/services.md # - Artifacts: docs/guides/artifacts.md - Projects: docs/guides/projects.md - Reference: From a25c3e680e0abae8aa04436daf4d3da0a3037a18 Mon Sep 17 00:00:00 2001 From: Egor Sklyarov Date: Fri, 4 Aug 2023 12:58:36 +0400 Subject: [PATCH 3/4] Improve services.md --- docs/docs/guides/services.md | 54 +++++++++++++++++------------------- 1 file changed, 25 insertions(+), 29 deletions(-) diff --git a/docs/docs/guides/services.md b/docs/docs/guides/services.md index 6bce0c7ef..de72ab433 100644 --- a/docs/docs/guides/services.md +++ b/docs/docs/guides/services.md @@ -1,13 +1,13 @@ # Services -A service is an application accessible from the global internet through the gateway. -Both cloud and local backends (behind NAT) could serve these applications. +A service is an internet-accessible application accessed through a gateway. +These applications can be hosted on both cloud and local backends (behind NAT). ## Gateways -To deploy service you need a gateway — small CPU instance with public IP address and, possibly, a domain. -Currently, dstack supports AWS, Azure, and GCP backend for gateway creation. -Use command bellow to create your first gateway. +To deploy a service, you require a gateway: a small CPU instance with a public IP address and potentially a domain. +Currently, dstack supports AWS, Azure, and GCP backends for creating gateways. +Run the following command to create your first gateway: ```shell $ dstack gateway create --project azure @@ -15,17 +15,15 @@ $ dstack gateway create --project azure Creating gateway, it may take some time... NAME ADDRESS dstack-gateway-fast-walrus 23.100.30.60 - ``` -Now you could use this gateway for services in any project configured in the same hub, -regardless of backend type. - -Use `dstack gateway list` to view gateways in the project. Use `dstack gateway delete` to free resources. +You can then use this gateway for services within any project configured on the same hub, +irrespective of the backend type. +Run `dstack gateway list` to view gateways within the project and `dstack gateway delete` to free up resources. -## Configuring a service +## Configuring Services -Create a service configuration, declaring gateway hostname and application port. +Construct a service configuration by specifying the gateway hostname and application port in a YAML format: ```yaml type: service @@ -35,14 +33,14 @@ commands: - python -m http.server 8000 ``` -If you wouldn't like to put hostname directly to a configuration file, you could use secrets interpolation. -Firstly, create secret in the project, where you are going to run your service. +To avoid directly inputting the hostname in the configuration file, you can use secret interpolation. +Begin by creating a secret in the project where your service will run: ```shell $ dstack secrets add GATEWAY_IP 23.100.30.60 --project local ``` -Secondly, replace gateway hostname with a variable. +Then replace the gateway hostname with a variable: ```yaml type: service @@ -52,7 +50,7 @@ commands: - python -m http.server 8000 ``` -By default, the service would be available on port 80, but you could configure a mapping, e.g. to port 5001. +The default service port is 80, but you can configure a mapping, such as to port 5001: ```yaml type: service @@ -62,26 +60,24 @@ commands: - python -m http.server 8000 ``` -## Running a service +## Running Services -To run a service use command below. +Execute the following command to run a service: ```shell $ dstack run . -f service.dstack.yml --project local ``` -The service would be available at `http://23.100.30.60:5001`. - - -## Running multiple services through the same gateway +The service will be accessible at `http://23.100.30.60:5001`. -You can't run multiple services at the same gateway hostname and external port. -As soon as service is down, you could reuse the same gateway hostname and external port. +## Running Multiple Services via the Same Gateway -If you would like to run multiple services, there are two possible solutions: +Running multiple services with the same gateway hostname and external port simultaneously is not possible. +However, you can reuse the same gateway hostname and external port if a service is no longer active. +If you wish to run multiple services, consider these two solutions: -- Use different ports -- Use different domains +- Utilize different ports +- Use distinct domains -Add DNS record for your domain, pointing to the gateway IP address. -After that you could use this domain name as a gateway hostname alias. +Create a DNS record for your domain, pointing it to the gateway's IP address. +Following this, you can use the domain name as an alias for the gateway hostname. From 59c45a26a2855f75932d43db9d91c52767c4eacf Mon Sep 17 00:00:00 2001 From: Egor Sklyarov Date: Fri, 4 Aug 2023 13:04:44 +0400 Subject: [PATCH 4/4] Improve configurations md files --- .../reference/configurations/dev-environment.md | 14 +++++++------- docs/docs/reference/configurations/service.md | 10 +++++----- docs/docs/reference/configurations/task.md | 14 +++++++------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/docs/reference/configurations/dev-environment.md b/docs/docs/reference/configurations/dev-environment.md index 6ec42194b..0d65f4661 100644 --- a/docs/docs/reference/configurations/dev-environment.md +++ b/docs/docs/reference/configurations/dev-environment.md @@ -1,6 +1,6 @@ # type: dev-environment (.dstack.yml) -Dev environment allows to connect to remote virtual machine from VS Code Desktop. +Dev environment allows connecting to a remote virtual machine from VS Code Desktop. !!! info "Filename" The configuration file must be named with the suffix `.dstack.yml`. For example, @@ -14,9 +14,9 @@ Dev environment allows to connect to remote virtual machine from VS Code Desktop - `ide` - The IDE to run. Currently only `vscode` is supported. - `env` - (Optional) The list or mapping of environment variables. Interpolation `PATH=/bin/my:$PATH` is supported. - `ports` - (Optional) The list of exposed ports or mappings. Allowed formats: - - `8000` - expose port `8000` and run ssh tunnel locally on the exact same port. + - `8000` - expose port `8000` and run the ssh tunnel locally on the same port. - `3333:8000` - expose port `8000` and run ssh tunnel locally on port `3333`. - - `*:8000` - expose port `8000` and run ssh tunnel locally on first available port starting from `8000`. + - `*:8000` - expose port `8000` and run the ssh tunnel locally on the first available port starting from `8000`. - `python` - (Optional) The preinstalled major python version (from `3.7` to `3.11`). Mutually exclusive with `image` property. - `setup` - (Optional) The list of commands to be executed once for the environment. - `init` - (Optional) The list of commands to be executed every restart of the environment. @@ -24,8 +24,8 @@ Dev environment allows to connect to remote virtual machine from VS Code Desktop ## Custom docker image properties: - `image` - (Optional) The docker image. Mutually exclusive with `python` property. -- `entrypoint` - (Optional) The docker entrypoint to interpret the commands (typically `/bin/bash -i -c`). -- `registry_auth` - (Optional) The credentials to pull the image from private registry. +- `entrypoint` - (Optional) The docker entry point to interpret the commands (typically `/bin/bash -i -c`). +- `registry_auth` - (Optional) The credentials to pull the image from the private registry. - `username` - The username. Supports secrets interpolation `${{ secrets.GHCR_USER }}`. - `password` - The password or token. Supports secrets interpolation `${{ secrets.GHCR_TOKEN }}`. - `home_dir` - (Optional) The home directory inside the container. Defaults to `/root`. @@ -37,10 +37,10 @@ Dev environment allows to connect to remote virtual machine from VS Code Desktop ## Optimization properties: - `cache` - (Optional) The list of directories to cache between the environment restarts. Both absolute and relative paths are supported. -- `build` - (Optional) The list of commands to run during build stage. You must call `dstack build` first or use flag `dstack run --build`. +- `build` - (Optional) The list of commands to run during the build stage. You must call `dstack build` first or use the flag `dstack run --build`. !!! info "Note" - Build is an experimental feature. Performance gain depends on the type of workloads and specific cloud provider. + The build is an experimental feature. Performance gain depends on the type of workload and specific cloud provider. ## Examples: diff --git a/docs/docs/reference/configurations/service.md b/docs/docs/reference/configurations/service.md index ccc0d1544..b32cca4fc 100644 --- a/docs/docs/reference/configurations/service.md +++ b/docs/docs/reference/configurations/service.md @@ -1,6 +1,6 @@ # type: service (.dstack.yml) -Service allows to run an application and expose it over HTTP to global internet through the gateway. +Service allows running an application and exposing it over HTTP to the global internet through the gateway. !!! info "Filename" The configuration file must be named with the suffix `.dstack.yml`. For example, @@ -23,8 +23,8 @@ Service allows to run an application and expose it over HTTP to global internet ## Custom docker image properties: - `image` - (Optional) The docker image. Mutually exclusive with `python` property. -- `entrypoint` - (Optional) The docker entrypoint to interpret the commands (typically `/bin/bash -i -c`). -- `registry_auth` - (Optional) The credentials to pull the image from private registry. +- `entrypoint` - (Optional) The docker entry point to interpret the commands (typically `/bin/bash -i -c`). +- `registry_auth` - (Optional) The credentials to pull the image from the private registry. - `username` - The username. Supports secrets interpolation `${{ secrets.GHCR_USER }}`. - `password` - The password or token. Supports secrets interpolation `${{ secrets.GHCR_TOKEN }}`. - `home_dir` - (Optional) The home directory inside the container. Defaults to `/root`. @@ -32,10 +32,10 @@ Service allows to run an application and expose it over HTTP to global internet ## Optimization properties: - `cache` - (Optional) The list of directories to cache between the environment restarts. Both absolute and relative paths are supported. -- `build` - (Optional) The list of commands to run during build stage. You must call `dstack build` first or use flag `dstack run --build`. +- `build` - (Optional) The list of commands to run during the build stage. You must call `dstack build` first or use the flag `dstack run --build`. !!! info "Note" - Build is an experimental feature. Performance gain depends on the type of workloads and specific cloud provider. + The build is an experimental feature. Performance gain depends on the type of workload and specific cloud provider. ## Examples: diff --git a/docs/docs/reference/configurations/task.md b/docs/docs/reference/configurations/task.md index 04ed19b65..c0a70a3fd 100644 --- a/docs/docs/reference/configurations/task.md +++ b/docs/docs/reference/configurations/task.md @@ -1,6 +1,6 @@ # type: task (.dstack.yml) -Task allows to run commands non-interactively: from fine-tuning to serving. +The task allows to run commands non-interactively: from fine-tuning to serving. !!! info "Filename" The configuration file must be named with the suffix `.dstack.yml`. For example, @@ -14,17 +14,17 @@ Task allows to run commands non-interactively: from fine-tuning to serving. - `commands` - The list of commands to be executed every restart of the environment. - `env` - (Optional) The list or mapping of environment variables. Interpolation `PATH=/bin/my:$PATH` is supported. - `ports` - (Optional) The list of exposed ports or mappings. Allowed formats: - - `8000` - expose port `8000` and run ssh tunnel locally on the exact same port. + - `8000` - expose port `8000` and run the ssh tunnel locally on the same port. - `3333:8000` - expose port `8000` and run ssh tunnel locally on port `3333`. - - `*:8000` - expose port `8000` and run ssh tunnel locally on first available port starting from `8000`. + - `*:8000` - expose port `8000` and run the ssh tunnel locally on the first available port starting from `8000`. - `python` - (Optional) The preinstalled major python version (from `3.7` to `3.11`). Mutually exclusive with `image` property. - `setup` - (Optional) The list of commands to be executed once for the environment. ## Custom docker image properties: - `image` - (Optional) The docker image. Mutually exclusive with `python` property. -- `entrypoint` - (Optional) The docker entrypoint to interpret the commands (typically `/bin/bash -i -c`). -- `registry_auth` - (Optional) The credentials to pull the image from private registry. +- `entrypoint` - (Optional) The docker entry point to interpret the commands (typically `/bin/bash -i -c`). +- `registry_auth` - (Optional) The credentials to pull the image from the private registry. - `username` - The username. Supports secrets interpolation `${{ secrets.GHCR_USER }}`. - `password` - The password or token. Supports secrets interpolation `${{ secrets.GHCR_TOKEN }}`. - `home_dir` - (Optional) The home directory inside the container. Defaults to `/root`. @@ -32,10 +32,10 @@ Task allows to run commands non-interactively: from fine-tuning to serving. ## Optimization properties: - `cache` - (Optional) The list of directories to cache between the environment restarts. Both absolute and relative paths are supported. -- `build` - (Optional) The list of commands to run during build stage. You must call `dstack build` first or use flag `dstack run --build`. +- `build` - (Optional) The list of commands to run during the build stage. You must call `dstack build` first or use the flag `dstack run --build`. !!! info "Note" - Build is an experimental feature. Performance gain depends on the type of workloads and specific cloud provider. + The build is an experimental feature. Performance gain depends on the type of workload and specific cloud provider. ## Examples: