Skip to content

app_prismio Deploy Runbook

This is an operator-first checklist for building, promoting, and rolling back app_prismio.

Quick model

  • Build once: produce an immutable image tagged with a full Git SHA.
  • Promote by redeploying the same SHA to each environment.
  • Roll back by redeploying a previously known-good SHA.

Prerequisites

  • You can run GitHub Actions workflows in this repository.
  • GitHub environment configuration is present for dev, staging, and prod:
  • Required environment variable: DEPLOY_PATH
  • Required environment variable: APP_ENV_FILE
  • Repository secrets are configured for deploy workflow:
  • DEPLOY_SSH_PRIVATE_KEY
  • DEPLOY_HOST
  • DEPLOY_USER
  • GHCR_USERNAME
  • GHCR_TOKEN

A) Build immutable image

  1. Merge changes to main or master (or run the build workflow manually).
  2. Open workflow: Build app_prismio Images.
  3. Wait for success.
  4. Capture the image tag from logs. The tag is the full commit SHA.

Expected artifact format:

  • ghcr.io//api:

B) Deploy to dev

  1. Open workflow: Deploy app_prismio.
  2. Click Run workflow.
  3. Set inputs:
  4. environment: dev
  5. image_tag:
  6. Run.
  7. Confirm workflow success.

What the workflow does:

  1. Verifies image exists in GHCR.
  2. Syncs deploy compose files to remote host.
  3. Pulls app and migrate images.
  4. Runs one-off migrations:
  5. python manage.py migrate --noinput
  6. Starts app container.
  7. Waits for container health check.

C) Promote to staging, then prod

Use exactly the same SHA from dev.

  1. Run Deploy app_prismio with:
  2. environment: staging
  3. image_tag:
  4. Validate staging.
  5. Run Deploy app_prismio with:
  6. environment: prod
  7. image_tag:
  8. Validate prod.

Rule: do not rebuild between environments. Promotion is redeploying the same artifact.

D) Rollback

  1. Identify the previous known-good SHA.
  2. Run Deploy app_prismio with:
  3. environment: target environment to recover
  4. image_tag:
  5. Confirm workflow success and app health.

Rollback is a redeploy of an older immutable tag.

E) Post-deploy smoke checks

Run after each environment deploy:

  1. Confirm workflow is green.
  2. Confirm app is reachable.
  3. Confirm login and one critical user flow.
  4. Confirm no migration errors in logs.
  5. Confirm no error spike in monitoring.

F) Local simulation (optional)

From repository root:

APP_IMAGE=ghcr.io/your-org/api: \ APP_ENV_FILE=/absolute/path/to/prod.env \ make app-deploy

This exercises pull + migrate + rollout with the deploy compose overlay locally.

G) Failure triage

If deploy fails, use this order:

  1. Image not found:
  2. Confirm SHA exists in Build workflow output.
  3. SSH or host sync failure:
  4. Confirm DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_PRIVATE_KEY.
  5. Migration failure:
  6. Inspect migrate container logs.
  7. Health check timeout/unhealthy:
  8. Inspect app container logs and /healthz dependencies.

References

  • .github/workflows/build-api.yaml
  • .github/workflows/deploy-api.yaml
  • .github/workflows/deploy-sites.yml
  • .github/workflows/deploy-marketing-preview.yml
  • infra/docker/compose/compose.yaml
  • infra/docker/compose/services/api.yaml
  • infra/docker/compose/services/postgres.yaml
  • tools/docker/Makefile

H) Sites deploys (marketing and docs)

The docs and marketing Cloudflare Pages deployments are consolidated in:

  • .github/workflows/deploy-sites.yml

Trigger behavior:

  • The workflow runs only for pull requests targeting main when the PR is merged.

Job behavior (path-gated):

  • deploy-marketing runs only when matching marketing files change:
  • apps/api/prismio/marketing/templates/marketing/pages/**
  • apps/api/prismio/templates/common/components/**
  • apps/api/prismio/static/**
  • apps/api/prismio/marketing/urls.py
  • apps/api/prismio/marketing/views.py
  • apps/api/prismio/marketing/management/commands/export_guest_site.py
  • .github/workflows/deploy-sites.yml
  • .github/workflows/deploy-marketing-preview.yml
  • deploy-docs runs only when matching docs files change:
  • docs/**
  • apps/api/docs/**
  • tools/docs/**
  • .github/workflows/deploy-sites.yml

Marketing preview deploy

Preview deploys are manual-only via:

  • .github/workflows/deploy-marketing-preview.yml

This workflow is workflow_dispatch only, so it never runs automatically from PR or push events.

Run steps:

  1. Open repository Actions.
  2. Choose Deploy Marketing Preview.
  3. Click Run workflow.