Skip to content

Commit 0868de5

Browse files
peterschmidt85peterschmidt85
authored
Updated runner and shim contributing guide (#2534)
1 parent 7a40432 commit 0868de5

File tree

3 files changed

+162
-1
lines changed

3 files changed

+162
-1
lines changed

‎.justfile

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Root justfile
2+
#
3+
# This justfile serves as the main entry point to recipes from different components.
4+
#
5+
# Run `just` to see all available commands.
6+
#
7+
# Components:
8+
# * runner/justfile – Building and uploading dstack runner and shim
9+
10+
default:
11+
@just --list
12+
13+
set allow-duplicate-recipes
14+
15+
import "runner/.justfile"
16+
17+
# TODO: Add frontend/justfile for managing frontend development tasks

‎runner/.justfile

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Justfile for building and uploading dstack runner and shim
2+
#
3+
# Run `just` to see all available commands
4+
#
5+
# Configuration:
6+
# - DSTACK_SHIM_UPLOAD_VERSION: Version of the runner and shim to upload
7+
# - DSTACK_SHIM_UPLOAD_S3_BUCKET: S3 bucket to upload binaries to
8+
#
9+
# Build Process:
10+
# - Runner is always built for linux/amd64
11+
# - Shim can be built for any platform (defaults to host platform)
12+
# - When uploading, shim is automatically built for linux/amd64
13+
#
14+
# Development Workflows:
15+
# - Local Development:
16+
# * Use build recipes to build binaries for local testing
17+
# * See README.md for instructions on running dstack server with local binaries
18+
# * No need to upload binaries for local development
19+
#
20+
# - Remote Development:
21+
# * Use upload recipes to build and upload binaries to S3
22+
# * See README.md for instructions on running dstack server with uploaded binaries
23+
# * Upload is required for testing with standard backends (including SSH fleets)
24+
25+
default:
26+
@just --list
27+
28+
# Version of the runner and shim to upload
29+
export version := env_var("DSTACK_SHIM_UPLOAD_VERSION")
30+
31+
# S3 bucket to upload binaries to
32+
export s3_bucket := env_var("DSTACK_SHIM_UPLOAD_S3_BUCKET")
33+
34+
# Download URLs
35+
export runner_download_url := "s3://" + s3_bucket + "/" + version + "/binaries/dstack-runner-linux-amd64"
36+
export shim_download_url := "s3://" + s3_bucket + "/" + version + "/binaries/dstack-shim-linux-amd64"
37+
38+
# Shim build configuration
39+
export shim_os := ""
40+
export shim_arch := ""
41+
42+
# Build runner
43+
[private]
44+
build-runner-binary:
45+
#!/usr/bin/env bash
46+
set -e
47+
echo "Building runner for linux/amd64"
48+
cd {{source_directory()}}/cmd/runner && GOOS=linux GOARCH=amd64 go build
49+
echo "Runner build complete!"
50+
51+
# Build shim
52+
[private]
53+
build-shim-binary:
54+
#!/usr/bin/env bash
55+
set -e
56+
cd {{source_directory()}}/cmd/shim
57+
if [ -n "$shim_os" ] && [ -n "$shim_arch" ]; then
58+
echo "Building shim for $shim_os/$shim_arch"
59+
GOOS=$shim_os GOARCH=$shim_arch go build
60+
else
61+
echo "Building shim for current platform"
62+
go build
63+
fi
64+
echo "Shim build complete!"
65+
66+
# Build both runner and shim
67+
build-runner: build-runner-binary build-shim-binary
68+
echo "Build complete! Linux AMD64 binaries are in their respective cmd directories."
69+
70+
# Clean build artifacts
71+
clean-runner:
72+
rm -f {{source_directory()}}/cmd/runner/runner
73+
rm -f {{source_directory()}}/cmd/shim/shim
74+
echo "Build artifacts cleaned!"
75+
76+
# Run tests for runner and shim
77+
test-runner:
78+
cd {{source_directory()}} && go test -v ./...
79+
80+
# Validate shim is built for linux/amd64
81+
[private]
82+
validate-shim-binary:
83+
#!/usr/bin/env bash
84+
set -e
85+
if ! file {{source_directory()}}/cmd/shim/shim | grep -q "ELF 64-bit LSB executable, x86-64"; then
86+
echo "Error: Shim must be built for linux/amd64 for upload"
87+
exit 1
88+
fi
89+
90+
# Upload both runner and shim to S3
91+
upload-runner: upload-runner-binary upload-shim-binary
92+
93+
# Upload runner to S3
94+
[private]
95+
upload-runner-binary:
96+
#!/usr/bin/env bash
97+
set -e
98+
just build-runner-binary
99+
aws s3 cp {{source_directory()}}/cmd/runner/runner "{{runner_download_url}}" --acl public-read
100+
echo "Uploaded runner to S3"
101+
102+
# Upload shim to S3
103+
[private]
104+
upload-shim-binary:
105+
#!/usr/bin/env bash
106+
set -e
107+
just --set shim_os linux --set shim_arch amd64 build-shim-binary
108+
just validate-shim-binary
109+
aws s3 cp {{source_directory()}}/cmd/shim/shim "{{shim_download_url}}" --acl public-read
110+
echo "Uploaded shim to S3"

‎runner/README.md

+35-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
For overview of `dstack-shim` and `dstack-runner`, see [/contributing/RUNNER-AND-SHIM.md](../contributing/RUNNER-AND-SHIM.md).
44

5-
## Development
5+
## Running locally
66

77
Here's the steps to build `dstack-shim` and `dstack-runner` and run `dstack` with them locally:
88

@@ -40,6 +40,8 @@ Now you can call shim API:
4040
>>> s.submit("","", "ubuntu", None)
4141
```
4242

43+
### Local backend
44+
4345
You can also run `dstack` end-to-end with local shim and runner by enabling the `local` backend on dstack server:
4446

4547
```shell
@@ -76,6 +78,38 @@ The `local` backend will submit the run to the locally started shim and runner.
7678
Continue? [y/n]:
7779
```
7880

81+
## Testing remotely
82+
83+
You can also test the built shim and runner using standard backends (including SSH fleets).
84+
85+
> [!NOTE]
86+
> To run with standard backends, both the runner and shim must be built for linux/amd64.
87+
88+
Build the runner and shim, and upload them to S3 automatically using `just` (see [`justfile`](justfile)).
89+
90+
> [!IMPORTANT]
91+
> Before running any `just` commands that upload to S3, you must set the following environment variables:
92+
>
93+
> ```shell
94+
> export DSTACK_SHIM_UPLOAD_VERSION="your-version"
95+
> export DSTACK_SHIM_UPLOAD_S3_BUCKET="your-bucket"
96+
> ```
97+
>
98+
> These variables are required and must be set before running any upload commands.
99+
100+
```shell
101+
just upload
102+
```
103+
104+
To use the built shim and runner with the dstack server, pass the URLs via `DSTACK_SHIM_DOWNLOAD_URL` and `DSTACK_RUNNER_DOWNLOAD_URL`:
105+
106+
```shell
107+
export DSTACK_SHIM_DOWNLOAD_URL="https://${DSTACK_SHIM_UPLOAD_S3_BUCKET}.s3.amazonaws.com/${DSTACK_SHIM_UPLOAD_VERSION}/binaries/dstack-shim-linux-amd64"
108+
export DSTACK_RUNNER_DOWNLOAD_URL="https://${DSTACK_SHIM_UPLOAD_S3_BUCKET}.s3.amazonaws.com/${DSTACK_SHIM_UPLOAD_VERSION}/binaries/dstack-runner-linux-amd64"
109+
110+
dstack server --log-level=debug
111+
```
112+
79113
## Dependencies (WIP)
80114

81115
These are nonexhaustive lists of external dependencies (executables, libraries) of the `dstack-*` binaries.

0 commit comments

Comments
 (0)