Multi-stage Elixir/OTP Dockerfile, Kubernetes manifests following
Keycloak pattern, mix release migration module, and deploy runbook.
Target: guildhall.guildhouse.dev via Hetzner LB + Cloudflare (orange
cloud). Forgejo container registry at git.guildhouse.dev/tking/guildhall.
Not yet deployed; artifacts only. See DEPLOY-RUNBOOK.md for execution.
Artifacts produced:
- Dockerfile — multi-stage, Elixir 1.17.3 / OTP 27.1.2, debian-bookworm
builder + debian-bookworm-slim runtime. Dep-layer caching via
explicit apps/*/mix.exs copy before source. Asset pipeline runs
mix assets.setup + mix assets.deploy (tailwind + esbuild + phx.digest).
Non-root uid 1000, tini as pid-1, HEALTHCHECK against /health.
- .dockerignore — excludes _build/, deps/, k8s/, .git/, test artifacts,
and apps/guildhall_web/priv/static/assets/ (regenerated by phx.digest
inside the builder).
- apps/guildhall_web/.../router.ex — adds `/health` route under :api
pipeline. Unauthenticated by design (Kubernetes probes + LB target).
- apps/guildhall_web/.../controllers/health_controller.ex — shallow
health: Phoenix up + Ecto pool can `SELECT 1`. Returns 200 ok or 503
degraded with reason.
- apps/guildhall_ops_db/lib/guildhall/ops_db/release.ex — Release
module for migrations. `Guildhall.OpsDb.Release.migrate/0` and
`rollback/2`. Called from the migration Job via
`bin/guildhall eval`. Module path reflects actual repo location
(repo is `Guildhall.OpsDb.Repo` in `:guildhall_ops_db`, not the
prompt's suggested `Guildhall.Repo`).
Kubernetes manifests in k8s/ (numbered for apply order):
00-namespace.yaml — guildhall namespace w/ guildhouse labels
10-registry-secret-template.yaml — doc-only template for dockerconfigjson
20-postgres-pvc.yaml — 5Gi longhorn RWO
30-postgres-deployment.yaml — postgres:16, keycloak-matched resources
+ pg_isready probes, PGDATA subpath
40-postgres-service.yaml — ClusterIP :5432
50-guildhall-secrets-template.yaml — doc-only template for app + DB secrets
60-migration-job.yaml — ecto migration Job, name includes tag
for per-deploy uniqueness, TTL 24h
70-guildhall-deployment.yaml — RollingUpdate maxSurge 1 maxUnavailable 0,
/health probes, 200m/256Mi requests
and 1/1Gi limits, 5s preStop sleep
80-guildhall-service.yaml — LoadBalancer with exact Keycloak-
matched Hetzner annotations
(location nbg1, type lb11, name
guildhall, use-private-ip false),
port 80 origin (Cloudflare TLS)
- DEPLOY-RUNBOOK.md — 6-phase deploy sequence (build + push, cluster
prep, DB, migrate, app rollout, DNS + smoke), iteration helper with
sed-based tag-bump, rollback procedure (image rollback, schema
rollback via Release.rollback, full teardown), and v0.1 limitations
(Cloudflare-edge TLS not cluster-terminated; no Flux integration;
no OIDC wiring; no substrate CRD integration; single replica).
Decisions made during artifact production that weren't explicit in
the prompt:
- Release module name is `Guildhall.OpsDb.Release` (not
`Guildhall.Release`) matching the actual repo namespace. Migration
Job command adjusted to `Guildhall.OpsDb.Release.migrate()`.
- Dockerfile uses `-slim` builder variant (not the full bookworm
builder) to keep the builder stage closer to the runtime image
size, reducing multi-stage layer transfer during build.
- Asset compilation runs `mix assets.setup` before `mix assets.deploy`
so tailwind + esbuild binaries install cleanly inside the container
(the dev-only :runtime flag on those deps means they need explicit
install in a prod builder).
- tini added as pid-1 in the runtime stage. Not in the prompt, but
standard-practice for OTP containers to ensure signal propagation
and zombie reaping under Kubernetes.
- Rolling update strategy: maxSurge 1 / maxUnavailable 0 (zero-
downtime rollout at replicas=1; the new pod comes up alongside the
old, health-checks, then the old is terminated). Matches typical
single-replica LiveView pattern.
- preStop `sleep 5` — gives in-flight HTTP + LiveView connections a
grace window before termination.
- Hetzner LB annotations: verified exact set from cluster keycloak
service — location=nbg1, name=guildhall, type=lb11,
use-private-ip=false. The prompt asked about uses-proxyprotocol
and algorithm-type; neither is set on Keycloak's service and both
are omitted here for consistency.
- Migration Job name includes the tag (`guildhall-migrate-v0-1-0`) so
multiple deploys don't collide on Job name reuse. Runbook documents
the sed helper to bump both the image tag and the Job name for
subsequent deploys.
- Both exploratory docs (`DEPLOY-EXPLORATORY-2026-04-21.md`,
`FORGEJO-REGISTRY-INVESTIGATION-2026-04-21.md`) are currently
untracked in the repo. They're left out of this commit per the
prompt's explicit `git add` list. They can be committed separately
(or ignored) at Tyler's discretion.
Not done tonight (per prompt's NOT PERMITTED list):
- docker build / docker push
- kubectl apply of any manifest
- Forgejo PAT creation
- Cloudflare DNS changes
- git push (this commit is local-only pending review)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Tyler J King <tking@guildhouse.dev>
Tyler J King
c6f1d07ed9