Quick start¶
dstack
makes it very easy for ML engineers to run dev environments, pipelines and apps cost-effectively
on any cloud.
Installation and setup¶
To use dstack
, install it with pip
and start the Hub server.
$ pip install "dstack[aws,gcp,azure]"
$ dstack start
The Hub is available at http://127.0.0.1:3000?token=b934d226-e24a-4eab-eb92b353b10f
What is Hub?
Hub is a server that manages projects and users. Each project allows you to configure where to run dev environments, pipelines, and apps (e.g. locally or in the cloud), as well as manage users that access it.
At startup, dstack
sets up a default project for local execution. To run dev environments, pipelines, and apps in your
desired cloud account, you must create the corresponding project and configure the dstack
CLI to use it.
Initializing the repo¶
Before you can run dev environments, pipelines, and apps in any folder,
first have to initialize it as a repo by running the dstack init
command.
$ mkdir quickstart && cd quickstart
$ dstack init
Running a dev environment¶
A dev environment is a virtual machine that includes the environment and an interactive IDE or notebook setup based on a pre-defined configuration.
Go ahead and define this configuration via YAML (under the .dstack/workflows
folder).
workflows:
- name: code-gpu
provider: code
setup:
- pip install -r dev-environments/requirements.txt
resources:
gpu:
count: 1
NOTE:
For dev environments, the configuration allows you to configure hardware resources, set up the Python environment, expose ports, configure cache, and many more.
Now, you can start it using the dstack run
command:
$ dstack run code-gpu
RUN WORKFLOW SUBMITTED STATUS TAG
shady-1 code-gpu now Submitted
Starting SSH tunnel...
To exit, press Ctrl+C.
Web UI available at http://127.0.0.1:10000/?tkn=4d9cc05958094ed2996b6832f899fda1
NOTE:
If you configure a project to run dev environments in the cloud, dstack
will automatically provision the
required cloud resources, and forward ports of the dev environment to your local machine. When you stop the
dev environment, dstack
will automatically clean up cloud resources.
Running a pipeline¶
A pipeline is a set of pre-defined configurations that allow to process data, train or fine-tune models, do batch inference or other tasks.
To run a pipeline, all you have to do is define it via YAML (under the .dstack/workflows
folder)
and then run it by name via the CLI.
workflows:
- name: train-mnist-gpu
provider: bash
commands:
- pip install -r pipelines/requirements.txt
- python pipelines/train.py
artifacts:
- ./lightning_logs
resources:
gpu:
count: 1
NOTE:
For pipelines, the configuration allows you to configure hardware resources and output artifacts, set up the Python environment, expose ports, configure cache, and many more.
Now, you can run the pipeline using the dstack run
command:
$ dstack run train-mnist-gpu
RUN WORKFLOW SUBMITTED STATUS TAG
shady-1 train-mnist-gpu now Submitted
Provisioning... It may take up to a minute. ✓
GPU available: True, used: True
Epoch 1: [00:03<00:00, 280.17it/s, loss=1.35, v_num=0]
---> 100%
NOTE:
If you configure a project to run pipelines in the cloud, the dstack run
command will automatically provision the
required cloud resources.
After the pipeline is finished, dstack
will save output artifacts and clean up cloud resources.
Running an app¶
An app can be either a web application (such as Streamlit, Gradio, etc.) or an API endpoint (like FastAPI, Flask, etc.) setup based on a pre-defined configuration.
Go ahead and define this configuration via YAML (under the .dstack/workflows
folder).
workflows:
- name: fastapi-gpu
provider: bash
ports:
- 3000
commands:
- pip install -r apps/requirements.txt
- uvicorn apps.main:app --port 3000 --host 0.0.0.0
resources:
gpu:
count: 1
NOTE:
For apps, the configuration allows you to customize hardware resources, set up the Python environment, configure cache, and more.
Now, you can run the app using the dstack run
command:
$ dstack run fastapi-gpu
RUN WORKFLOW SUBMITTED STATUS TAG
silly-dodo-1 fastapi-gpu now Submitted
Starting SSH tunnel...
To interrupt, press Ctrl+C.
INFO: Started server process [1]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:3000 (Press CTRL+C to quit)
NOTE:
If you configure a project to run apps in the cloud, dstack
will automatically provision the required cloud
resources, and forward ports of the app to your local machine.
NOTE:
Check out the dstackai/dstack-examples
repo for source code and other examples.