Skip to content

ADR 0052

github-actions[bot] edited this page Nov 22, 2026 · 1 revision

Status: accepted · Built: done · Date: 2026-11-22

Closes ADR 0034's wave-2 item for static apps. Built: the static kind in the agent (Spotcraft's image as the server, the site image mounted at /srv, the fallback setting, redeploys on a new server image at start), GET, PUT and DELETE /redirects with sites/_redirects.caddy, and both in the dashboard.

Static sites are files-only images; redirects are an instance setting

Context

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.

Decision

  • A static site is an image with its files in /site. Two lines: FROM scratch and COPY dist /site. CI builds it for linux/amd64 and linux/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) or static. 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: image volume). 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.html for folders, .html without 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 its 404.html and status 404; spa answers with its index.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 from domain, a to address (https://), whether the path and query are kept, and optional prefix rules checked first. The agent keeps them in apps/.redirects.json and writes them to sites/_redirects.caddy. Every redirect is permanent (301). A root domain's www. 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.

Consequences

  • 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-ancestors can't, so framing is limited by the platform's X-Frame-Options default.
  • The agent must know Spotcraft's image (SPOTCRAFT_SERVER_IMAGE); without it, static sites are refused.
  • The removal test holds: the /site folder 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.

Clone this wiki locally