Skip to content

Commit a789342

Browse files
peterschmidt85peterschmidt85
committed
- [CLI] Updated Docker and Hugging Face Spaces installation instructions to reduce confusion
1 parent f117fd9 commit a789342

2 files changed

Lines changed: 69 additions & 78 deletions

File tree

‎docs/docs/installation/docker.md‎

Lines changed: 35 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Docker
22

3-
!!! info "NOTE:"
4-
As an alternative to the [`dstack start`](../reference/cli/start.md) command, you can run the `dstack` server via
5-
Docker. This is recommended if you want to deploy the server in an environment that supports Docker.
6-
7-
Here's how to run `dstack` via Docker:
3+
Here's how to run the `dstack` server via Docker:
84

95
<div class="termy">
106

@@ -16,6 +12,13 @@ $ docker run --name dstack -p &lt;port-on-host&gt;:3000 \
1612

1713
</div>
1814

15+
!!! info "NOTE:"
16+
If you run the `dstack` server via Docker, it will not allow you to run workloads locally.
17+
To run workloads locally, make sure to use [`pip`](pip.md).
18+
19+
Running the `dstack` server via Docker makes sense only if you intend to deploy the `dstack` server
20+
outside of your machine to run workloads in the cloud.
21+
1922
## Environment variables
2023

2124
Here's the list of environment variables which you can override:
@@ -24,39 +27,30 @@ Here's the list of environment variables which you can override:
2427
at the first startup.
2528
- `DSTACK_HUB_DATA` – (Optional) The path to the directory where the Hub server stores the state. Defaults to `~/.dstack/hub/data`.
2629

