trails/infrastructure/brouter-host

BRouter host compose project

Runs on a dedicated Hetzner Robot server (currently ullrich.is, private IP 10.0.1.10 over vSwitch #80672), owned by the non-root trails user. Services:

• brouter — the BRouter Java server, planet-scale segments, 8 GB JVM heap, no public port.
• caddy — thin sidecar enforcing the X-BRouter-Auth shared-secret header. Bound to 10.0.1.10:17777 (vSwitch IP only).

Public ingress is blocked at the host's UFW (port 17777 is only allowed on the VLAN interface from 10.0.0.2, the flagship's vSwitch IP).

One-time provisioning

Operator (as root) — one-time firewall rules

The dedicated host's UFW policy rejects anything not explicitly allowed. Open the vSwitch ports the flagship needs:

# BRouter Caddy sidecar (already added during section 1.2):
# ufw allow in on enp4s0.4000 from 10.0.0.2 to any port 17777 proto tcp \
#   comment 'trails brouter via flagship vSwitch'

# cAdvisor metrics endpoint (section 6) — add if not already:
ufw allow in on enp4s0.4000 from 10.0.0.2 to any port 8080 proto tcp \
  comment 'trails brouter cadvisor via flagship vSwitch'

Application bring-up (as the trails user)

# 1. Land the compose project
cd ~
git clone https://github.com/trails-cool/trails.git repo
mkdir -p brouter
cp -r repo/infrastructure/brouter-host/* brouter/
cd brouter

# 2. Provide the shared secret (matches BROUTER_AUTH_TOKEN in SOPS)
#    The CD workflow normally writes this file; for manual bring-up,
#    do it yourself.
cat > .env <<'EOF'
BROUTER_AUTH_TOKEN=<paste value from sops -d infrastructure/secrets.app.env | grep BROUTER_AUTH_TOKEN>
EOF
chmod 0600 .env

# 3. Seed segments (multi-hour, ~60–80 GB)
./download-segments.sh

# 4. Start services
docker compose pull
docker compose up -d

# 5. Smoke test from the flagship (over vSwitch)
#    Should return 200 with the token, 403 without.
# ssh root@trails.cool 'curl -sSf -H "X-BRouter-Auth: <TOKEN>" http://10.0.1.10:17777/brouter?lonlats=... '

Subsequent deploys

The cd-brouter GitHub Actions workflow handles routine updates: it pulls the latest image, rewrites the compose file + Caddyfile from the repo, and restarts.

Segment updates

Segments are refreshed by brouter.de weekly. To pull updates:

./download-segments.sh
docker compose restart brouter

Schedule via cron if you want automatic updates (not wired in this repo yet).

Token rotation

1. Regenerate: openssl rand -base64 32.
2. Update SOPS: sops infrastructure/secrets.app.env (writer uses the sops -d | append | sops -e pattern via the CD workflow; editing directly works too).
3. Merge the SOPS change to main.
4. cd-apps redeploys the Planner (sends the new token outbound).
5. cd-brouter redeploys Caddy (matches on the new token).
6. Brief overlap window where Planner sends new token but Caddy still accepts old: both deploys should fire within a minute of each other, so a few 403s are the worst case.

Rollback

If BRouter is misbehaving and the flagship BRouter is still warm (during the 48 h soak window post-cutover), flip BROUTER_URL in infrastructure/secrets.app.env back to http://brouter:17777 and redeploy the Planner. After the soak window, see the change's design.md for the longer rollback path.

Logging

The dedicated host's Docker daemon default logging driver is loki (the operator's personal Loki). Our compose file explicitly overrides each service to json-file so logs stay local; a promtail sidecar (section 6.3 of the relocate change) tails them and ships to trails.cool's Loki over the vSwitch. If you disable that sidecar, the BRouter logs will NOT flow to trails.cool's Grafana — they'll just accumulate locally and eventually rotate.