Repository navigation
ADR 0052
Status: accepted · Built: done · Date: 2026-11-22
Closes ADR 0034's wave-2 item for static apps. Built: the
statickind in the agent (Spotcraft's image as the server, the site image mounted at /srv, thefallbacksetting, redeploys on a new server image at start),GET,PUTandDELETE /redirectswithsites/_redirects.caddy, and both in the dashboard.
ADR 0034 says Spotcraft receives an image or a folder, and serves
containers and static files. Only containers were built; static apps were left for wave 2. Sites
that are only files (a marketing site, a docs site, a client-rendered app) still need a host,
and the owner wants them on the instance, with the same contract as other apps: HTTPS, the
headers, legal.json, analytics and the user pool on the same origin.
Old domains also need to send visitors to their new place. Without a redirect on the instance, the owner needs another service for that.
A folder upload doesn't fit what exists. Request bodies are capped at every layer, from Caddy to the agent, and neither the agent nor Caddy can unpack an archive into a place the other can read. Apps already have a deploy path built on images: the deploy hook, releases, blue/green slots, health, logs, rollback and removal.
-
A static site is an image with its files in
/site. Two lines:FROM scratchandCOPY dist /site. CI builds it forlinux/amd64andlinux/arm64, pushes it, and calls the deploy hook, as for any app. The registry is the storage and the tag is the reference, like GitHub Pages' artifact and deploy steps. -
An app has a kind:
container(the default) orstatic. It is set when the app is made and can't change. -
Spotcraft serves the files with its own server. A static site runs Spotcraft's own image,
the one the agent runs from, as Caddy with a static Caddyfile baked into that image. The site
image is mounted read-only (a Compose
type: imagevolume). The server's code is Spotcraft's and changes with Spotcraft's version, never the site's. When the agent starts on a new version, it deploys static sites again onto the new server; nothing is built, so it is quick. -
The server: compression,
index.htmlfor folders,.htmlwithout the extension, and hashed assets (name.<hash>.ext) cached for a year. An unknown path gets the site's fallback, its one setting:404(the default) answers with its404.htmland status 404;spaanswers with itsindex.html. -
What a static site gets is what an app gets on its domain: HTTPS, its default host or own
domain with
www, the security headers,/_spotcraft/legal.json, analytics and/_spotcraft/auth/*. What it doesn't: env vars, a schema, mail, migrations, or settings for a port, CPUs, env or a writable root. It has no process of its own. -
Redirects are an instance setting, not an app. Each has a
fromdomain, atoaddress (https://), whether the path and query are kept, and optional prefix rules checked first. The agent keeps them inapps/.redirects.jsonand writes them tosites/_redirects.caddy. Every redirect is permanent (301). A root domain'swww.redirects too. A redirect can't take a host an app, the dashboard or the user pool answers on, and an app can't take a redirected host.
- A static site deploys, releases, rolls back and is removed like an app; the dashboard and the deploy hook need nothing new.
- Each site costs a small Caddy process (about 11 MB), not a share of one server for all sites. The cost buys the same slots, health and logs as apps.
- A site can't set response headers. Its CSP goes in a
<meta>tag;frame-ancestorscan't, so framing is limited by the platform'sX-Frame-Optionsdefault. - The agent must know Spotcraft's image (
SPOTCRAFT_SERVER_IMAGE); without it, static sites are refused. - The removal test holds: the
/sitefolder runs on any static host. The/_spotcraft/*routes and the pool are the instance's, as for any app. - A redirect domain has no container, so it isn't an app: no status, metrics or deploy history.
Published from docs/. Edit the files there; changes here are overwritten.