First time, on the VM: copy and fill .env.example, which
explains each value and what happens when an optional capability stays unset.
mkdir -p /opt/wattroom && cd /opt/wattroom
# copy this deploy/ directory here
cp .env.example .env
cp livekit.yaml.example livekit.yaml # real keys, same values as .env
docker compose -f docker-compose.prod.yml up -d
LiveKit runs on the host's network (WebRTC needs real UDP on the VM's
address) and everything else on the compose network, so the two never see each
other by name. Caddy reaches LiveKit as host.docker.internal, and LiveKit's
webhook reaches the server on the loopback port the compose publishes — keep
both if you change either side, or Join voice answers 502 and the voice radar
never moves.
Every deploy after that is a tag bump in .env:
WATTROOM_TAG=2026.09.1
docker compose -f docker-compose.prod.yml pull wattroom
docker compose -f docker-compose.prod.yml up -d wattroom
A rollback is the same three lines with the previous tag. That works only because migrations are expand/contract (ADR-0019): a release only adds, and drops land one release after the release whose code stopped using the thing. Break that rule and the old binary meets a schema it cannot serve.
Releases are cut with make release, which computes the next CalVer number
(YYYY.0M.MICRO), opens and merges a release PR promoting the changelog, then
tags the result — building
ghcr.io/natrontech/wattroom:2026.09.1 and opening a GitHub Release whose
notes are that release's changelog section. Pushes to main still
build :main for testing; never pin the VM to it, because a moving tag has no
previous version to go back to. The server migrates its own schema at boot, so
pull + up -d is still the whole path.
Check what actually landed — the second one is a real database ping now, not a hardcoded "ok":
curl -s https://wattroom.ch/api/version # {"version":"2026.09.1",...}
curl -s https://wattroom.ch/api/healthz # ok
This directory is the self-hosting reference: what the app needs to run, not
what runs wattroom.ch. Deployment automation belongs to whoever operates the
box, because it has to fit their edge proxy, their metrics system and their
backup driver — for wattroom.ch that is janlauber/homelab, which drops the
caddy, prometheus and backup services below for exactly those reasons and
rolls releases out with its own timer.
If you are self-hosting, the three lines above are a complete deploy. Automate
them wherever your other services are automated, and keep two properties:
never restart into a ride (wattroom_room_riding on wattroom:9091/metrics
tells you — it counts riders with a live sample, not everyone holding a voice
channel's socket), and take a dump first, because migrations run at boot and are
forward-only.
That gauge was absent from the endpoint in 2026.09.118 and 2026.09.119
— #1738 gave /metrics its own registry and this one collector kept
registering into the old one (#2321). A guard reading it on either of those two
releases saw nothing and, if it treats an unreadable count as "someone might be
riding", deferred every rollout until its own timeout. wattroom_room_riders
is the fallback, and it was never affected.
One Prometheus for the homelab, not one per workload (ADR-0006's convention, applied by ADR-0019). This stack does not run its own. Your Prometheus scrapes the container directly over a shared docker network, which is also why nothing has to be published to reach it:
docker network create monitoring # once, if your Prometheus stack hasn't
Put your Prometheus container on that same network, then give it:
scrape_configs:
- job_name: wattroom # the job name WattroomDown matches on
static_configs:
- targets: ['wattroom:9091'] # the metrics listener, NOT the app port
rule_files:
- /opt/wattroom/alerts.yml
and mount /opt/wattroom/alerts.yml into it read-only. Leave honor_labels
off. The background-job metrics carry a job label of their own; the scrape's
job="wattroom" wins and the app's arrives as exported_job, which is what the
job rules select on. Turn honor_labels on and the app's label replaces the
scrape's, and those rules match nothing (#2679).
wattroom.ch is not wired this way. Its Prometheus runs on another VM and reads
only the rules in janlauber/homelab, which holds a hand-ported copy of
alerts.yml, so a rule changed here has to be ported there too. Routing to a
phone and dashboards are the homelab's, per its own rules.
/metrics has its own listener on 9091 (#1738), which nothing proxies:
port 8080 answers 404 there, and what the endpoint publishes no longer depends
on an edge remembering to block a path. Caddy's block stays as a second lock.
Check it from the VM the way Prometheus does:
docker run --rm --network monitoring curlimages/curl -s http://wattroom:9091/metrics
Upgrading past this change: move the scrape and the deploy guard's ride
check from wattroom:8080/metrics to wattroom:9091/metrics. The old address
answers a 404 that says so, rather than an empty scrape. WATTROOM_METRICS_ADDR
defaults to :9091 and moves the listener; setting it to the empty string turns
it off, which is what a deployment with no scraper at all should do. Unset and
empty differ on purpose — there is no way to ask for the default by writing it
blank.
A Strava refresh token is stored sealed with WATTROOM_TOKEN_KEY or not at
all (ADR-0035). Without the key the server boots, logs that Strava is off, and
offers neither Strava sign-in nor connection; set it before configuring the
Strava app, or before upgrading a server that ran Strava without it.
The key seals two things, and a rotation treats them differently:
- Strava refresh tokens are not re-sealed. A rotated key makes them unreadable, and riders reconnect Strava (ADR-0035).
- Routes riders keep are re-sealed, because a route cannot be reconnected (ADR-0063). Each route records the version of the key that sealed it.
To rotate, deploy with WATTROOM_TOKEN_KEY set to the new key, then run the
re-seal once with the old key beside it:
docker compose exec -e WATTROOM_TOKEN_KEY_PREVIOUS='<the old key>' wattroom /wattroom reseal-routes
It moves every route sealed under the old key to the new one and logs how many it moved. It is safe to run twice and safe beside a running server. Until it has run, a route sealed under the old key keeps its heights, but its map and its full road (turns, height above sea) will not open, and the rider's export says it is incomplete. A server with no key at all never stores a route's map or its turns, only its heights measured from its start.
The same endpoint carries usage counts (#2913), recounted from the database
every five minutes: wattroom_accounts, wattroom_rides,
wattroom_ridden_seconds, wattroom_ridden_joules, wattroom_crews,
wattroom_workouts, wattroom_tracks, wattroom_strava_connections and
wattroom_sessions_upcoming, plus two with a window of 1d, 7d or 30d —
wattroom_accounts_created (signups that still exist) and
wattroom_riders_active (accounts with a ride that started in the window).
Counts only: no label names a rider, a crew or a channel. NaN means not
counted yet, as above, and
wattroom_job_last_success_timestamp_seconds{job="usage counts"} says how fresh
the numbers are.
The production synthetic ride — the check that proves a ride works rather
than that a homepage returns 200 — is not wired yet (#314). Until it is,
WATTROOM_SYNTHETIC_TOKEN can stay unset: POST /api/auth/synthetic 404s and
the path does not exist.