Packaging: multi-stage Dockerfile (scratch + CA certs) #17

Context

PRD: docs/PRD.md (Cloudflare Containers / Go binary on Linux).

Ship a minimal container image for aixgo-sync suitable for Cloudflare Containers and any Linux host. Prefer the smallest runtime surface: scratch, with TLS trust store present when the binary makes outbound HTTPS (R2/S3, GitHub, etc.).

Goal

Add a multi-stage Dockerfile that:

1. Build stage — compile a static aixgo-sync (or equivalent) with a current Go toolchain image.
2. Certs stage (if needed) — take CA certificates from an Alpine (or alpine:latest) image (/etc/ssl/certs/ca-certificates.crt).
3. Runtime stage — FROM scratch, copy the binary + CA bundle (and any other required static files), set a non-root-friendly entrypoint.

Out of scope

• Cloudflare deploy wiring / Wrangler / container binding (docs can note “image is ready for Containers”)
• Multi-arch publish to GHCR (nice-to-have follow-up; single linux/amd64 is enough for the first PR)
• Changing application config or HTTP routes

Suggested layout

Dockerfile
.dockerignore
# optional:
# docs/deploy-containers.md   // short “build & run” note

Acceptance criteria

• Multi-stage Dockerfile with final stage FROM scratch
• Binary is statically linked (or otherwise runs on scratch without glibc)
• CA certs are copied into the scratch image when outbound TLS is required (document the path, e.g. SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt)
• .dockerignore keeps build context small (no .git, coverage, local caches)
• Documented one-liner to build and run locally, e.g. docker build -t aixgo-sync:local . and docker run --rm -p … aixgo-sync:local …
• Image builds successfully in CI or a documented make docker / workflow step (prefer a simple make docker target if a Makefile already exists)
• make check remains green; Docker is not required for the default gate unless you add a separate optional target

Required tests / verification

1. docker build succeeds locally (or in CI)
2. Container starts and /healthz (or the current health endpoint) responds once serve exists
3. Brief note in README or deploy doc: why scratch + where certs come from

Dependencies

• Prefer landing after cmd/aixgo-sync can serve (issue M1: HTTP serve — healthz + sessions GET/PUT (CAS/ETag) #4) so the image has a real entrypoint to smoke-test. Can still land the Dockerfile earlier with a version / stub entrypoint if useful.

How to hand to Aixgo Code

Apply label ax:go when ready (one issue at a time is still fine; parallel with M1 API work is OK if the Dockerfile stays self-contained).