Skip to content

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 packageManager of package.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:

bun run dev:demo                 # http://localhost:5173

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

  1. Actions → Bump version → patch/minor/major. It sets the version in Cargo.toml, web/package.json and e2e/package.json, commits, and tags vX.Y.Z.
  2. The tag starts release.yml, which runs nothing twice. tested-on-main.yml from firsttris/workflows checks that the CI was green on main for 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 image tristanteu/stellwerk and ghcr.io/speicherstadt/stellwerk for linux/amd64 and linux/arm64 (tags x.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, and cargo-chef keeps 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 and SHA256SUMS.

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

pip install -r requirements-docs.txt
mkdocs serve                     # http://127.0.0.1:8000, reloads on change

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.