Files
magik/docs/stateless-web-service-deploy.md
masi a07522a189 MAGIK — Commander deck builder
React 19 SPA + node:http/node:sqlite API in one container. Card data is
baked into the image from a Scryfall bulk build, so the runtime never calls
Scryfall. No server-side user state: decks live in the browser and travel in
the share URL, which is why there is no PVC and replicas: 1 is correct.

Adds a README covering the architecture and the reasoning behind it, and
publishes the project skills under .claude/skills/.

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-01 21:12:19 -03:00

3.5 KiB

Deploying a stateless single-container web service

A recipe for putting a read-only web app on the homelab, verified on the magik service. There is no PVC, no account and no server-side state, which is the case the default local-path storage class is not right for.

MAGIK's public edge is Caddy on the Oracle VPS. A DNS-only A record points to the VPS, and Caddy proxies the original hostname over Tailscale to the homelab's Traefik ingress. The app deployment script leaves that route alone; accessctl expose would replace the DNS record with the private Tailnet IP.

When this applies

A service whose state is either immutable (baked into the image) or lives entirely in the browser. If a user can lose data by deleting a pod, it does not apply — that needs the storage decision in the homelab operations contract first.

The chain

docker build → push localhost:32000/<name>:<tag>
            → sed 's/:latest/:<tag>/' manifest | kubectl apply -f -
            → kubectl rollout status
            → configure the service's public or private edge

For Tailnet or LAN-only services, the last step is accessctl expose <ns>/<svc> <subdomain>. MAGIK uses the public Caddy route described above instead.

What the cluster needs

securityContext:
  runAsNonRoot: true
  runAsUser: 10001      # the uid the image creates; they must match
  runAsGroup: 10001
  fsGroup: 10001
  seccompProfile:
    type: RuntimeDefault

Requests and limits on cpu, memory and ephemeral-storage. There are no namespace quotas, so the request is the only thing keeping a new workload from crowding the control plane. A read-only index in the tens of MB and a 192Mi memory request is a realistic starting point; a Node process holding a SQLite handle and nothing else sits comfortably under 512Mi.

imagePullPolicy: IfNotPresent is safe only because the registry is localhost:32000, which the node reaches over loopback.

The tag has to change every release

The manifest carries :latest as a placeholder and deploy.sh rewrites it to <timestamp> before applying. If the project is not a git checkout there is no commit to hash, so a UTC timestamp is the tag — what matters is that it is never the same twice, or a node that already holds :latest will not re-pull.

Serving a SPA

Do not add an ingress path rewrite. The application should return its own index.html for any path it does not recognise as a file; that is what makes /browse and a shared deep link survive a hard refresh. A rewrite in the ingress duplicates the fallback in a second place and the two drift.

The same applies to /api: same origin, no CORS, no separate service.

Verifying

kubectl rollout status deployment/<name> -n <ns> --timeout=5m
curl -fsS https://<sub>.<domain>/api/health
curl -o /dev/null -w '%{http_code}\n' https://<sub>.<domain>/<a-client-route>

The second curl is not optional. A 200 on / says the container is up; only a client-side route proves the SPA fallback works. Certificates are issued asynchronously — an HTTPS curl taken too soon fails with a name mismatch against the previous certificate, so kubectl wait --for=condition=Ready certificate/<name>-tls first.

Image-building gotchas

  • Node 26 images ship without corepack. RUN corepack enable fails with corepack: not found; install pnpm directly (npm install -g pnpm@11) instead.
  • Bake build-time data into the image rather than fetching it there. A build that needs the network is a build that fails for reasons unrelated to the code.