Development¶
How the repository is laid out, how to build and run Stellwerk from source, how it is tested and how a release is made. The rules for changes are in CLAUDE.md; they apply to people too.
Repository¶
| Path | What |
|---|---|
crates/protocol |
the messages between agent and Zentrale and the desired state; knows devices, folders, modes and paths, not Syncthing |
crates/engine |
everything about Syncthing: the pinned version, download, starting it, REST client, reconciler, monitor, conflict and version files |
crates/agent |
stellwerk-agent: pairing, the connection to the Zentrale, the background service; src/bin/background.rs is the Windows program without a console |
crates/zentrale |
stellwerk: axum server, SQLite store with migrations, desired-state derivation, hub, live status, pairing, mDNS, the embedded UI |
web/ |
the web UI: React (built with the TanStack Redact runtime), TanStack Router and Query, Tailwind, Paraglide; src/demo/ holds the demo data |
e2e/ |
Playwright tests and the screenshots, against the UI in demo mode |
docker/Dockerfile |
the Zentrale's image |
installer/windows/ |
the NSIS script of the Windows installer |
scripts/ |
the service and installer smoke tests CI runs on real systems |
docs/ |
this documentation (MkDocs Material) |
Prerequisites¶
- Rust stable (the workspace needs at least 1.94, edition 2024)
- Bun (the version in
packageManagerofpackage.json): installs the packages and runs the scripts, Vite and the Playwright runner - for the docs: Python and
pip install -r requirements-docs.txt
Building¶
bun install
bun run --filter web build # web/dist, embedded into the Zentrale's release build
cargo build --release # target/release/stellwerk and stellwerk-agent
docker build -f docker/Dockerfile -t tristanteu/stellwerk . # the image, UI included
A release build of the Zentrale built before web/dist exists answers every page with a hint to
build the UI first. Debug builds read web/dist from disk at run time.
Running it locally¶
The UI alone, on demo data, without Rust or Syncthing:
A real Zentrale and agent on one machine, with ports that do not collide with a Syncthing you run yourself:
# once: the admin password
cargo run -p stellwerk-zentrale -- --data-dir /tmp/stw/zentrale set-password <<< 'dev'
# terminal 1: the Zentrale (:8080) and the UI with hot reload (:5173, /api proxied to :8080)
bun run dev
# terminal 2: an agent, after "Pair device" in the UI
cargo run -p stellwerk-agent -- --data-dir /tmp/stw/agent join --server http://127.0.0.1:8080 <CODE>
cargo run -p stellwerk-agent -- --data-dir /tmp/stw/agent run --name dev-agent
bun run dev runs bun run --parallel dev:server dev:web: dev:server is
cargo run -p stellwerk-zentrale -- --data-dir /tmp/stw/zentrale --listen 127.0.0.1:8080
--hub-listen tcp://127.0.0.1:22101 --lan-pairing false, dev:web the Vite dev server
(bun run --cwd web dev; under bun run --filter it would not stop with the other). Both run
side by side, each line prefixed with its script's name, and when one exits with an error the
other is stopped. Ctrl+C, Ctrl+Z and closing the terminal reach both, as the terminal signals the
whole foreground process group; fg resumes them after Ctrl+Z. In a terminal both keep their
colours (FORCE_COLOR, CARGO_TERM_COLOR).
Two agents on one machine need two data directories. Never start a test Syncthing on 8384 or 22000, and never touch a Syncthing you did not start.
Tests¶
| Command | What runs |
|---|---|
cargo test |
unit tests of every crate, and the integration tests in crates/*/tests against real Syncthing instances (the pinned version is downloaded once into .syncthing-cache/) |
bun run --filter web check |
Biome, tsc --noEmit, Vitest, vite build |
bun checks |
files past 400 lines, the interface texts and rings of imports between modules (the folders of web/src), by firsttris/workflows' checks with checks.json; older large files and texts are listed in .checks/ and may only get fewer. bun checks pr gives hints on the branch, such as a function new or grown past 80 lines |
bun run e2e |
Playwright against the demo build, its runner and Vite on Bun (bun --bun playwright test); PW_CHROMIUM=/path/to/chrome outside the Playwright image, PW_PORT when 4173 is taken |
mkdocs build --strict |
the docs, with broken links as errors |
The integration tests are the gates of the roadmap:
| Test | Shows |
|---|---|
engine/tests/phase0_gate.rs |
the reconciler sets up two Syncthings and a file arrives |
zentrale/tests/pairing.rs |
a device pairs with a code and syncs with the hub |
zentrale/tests/lan_pairing.rs |
a device without a code waits, is approved and syncs |
zentrale/tests/phase1_gate.rs |
three nodes; a device that was offline catches up on files and configuration |
zentrale/tests/phase2_gate.rs |
a conflict is resolved on the hub and a version restored |
zentrale/tests/api.rs |
login, CSRF, folders, drafts and pairing codes over HTTP |
Every Syncthing in a test runs with SpawnOptions::isolated: random ports on 127.0.0.1, no
discovery, no relays.
Continuous integration¶
| Workflow | When | Does |
|---|---|---|
ci.yml |
every push to main and pull request (not for docs only) |
Rust: fmt, clippy and tests (cargo nextest, every test in its own process at once) on Linux, Windows and macOS, then the service smoke test with the agent the tests built; web checks; bun checks (with bun checks pr on a pull request); E2E in the Playwright image; the Docker image builds and starts. A pull request runs only what it can break (scripts/ci-changes.sh): a change in web/ alone skips Rust, one in crates/ alone the UI checks, and the image builds only when docker/, a lockfile or a package.json changed |
agents.yml |
pushes to main, from release.yml, or by hand |
the agent for every platform; on Windows also the installer and its silent install/uninstall test; SHA256SUMS and the install scripts. On main it keeps the release builds' cache warm, and a broken release build shows up there |
docs.yml |
pushes to main and pull requests that touch docs/, mkdocs.yml or requirements-docs.txt |
builds the docs with mkdocs build --strict (the privacy plugin downloads fonts and the Mermaid script at build time, so the site loads nothing from third parties); on main also publishes them to GitHub Pages |
screenshots.yml |
by hand: Actions → Update screenshots | renders the pictures in docs/ from the demo data and commits them |
bump.yml |
by hand: Actions → Bump version | raises the version and tags it, which starts release.yml |
release.yml |
a tag vX.Y.Z, or by hand |
CI, agents, the multi-arch image on Docker Hub and GHCR, the GitHub release with the agents |
The reusable parts (bump, tested on main, Docker release, screenshots) come from firsttris/workflows.
Releasing¶
- Actions → Bump version → patch/minor/major. It sets the version in
Cargo.toml,web/package.jsonande2e/package.json, commits, and tagsvX.Y.Z. - The tag starts
release.yml, which runs nothing twice.tested-on-main.ymlfrom firsttris/workflows checks that the CI was green onmainfor the commit before the release commit, which only raises the version; only when it was not does the release run the CI first. The agents build from the start, beside the imagetristanteu/stellwerkandghcr.io/speicherstadt/stellwerkforlinux/amd64andlinux/arm64(tagsx.y.z,x.y,latest, the Docker Hub description from the README). The image's build cache is the one the CI's Docker job fills, andcargo-chefkeeps the compiled dependencies in it, so only Stellwerk's own crates compile. Last, the GitHub release gets the agents, the Windows installer, the install scripts andSHA256SUMS.
Run by hand on main, release.yml publishes the image as edge only, without a release: a
dry run of the publishing part.
Secrets: DOCKER_PAT (Docker Hub access token for tristanteu). GHCR uses the workflow's own
token.
Changing Syncthing's version¶
The version and the SHA-256 of every platform's archive are in crates/engine/src/pin.rs.
Renovate (.github/renovate.json5) opens a pull request for each new Syncthing release; on its
branch syncthing-pin.yml puts in the checksums from the release's sha256sum.txt.asc and starts
CI, whose integration tests must be green with the new version. By hand: put in the version and
the checksums, and run cargo test. The Syncthing sources (lib/config, lib/api) are the
reference for anything the engine relies on.
Documentation¶
Pictures come from bun run screenshots or Actions → Update screenshots; never edit them by
hand. The same command renders docs/social-preview.png (1280 × 640) from
scripts/social-preview/social-preview.html and the dark screenshot; upload it under
Settings → General → Social preview when it changed. Links between pages are relative (installation.md#…); links from the README go to the
published site.