Repository navigation
ADR 0021
Status: accepted · Built: done · Date: 2026-11-13 · Superseded by: 0022, 0023
Built: default subdomains, client-address handling, the infra/cloudflare module, the Hetzner edge switch, tunnel mode on both servers, custom domains through the API and per-app Access. Protected apps are probed only up to the Access sign-in.
Every app needs a domain typed in by hand, and its A and AAAA records made by hand. Caddy on public ports 80 and 443 gets a certificate for each domain. Both servers' addresses are public, and nothing in front of them filters traffic.
Hosting platforms like Vercel give every project an address from its name and let a custom domain point at it with one CNAME record. A self-hosted Spotcraft can do the same, and Cloudflare's free plan adds a hidden origin, TLS, a WAF, DDoS protection and sign-in (Access). Not every owner uses Cloudflare, so it must stay optional.
-
A default host per app. With
APPS_DOMAINset on the agent, every app is served at<name>.<APPS_DOMAIN>. App names are already DNS labels. One wildcard record (*.<APPS_DOMAIN>) covers every app.APPS_DOMAINshould be a zone apex, so Cloudflare's free certificate (one level of wildcard) covers it.wwwandfallbackare reserved names. -
domainbecomes the optional custom domain, served next to the default host. WithoutAPPS_DOMAIN, it is required, as before. No host can belong to two apps. Existingapp.jsonfiles need no change. -
Cloudflare is optional (
EDGE=direct|cloudflare, defaultdirect).directis today's setup. Withcloudflare:- Each server runs
cloudflaredfor its own Cloudflare Tunnel. The tunnel dials out, so ports 80 and 443 are closed in the firewall and the servers' addresses stay hidden. - Caddy serves plain HTTP behind the tunnel and still routes by host. Cloudflare holds the certificates.
- Caddy trusts
CF-Connecting-IPonly from private addresses (cloudflared) and only in this mode, and passes the visitor's address on asX-Forwarded-For. The dashboard's login lockout and the apps keep seeing real visitors.
- Each server runs
-
Zone-level setup is OpenTofu (
infra/cloudflare, next toinfra/hetzner): the tunnels, the wildcard and dashboard records, TLS settings, the free managed WAF rules, a rate limit on the dashboard's login, bot switches (off by default) and Access in front of the dashboard. Zones are looked up, never created, so records made by hand survive. Cloudflare's free managed WAF rules are on by default and left alone.route_dns = falsebuilds everything but leaves the records alone, so an existing instance can prepare everything first and keep the switch itself to a few minutes' outage. It can't be zero: behind the tunnel, Caddy serves plain HTTP tocloudflaredonly, so the public records stop working once Spotcraft switches modes. -
Every app follows a mode change. When the agent starts, it rewrites every app's Caddy site
for the current
EDGEandAPPS_DOMAINand reloads Caddy, so switching modes doesn't wait for each app's next deploy. -
Custom domains are set up by the agent through the Cloudflare API, because the agent
already deploys apps one at a time and rolls back:
- A domain whose zone is in the same Cloudflare account gets a proxied CNAME to the apps tunnel. A root domain works through CNAME flattening.
- Any other domain becomes a Cloudflare for SaaS custom hostname on the apps zone. Its owner
adds a CNAME to
<name>.<APPS_DOMAIN>, and the dashboard shows the verification and certificate status. - The agent only changes records it made itself (marked with the comment
spotcraft:<name>), unless the owner explicitly takes over an existing record.
- Per-app sign-in: an app can be put behind Cloudflare Access with the owners' policy, for staging apps and previews.
- An app is reachable before anyone touches DNS for it, once the wildcard exists.
- With Cloudflare, Cloudflare is in every request's path: if it is down, so are the apps.
- The agent's Cloudflare token can edit DNS in the account's zones. It lives only in the apps
server's
.env, like the agent's other secrets. The token's scopes are listed ininfra/cloudflare. - Apps on sibling subdomains of the apps domain can set cookies for the whole zone. One instance hosts one owner's apps, so this is accepted. A dedicated apps zone avoids it.
-
directmode still works on any VPS without a Cloudflare account.
Published from docs/. Edit the files there; changes here are overwritten.