27-
### Persisting state
28-
29-
By default, `dstack` saves state in a local directory (see `DSTACK_HUB_DATA`).
30-
If you want to persist state automatically to a cloud object storage, you can configure the following environment
31-
variables.
32-
33-
- `LITESTREAM_REPLICA_URL` - The url of the cloud object storage.
34-
Examples: `s3://<bucket-name>/<path>`, `gcs://<bucket-name>/<path>`, `abs://<storage-account>@<container-name>/<path>`, etc.
35-
36-
??? info "AWS S3"
37-
To persist state into an AWS S3 bucket, provide the following environment variables:
38-
39-
- `AWS_ACCESS_KEY_ID` - The AWS access key ID
40-
- `AWS_SECRET_ACCESS_KEY` - The AWS secret access key
41-
42-
??? info "GCP Storage"
43-
To persist state into an AWS S3 bucket, provide one of the following environment variables:
44-
45-
- `GOOGLE_APPLICATION_CREDENTIALS` - The path to the GCP service account key JSON file
46-
- `GOOGLE_APPLICATION_CREDENTIALS_JSON` - The GCP service account key JSON
47-
48-
??? info "Azure Blob Storage"
49-
To persist state into an Azure blog storage, provide the following environment variable.
50-
51-
- `LITESTREAM_AZURE_ACCOUNT_KEY` - The Azure storage account key
52-
53-
More [details](https://litestream.io/guides/) on options for configuring persistent state.
54-
55-
## Limitation
56-
57-
When you run `dstack` via Docker, it doesn't allow you to configure a project that runs dev environments, pipelines, and apps locally.
58-
You can only configure the projects that run dev environments, pipelines, and apps in the cloud.
59-
60-
!!! info "NOTE:"
61-
If you want `dstack` to run dev environments,
62-
pipelines, and apps both locally and in the cloud, it is recommended to start the server using the `dstack start` command.
30+
??? info "Persisting state in a cloud storage"
31+
32+
By default, `dstack` saves state in a local directory (see `DSTACK_HUB_DATA`).
33+
If you want to persist state automatically to a cloud object storage, you can configure the following environment
34+
variables.
35+
36+
- `LITESTREAM_REPLICA_URL` - The url of the cloud object storage.
37+
Examples: `s3://<bucket-name>/<path>`, `gcs://<bucket-name>/<path>`, `abs://<storage-account>@<container-name>/<path>`, etc.
38+
39+
??? info "AWS S3"
40+
To persist state into an AWS S3 bucket, provide the following environment variables:
41+
42+
- `AWS_ACCESS_KEY_ID` - The AWS access key ID
43+
- `AWS_SECRET_ACCESS_KEY` - The AWS secret access key
44+
45+
??? info "GCP Storage"
46+
To persist state into an AWS S3 bucket, provide one of the following environment variables:
47+
48+
- `GOOGLE_APPLICATION_CREDENTIALS` - The path to the GCP service account key JSON file
49+
- `GOOGLE_APPLICATION_CREDENTIALS_JSON` - The GCP service account key JSON
50+
51+
??? info "Azure Blob Storage"
52+
To persist state into an Azure blog storage, provide the following environment variable.
53+
54+
- `LITESTREAM_AZURE_ACCOUNT_KEY` - The Azure storage account key
55+
56+
More [details](https://litestream.io/guides/) on options for configuring persistent state.

‎docs/docs/installation/hf-spaces.md‎

Lines changed: 34 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
# Hugging Face Spaces
22

33
!!! info "NOTE:"
4-
If you want to use `dstack` alone, it's enough to start the Hub server locally using
5-
the [`dstack start`](../reference/cli/start.md)
6-
command. It will allow you to run dev environments, pipelines, and apps both locally
7-
and in the cloud.
8-
9-
However, if you want to work as a team and manage cloud credentials in a more secure way, you may consider
10-
deploying the `dstack` server as a Hugging Face Space.
4+
If you run the `dstack` server via Docker, it will not allow you to run workloads locally.
5+
To run workloads locally, make sure to use [`pip`](pip.md).
6+
7+
Running the `dstack` server via Hugging Face Spaces makes sense only if you intend to
8+
deploy the `dstack` server outside of your machine to run workloads in the cloud.
119

1210
## Create a space
1311

@@ -18,7 +16,7 @@ The easiest way to create a Space to run `dstack` is duplicating the
1816
[`dstackai/dstack-template`](https://huggingface.co/spaces/dstackai/dstack-template) Space template
1917
by clicking the button below.
2018

21-
<a href="https://huggingface.co/spaces/dstackai/dstack-template?duplicate=true"
19+
<a href="https://huggingface.co/spaces/dstackai/dstack-template?duplicate=true&visibility=public"
2220
class="md-button md-button--primary" target="_blank">Create a Space</a>
2321

2422
## Configure the settings
@@ -40,32 +38,31 @@ the required value.
4038

4139
If you don't do that, dstack will generate it randomly and print it to the `Logs`.
4240

43-
#### Persisting state
44-
45-
If you want the space to maintain the state across restarts, you need to add the secrets that instruct `dstack`
46-
to persist the state in a cloud object storage of your choice.
47-
48-
- `LITESTREAM_REPLICA_URL` - The url of the cloud object storage.
49-
Examples: `s3://<bucket-name>/<path>`, `gcs://<bucket-name>/<path>`, `abs://<storage-account>@<container-name>/<path>`, etc.
50-
51-
??? info "AWS S3"
52-
To persist state into an AWS S3 bucket, provide the following environment variables:
53-
54-
- `AWS_ACCESS_KEY_ID` - The AWS access key ID
55-
- `AWS_SECRET_ACCESS_KEY` - The AWS secret access key
56-
57-
??? info "GCP Storage"
58-
To persist state into an AWS S3 bucket, provide one of the following environment variables:
59-
60-
- `GOOGLE_APPLICATION_CREDENTIALS` - The path to the GCP service account key JSON file
61-
- `GOOGLE_APPLICATION_CREDENTIALS_JSON` - The GCP service account key JSON
62-
63-
??? info "Azure Blob Storage"
64-
To persist state into an Azure blog storage, provide the following environment variable.
65-
66-
- `LITESTREAM_AZURE_ACCOUNT_KEY` - The Azure storage account key
67-
68-
Once the settings are configured, you can restart the space and log in as an administrator. From there, you can create
69-
users, projects, and configure the `dstack` CLI. This allows you to collaborate as a team, running development
70-
environments, pipelines, and apps securely and conveniently in the cloud without the need to host the `dstack` server
71-
yourself.
41+
??? info "Persisting state in a cloud storage"
42+
If you want the `dstack` server to persist the state across restarts, you need to add the secrets that instruct `dstack`
43+
to persist the state in a cloud object storage of your choice.
44+
45+
- `LITESTREAM_REPLICA_URL` - The url of the cloud object storage.
46+
Examples: `s3://<bucket-name>/<path>`, `gcs://<bucket-name>/<path>`, `abs://<storage-account>@<container-name>/<path>`, etc.
47+
48+
??? info "AWS S3"
49+
To persist state into an AWS S3 bucket, provide the following environment variables:
50+
51+
- `AWS_ACCESS_KEY_ID` - The AWS access key ID
52+
- `AWS_SECRET_ACCESS_KEY` - The AWS secret access key
53+
54+
??? info "GCP Storage"
55+
To persist state into an AWS S3 bucket, provide one of the following environment variables:
56+
57+
- `GOOGLE_APPLICATION_CREDENTIALS` - The path to the GCP service account key JSON file
58+
- `GOOGLE_APPLICATION_CREDENTIALS_JSON` - The GCP service account key JSON
59+
60+
??? info "Azure Blob Storage"
61+
To persist state into an Azure blog storage, provide the following environment variable.
62+
63+
- `LITESTREAM_AZURE_ACCOUNT_KEY` - The Azure storage account key
64+
65+
Once the settings are configured, you can restart the space and log in as an administrator. From there, you can create
66+
users, projects, and configure the `dstack` CLI. This allows you to collaborate as a team, running development
67+
environments, pipelines, and apps securely and conveniently in the cloud without the need to host the `dstack` server
68+
yourself.

0 commit comments

Comments
 (0)