Migrations And Release
Build images, run migrations, refresh API contracts, and validate a release.
Migrations And Release
Use migrations and generated-contract checks as release gates. Do not depend on runtime AutoMigrate outside local development.
Build Images
The backend Dockerfile builds these runtime targets from one Go build stage:
| Target | Contains |
|---|---|
api-runtime | /app/api |
proof-worker-runtime | /app/worker-proof |
worker-runtime | /app/worker |
verifier-cli-runtime | /app/verifier |
migrator-runtime | /app/migrator |
runtime | API plus worker binaries for the compose reference image. |
Reference build:
docker compose build api proof-worker anchor-worker notification-worker report-worker retry-worker maintenance-worker
Run Migrations
The root compose file exposes a migrator profile:
docker compose --profile migration build db-migrate
docker compose --profile migration run --rm db-migrate version
For a reviewed migration run, set:
MIGRATIONS_DATABASE_URL='postgres://...'
MIGRATIONS_ACTION=up
Use the migrator up -dry-run command where supported before applying changes
to a shared environment.
Refresh API Contract
From backend/:
make api-contract
This refreshes Swagger and generated TypeScript clients. For route comparison only:
go run ./cmd/route-contract -write-docs
Expected outputs:
| File | Purpose |
|---|---|
backend/docs/swagger/swagger.json and .yaml | Generated OpenAPI artifacts. |
backend/docs/api-contract-status.md | Human-readable route backlog comparison. |
backend/docs/api-contract-status.json | Machine-readable route status. |
frontend/src/lib/api/client and dashboard/src/lib/api/client | Generated HeyAPI clients. |
The current contract status reports 54 expected backlog operations and 54 implemented in Swagger.
Validate Backend
Run:
cd backend
go test ./...
make api-contract
Docker-heavy checks:
make -C backend compose-e2e-config
docker compose -f compose.e2e.yml up --build -d
Use unique E2E ports when running in parallel:
COMPOSE_PROJECT_NAME=wipe-e2e-local \
WIPE_E2E_API_PORT=18080 \
WIPE_E2E_KEYCLOAK_PORT=18081 \
WIPE_E2E_PUBLIC_API_URL=http://127.0.0.1:18080 \
WIPE_E2E_PUBLIC_KEYCLOAK_URL=http://127.0.0.1:18081 \
docker compose -f compose.e2e.yml up --build -d
Validate Frontends
For the new frontend:
cd frontend
npm install
npm run check
npm run build
For the dashboard:
cd dashboard
pnpm check
pnpm build
Release Checklist
| Check | Expected result |
|---|---|
| Git status reviewed | Only intended source and generated files changed. |
| Migrations reviewed | Up/down SQL exists and migrator image can run version. |
| API contract refreshed | No missing cahier backlog endpoints. |
| Backend tests pass | go test ./... succeeds. |
| Frontend type/build checks pass | Selected portal builds with generated client. |
| Compose smoke passes | API, Keycloak, MinIO, workers, and portals start. |
| Observability heartbeats present | API and worker signals visible in Grafana/Prometheus. |
| Secrets reviewed | No local defaults or dev bypasses in non-local environment. |