Skip to content

Commit 2789f35

Browse files
peterschmidt85peterschmidt85
committed
Updated runner and shim contributing guide
* Updated README to include instructions on how to test shim and runner remotely * Added justfile with common reciples to build and upload runner and shim
1 parent 7b44252 commit 2789f35

2 files changed

Lines changed: 138 additions & 1 deletion

File tree

‎justfile‎

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

‎runner/README.md‎

Lines changed: 26 additions & 1 deletion
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,29 @@ 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+
```shell
91+
just upload
92+
```
93+
94+
To use the built shim and runner with the dstack server, pass the URLs via `DSTACK_SHIM_DOWNLOAD_URL` and `DSTACK_RUNNER_DOWNLOAD_URL`:
95+
96+
```shell
97+
DSTACK_SHIM_DOWNLOAD_URL=https://dstack-runner-downloads-stgn.s3.eu-west-1.amazonaws.com/0.0.0/binaries/dstack-shim-linux-amd64
98+
99+
DSTACK_RUNNER_DOWNLOAD_URL=https://dstack-runner-downloads-stgn.s3.eu-west-1.amazonaws.com/0.0.0/binaries/dstack-runner-linux-amd64
100+
101+
dstack server --log-level=debug
102+
```
103+
79104
## Dependencies (WIP)
80105

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

0 commit comments

Comments
 (0)