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>
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 enablefails withcorepack: 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.