Deployment

Build, migrate, deploy, verify, and roll back without exposing test surfaces.

This page is the production rollout checklist for the service image, database schema, runtime configuration, and public documentation site.

Environment Layout

Environment Static config Runtime values Expected use
Local process configs/static_config.yaml configs/config_vars.yaml Manual development and API poking.
Dev Docker profile configs/static_config.yaml configs/config_vars.docker.yaml Containerized development with source mounted.
Production Docker profile configs/static_config.prod.yaml Mounted/generated /app/configs/config_vars.yaml Release image without source mount or testsuite endpoints.

Build and Release Gate

A release candidate should build the service, compile SQL query headers, run unit tests, run the functional testsuite, and validate the OpenAPI YAML before deployment. 

cmake --build cmake-build-debug -j$(nproc) --target smirkly-auth smirkly-auth_unittest
ctest --test-dir cmake-build-debug --output-on-failure
ruby -e "require 'yaml'; YAML.load_file('openapi/auth-v0.yaml')"

The GitHub Pages workflow publishes docs/ plus the current openapi/auth-v0.yaml, so API docs and the deployed contract move together.

Database Migrations

  • Run the migration job before starting a service version that depends on new schema.
  • Keep MIGRATE_DATABASE_URL and service postgres-dbconnection pointed at the same database.
  • Do not run application schema from Postgres init scripts in production; use versioned migrations.
  • For local databases created before migration tracking, recreate the volume or baseline it manually after checking schema state.
docker compose --profile dev run --rm smirkly-migrate-dev

docker compose --profile prod up --build -d smirkly-auth

Production Container Rules

  • Use the release image and configs/static_config.prod.yaml.
  • Mount JWT keys and generated runtime config at deploy time.
  • Keep testsuite, tests-control, and fake-mode endpoints out of the production static config.
  • Expose the service only through TLS-terminating ingress or a private service mesh.
  • Set resource limits so userver congestion control reflects real CPU constraints.

Rollout Sequence

  1. Build and test the release candidate.
  2. Generate environment-specific config_vars.yaml from the secret store.
  3. Run migrations once per database.
  4. Start the new service version with static_config.prod.yaml.
  5. Check JWKS, sign-up, sign-in, refresh, logout, and email verification smoke tests.
  6. Watch logs, SMTP outbox backlog, DB errors, latency, and 4xx/5xx rate for the rollout window.

Rollback

Prefer forward-compatible migrations. If rollback is required, stop the new service version first, deploy the previous image with its matching runtime config, and only then decide whether a down migration is safe. Never run a destructive down migration while a newer binary can still write to the database.