Operations

Once the integration is verified, this is how you keep it healthy. The invariants from Deployment overview apply throughout — in particular, application rollback and schema recovery are separate decisions.

Scheduled cleanup

Expired sessions, one-time state, and locks are drained by a bounded cleanup job. Run it at least daily. You configured it during deploy:

• Google Cloud — a Cloud Scheduler job invokes the Cloud Run cleanup job. See Google Cloud → Schedule cleanup.
• Docker / VPS — a systemd timer or cron entry runs the cleanup Compose service. See Docker → Schedule cleanup.

Alert if the scheduled cleanup fails or stops running — a stalled cleanup lets transient tables grow unbounded.

Backups and restore drills

gcloud sql backups create \
  --instance="$SQL_INSTANCE" \
  --description="pre-release $(date -u +%Y-%m-%dT%H:%M:%SZ)"

gcloud sql backups list --instance="$SQL_INSTANCE" --limit=10

export BACKUP_ID="$(gcloud sql backups list \
  --instance="$SQL_INSTANCE" --sort-by='~endTime' --limit=1 \
  --format='value(id)')"
export RESTORE_INSTANCE="${SQL_INSTANCE}-restore-drill"

gcloud sql backups restore "$BACKUP_ID" \
  --backup-instance="$SQL_INSTANCE" \
  --restore-instance="$RESTORE_INSTANCE" \
  --region="$REGION" \
  --edition=ENTERPRISE --cpu=1 --memory=3840MiB \
  --no-deletion-protection

umask 077
mkdir -p backups
export AGE_RECIPIENT="age1REPLACE_WITH_RECOVERY_RECIPIENT"
export BACKUP_FILE="backups/canvas-seb-$(date -u +%Y%m%dT%H%M%SZ).dump.age"

docker compose --env-file .env.secrets -f compose.yaml -f compose.secrets.yaml \
  exec -T postgres \
  pg_dump --username=canvas_seb --dbname=canvas_seb \
    --format=custom --no-owner --no-acl \
  | age --recipient "$AGE_RECIPIENT" >"$BACKUP_FILE"

docker compose --env-file .env.secrets -f compose.yaml -f compose.secrets.yaml \
  exec -T postgres createdb --username=canvas_seb canvas_seb_restore_drill

age --decrypt --identity /secure/path/age-identity.txt "$BACKUP_FILE" \
  | docker compose --env-file .env.secrets -f compose.yaml -f compose.secrets.yaml \
      exec -T postgres \
      pg_restore --username=canvas_seb --dbname=canvas_seb_restore_drill \
        --exit-on-error --no-owner --no-acl

Upgrades

docker build --tag canvas-seb-lti:NEW_VERSION .
# edit APP_IMAGE in .env.secrets

docker compose --env-file .env.secrets -f compose.yaml -f compose.secrets.yaml \
  up --detach --wait

Rollback

• Google Cloud — list revisions and shift traffic only when compatibility is confirmed:

  gcloud run revisions list --service="$SERVICE" --region="$REGION"
  gcloud run services update-traffic "$SERVICE" --region="$REGION" \
    --to-revisions="PREVIOUS_REVISION=100"

• Docker / VPS — restore the prior immutable APP_IMAGE and run the same up --detach --wait. This rolls back the application only.

Schema recovery means a reviewed forward migration or a restore into a controlled target — never an automatic down-migration during a failed deploy. Use expand/migrate/deploy/contract changes so adjacent revisions stay compatible.

PostgreSQL pool sizing

DATABASE_POOL_MAX is per application process. Reserve connections for migrations, cleanup, administration, monitoring, and restore work:

(max app instances × DATABASE_POOL_MAX) + job/admin reserve < database max_connections

The checked-in Cloud Run configs use a pool max of 5; production's ten instances therefore use at most 50 application connections before the reserve. Recalculate before changing either value.

Secret rotation

Rotate one secret at a time: create a new immutable version, point the runtime at it, deploy, smoke test, then disable the old version. Consequences (sessions invalidated, outstanding state invalidated, Canvas/JWKS coordination, fresh .seb downloads) are in Configuration → Secret rotation.

Release smoke checks

Run after every release:

curl -fsS "${TOOL_URL}/health"
curl -fsS "${TOOL_URL}/ready"
curl -fsS "${TOOL_URL}/.well-known/jwks.json"
curl -fsS "${TOOL_URL}/lti/config"
curl -fsS "${TOOL_URL}/js/canvas-seb-detector.js" | head
curl -fsS "${TOOL_URL}/js/canvas-seb-theme-loader.js" | head

Then complete the verification sequence for any change that touches authentication, Canvas, settings, configuration, the detector, or exit.

Monitoring

Alert on: application 5xx responses, /ready failures, migration/cleanup job failures, PostgreSQL connection saturation, database storage growth, failed backups, stale cleanup executions, and certificate expiry. On a VPS, also watch disk space, container health, backup age, and host security updates.

Development database reset (dev only)

A guarded command exists for a completely fresh dev state. It permanently destroys all records in the maintained dev database before recreating it and reapplying migrations.

npm run db:reset:gcloud:dev -- --project "$PROJECT_ID"