diff --git a/.env.example b/.env.example index 424b28a..a4fe63f 100644 --- a/.env.example +++ b/.env.example @@ -12,6 +12,12 @@ DEFAULT_EVENT_SLUG=demo # Encrypts the session cookie. REQUIRED, min 32 chars. # openssl rand -base64 48 SESSION_SECRET= +# While rotating: the old secret(s), comma-separated, still accepted for +# reading cookies for one session lifetime so nobody is signed out. +# SESSION_SECRET_PREVIOUS= +# Hashes login codes. Defaults to SESSION_SECRET; set it separately in +# production so rotating the session secret leaves codes in flight working. +# OTP_PEPPER= # ── Postgres ────────────────────────────────────────────────── POSTGRES_USER=matchmaker @@ -22,7 +28,18 @@ POSTGRES_PORT=5432 # Used by scripts run on the HOST (migrate/seed/import). # Inside docker-compose the host is `postgres`, not `localhost`. DATABASE_URL=postgres://matchmaker:matchmaker@localhost:5432/matchmaker +# disable (local, no TLS) | require (encrypted, unverified) | verify (encrypted, +# certificate checked against DATABASE_CA_CERT or DATABASE_CA_CERT_FILE). +# Production refuses anything but verify for a remote database. DATABASE_SSL=disable +# DATABASE_CA_CERT_FILE=/etc/ssl/certs/rds-global-bundle.pem + +# Deployed only: the migration task creates these least-privilege logins +# (packages/db/src/ensure-roles.ts); web and worker then use the runtime one. +# DATABASE_RUNTIME_USER=app_runtime +# DATABASE_RUNTIME_PASSWORD= +# KEYCLOAK_DB_USER=keycloak +# KEYCLOAK_DB_PASSWORD= # ── Keycloak ────────────────────────────────────────────────── KEYCLOAK_PORT=8080 @@ -43,11 +60,15 @@ KEYCLOAK_GOOGLE_IDP_ALIAS=google # From Google Cloud Console > APIs & Services > Credentials. # Authorised redirect URI must be: # http://localhost:8080/realms/match-maker/broker/google/endpoint -# Leave blank to develop with the e-mail-code path only. +# Leave blank to develop with the e-mail-code path only; the login page shows +# "Sign in with Google" only when GOOGLE_CLIENT_ID is set. After changing these +# (or KEYCLOAK_CLIENT_SECRET) on an existing realm, run: npm run keycloak:sync GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= # ── Resend (login e-mails) ──────────────────────────────────── +# The web app refuses to start without a key unless EMAIL_DEV_FALLBACK=true. +# EMAIL_FROM must use a domain verified in Resend. RESEND_API_KEY= EMAIL_FROM=Mr. Bridge @@ -61,6 +82,14 @@ OTP_TTL_SECONDS=600 OTP_MAX_PER_WINDOW=5 OTP_RATE_WINDOW_SECONDS=900 +# Seconds the worker waits before refreshing other people's matches after a +# profile change, so bursts of changes coalesce (default 120). +# MATCH_REFRESH_DELAY_SECONDS=120 + +# Proxies in front of the web app that append to X-Forwarded-For (1 behind +# the AWS ALB). 0 trusts no header, so per-IP login limits are skipped locally. +TRUSTED_PROXY_HOPS=0 + # ── Gemini (matchmaking) ────────────────────────────────────── GEMINI_API_KEY= GEMINI_LLM_MODEL=gemini-3.8-flash diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5b24733..b1d8b60 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,13 +2,23 @@ name: CI on: push: - branches: [main] + branches: [main, dev] + # Every pull request, whatever branch it targets. pull_request: - branches: [main] + # deploy.yml runs these same checks before it builds anything, so there is + # one definition of what a release must pass. + workflow_call: + inputs: + build_images: + description: "Also build the images (the deploy builds and pushes its own)" + type: boolean + default: true -# A new push supersedes an in-flight run on the same branch. +# A new push supersedes an in-flight run on the same branch. The workflow name +# keeps a deploy's call to this file out of the standalone CI run's group, +# which a push to main starts at the same time. concurrency: - group: ci-${{ github.ref }} + group: ci-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true env: @@ -20,6 +30,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + # The migration gate compares with the base commit. + fetch-depth: 0 - uses: actions/setup-node@v4 with: @@ -37,29 +50,31 @@ jobs: - name: Unit tests run: npx vitest run tests/unit + # Migrations run before the new code starts, and a rollback runs the + # previous image on the migrated schema: released migrations never + # change and new ones only expand. + - name: Migrations are safe to roll back from + run: npx tsx tools/check-migrations.ts "${{ github.event.pull_request.base.sha || github.event.before }}" + integration: name: Integration tests runs-on: ubuntu-latest - services: - postgres: - image: pgvector/pgvector:pg16 - env: - POSTGRES_USER: matchmaker - POSTGRES_PASSWORD: matchmaker - POSTGRES_DB: matchmaker - ports: - - 5432:5432 - options: >- - --health-cmd "pg_isready -U matchmaker" - --health-interval 5s - --health-timeout 5s - --health-retries 20 - + # The same Postgres (with the Keycloak database) and Keycloak (with the + # realm import and theme) that docker compose runs locally. env: DATABASE_URL: postgres://matchmaker:matchmaker@localhost:5432/matchmaker DATABASE_SSL: disable SESSION_SECRET: ci-session-secret-long-enough-for-validation-x + KEYCLOAK_ISSUER: http://localhost:8080/realms/match-maker + KEYCLOAK_PUBLIC_URL: http://localhost:8080 + KEYCLOAK_ADMIN: admin + KEYCLOAK_ADMIN_PASSWORD: admin + KEYCLOAK_CLIENT_ID: match-maker-web + KEYCLOAK_CLIENT_SECRET: ci-client-secret + APP_BASE_URL: http://localhost:3000 + # Suites skip themselves without these services; here that is a failure. + REQUIRE_SERVICES: db,keycloak steps: - uses: actions/checkout@v4 @@ -71,18 +86,111 @@ jobs: - run: npm ci + - name: Start Postgres and Keycloak + run: docker compose up -d --wait postgres keycloak + # The suite calls migrate() itself, so this only proves the runner works # standalone — the way the deploy pipeline invokes it. - name: Apply migrations run: npm run db:migrate + - name: Configure Keycloak + run: | + npm run keycloak:wait + npm run keycloak:sync + - name: Integration tests - run: npx vitest run tests/integration + run: npx vitest run tests/integration --reporter=default --reporter=json --outputFile=vitest-report.json + + # A suite that skipped itself would otherwise count as a pass. + - name: Every integration test ran + run: npx tsx tools/check-test-report.ts vitest-report.json + + - name: Service logs + if: failure() + run: docker compose logs --no-color postgres keycloak | tail -n 300 + + browser: + name: Browser acceptance + runs-on: ubuntu-latest + needs: [quality] + + # The built app and the worker against the compose Postgres and Keycloak. + # Login codes are logged instead of e-mailed and read from the app's log. + env: + DATABASE_URL: postgres://matchmaker:matchmaker@localhost:5432/matchmaker + DATABASE_SSL: disable + SESSION_SECRET: ci-session-secret-long-enough-for-validation-x + KEYCLOAK_ISSUER: http://localhost:8080/realms/match-maker + KEYCLOAK_PUBLIC_URL: http://localhost:8080 + KEYCLOAK_ADMIN: admin + KEYCLOAK_ADMIN_PASSWORD: admin + KEYCLOAK_CLIENT_ID: match-maker-web + KEYCLOAK_CLIENT_SECRET: ci-client-secret + APP_BASE_URL: http://localhost:3000 + EMAIL_DEV_FALLBACK: "true" + MATCH_REFRESH_DELAY_SECONDS: "3" + E2E_BASE_URL: http://localhost:3000 + E2E_WEB_LOG: ${{ github.workspace }}/e2e-web.log + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + cache: npm + + - run: npm ci + + - name: Start Postgres and Keycloak + run: docker compose up -d --wait postgres keycloak + + - name: Migrate, seed and configure Keycloak + run: | + npm run db:migrate + npm run db:seed + npm run keycloak:wait + npm run keycloak:sync + + - name: Build + run: npm run build + + - name: Install Chromium + run: npx playwright install --with-deps chromium + + - name: Start app and worker + run: | + (cd apps/web && nohup npx next start -p 3000 > "$E2E_WEB_LOG" 2>&1 &) + nohup npm run worker > e2e-worker.log 2>&1 & + for i in $(seq 1 60); do + curl -fsS http://localhost:3000/api/health/ready && exit 0 + sleep 2 + done + cat "$E2E_WEB_LOG" + exit 1 + + - name: Browser tests + run: npm run test:e2e + + - name: Keep report and logs + if: failure() + uses: actions/upload-artifact@v4 + with: + name: browser-acceptance + path: | + playwright-report/ + test-results/ + e2e-web.log + e2e-worker.log + retention-days: 7 build: name: Build images runs-on: ubuntu-latest needs: [quality] + # Push and pull_request runs have no inputs, so this is true for them. + if: ${{ inputs.build_images != false }} steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index f7bcde0..6b8dffa 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -5,14 +5,27 @@ on: branches: [main] workflow_dispatch: inputs: + environment: + description: "Where to deploy. Staging is a separate Terraform stack (environment = staging)." + type: choice + options: [production, staging] + default: production + promote_tag: + description: "Promote: copy this tag's staging images to production unchanged, then migrate and roll out (production only)" + type: string + default: "" deploy_keycloak: description: "Also rebuild and roll out Keycloak" type: boolean default: false + rollback_tag: + description: "Roll back: re-deploy this existing image tag (skips checks, build and migrations)" + type: string + default: "" # Never let two deploys race for the same service. concurrency: - group: deploy-production + group: deploy-${{ inputs.environment || 'production' }} cancel-in-progress: false permissions: @@ -20,45 +33,98 @@ permissions: id-token: write contents: read +# Staging names follow the Terraform stack (match-maker-staging-*) and never +# fall back to production's repository variables. Each job that touches AWS +# runs in the GitHub environment of the target, so its role, subnets and URL +# come from that environment's secrets and variables. env: + TARGET: ${{ inputs.environment || 'production' }} + STACK: ${{ inputs.environment == 'staging' && 'match-maker-staging' || 'match-maker-prod' }} AWS_REGION: ${{ vars.AWS_REGION || 'ap-south-1' }} - ECS_CLUSTER: ${{ vars.ECS_CLUSTER || 'match-maker-prod-cluster' }} - ECS_WEB_SERVICE: ${{ vars.ECS_WEB_SERVICE || 'match-maker-prod-web' }} - ECS_WORKER_SERVICE: ${{ vars.ECS_WORKER_SERVICE || 'match-maker-prod-worker' }} - ECS_KEYCLOAK_SERVICE: ${{ vars.ECS_KEYCLOAK_SERVICE || 'match-maker-prod-keycloak' }} - MIGRATE_TASK_FAMILY: ${{ vars.MIGRATE_TASK_FAMILY || 'match-maker-prod-migrate' }} + ECS_CLUSTER: ${{ inputs.environment == 'staging' && 'match-maker-staging-cluster' || vars.ECS_CLUSTER || 'match-maker-prod-cluster' }} + ECS_WEB_SERVICE: ${{ inputs.environment == 'staging' && 'match-maker-staging-web' || vars.ECS_WEB_SERVICE || 'match-maker-prod-web' }} + ECS_WORKER_SERVICE: ${{ inputs.environment == 'staging' && 'match-maker-staging-worker' || vars.ECS_WORKER_SERVICE || 'match-maker-prod-worker' }} + ECS_KEYCLOAK_SERVICE: ${{ inputs.environment == 'staging' && 'match-maker-staging-keycloak' || vars.ECS_KEYCLOAK_SERVICE || 'match-maker-prod-keycloak' }} + MIGRATE_TASK_FAMILY: ${{ inputs.environment == 'staging' && 'match-maker-staging-migrate' || vars.MIGRATE_TASK_FAMILY || 'match-maker-prod-migrate' }} jobs: - # Re-run the fast checks against the exact commit being shipped, so a green - # PR that raced with another merge cannot deploy a broken main. - verify: - name: Verify + # Decides what ships: the pushed commit, or an existing tag on rollback. + plan: + name: Plan release runs-on: ubuntu-latest + environment: ${{ inputs.environment || 'production' }} + outputs: + tag: ${{ steps.plan.outputs.tag }} + rollback: ${{ steps.plan.outputs.rollback }} + promote: ${{ steps.plan.outputs.promote }} steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: "22" - cache: npm - - run: npm ci - - run: npm run typecheck - - run: npx vitest run tests/unit + # A staging run must find staging's own settings, never production's. + - name: Check the target environment + env: + STACK_NAME: ${{ vars.STACK_NAME }} + run: | + set -euo pipefail + if [ "$TARGET" = "staging" ] && [ "${STACK_NAME:-}" != "match-maker-staging" ]; then + echo "::error::Set STACK_NAME=match-maker-staging (and staging's AWS secrets) in the GitHub 'staging' environment first." + exit 1 + fi + + - id: plan + env: + ROLLBACK_TAG: ${{ inputs.rollback_tag }} + PROMOTE_TAG: ${{ inputs.promote_tag }} + run: | + set -euo pipefail + echo "promote=false" >> "$GITHUB_OUTPUT" + if [ -n "${PROMOTE_TAG:-}" ]; then + if [ "$TARGET" != "production" ] || [ -n "${ROLLBACK_TAG:-}" ] || ! [[ "$PROMOTE_TAG" =~ ^[0-9a-f]{7,40}$ ]]; then + echo "::error::promote_tag takes an image tag, targets production, and cannot be combined with rollback_tag." + exit 1 + fi + echo "tag=$PROMOTE_TAG" >> "$GITHUB_OUTPUT" + echo "rollback=false" >> "$GITHUB_OUTPUT" + echo "promote=true" >> "$GITHUB_OUTPUT" + echo "Promoting the staging images tagged $PROMOTE_TAG" + elif [ -n "${ROLLBACK_TAG:-}" ]; then + if ! [[ "$ROLLBACK_TAG" =~ ^[0-9a-f]{7,40}$ ]]; then + echo "::error::rollback_tag must be an image tag (a commit SHA prefix), got '$ROLLBACK_TAG'." + exit 1 + fi + echo "tag=$ROLLBACK_TAG" >> "$GITHUB_OUTPUT" + echo "rollback=true" >> "$GITHUB_OUTPUT" + echo "Rolling back to $ROLLBACK_TAG" + else + # The commit SHA is the tag. `latest` also moves, but every deploy is + # pinned to an immutable tag so a rollback is just a re-deploy of one. + echo "tag=${GITHUB_SHA::12}" >> "$GITHUB_OUTPUT" + echo "rollback=false" >> "$GITHUB_OUTPUT" + fi + + # The full CI suite (lint, typecheck, unit + real-Postgres integration tests, + # Terraform validate) against the exact commit being shipped. Nothing is + # built or pushed unless all of it passes. + ci: + name: Required checks + needs: [plan] + # A promoted tag passed these checks when it was built for staging. + if: needs.plan.outputs.rollback != 'true' && needs.plan.outputs.promote != 'true' + uses: ./.github/workflows/ci.yml + with: + build_images: false build-and-push: name: Build & push images runs-on: ubuntu-latest - needs: [verify] - outputs: - image_tag: ${{ steps.meta.outputs.tag }} + needs: [plan, ci] + if: >- + !cancelled() && needs.plan.result == 'success' && needs.plan.outputs.rollback != 'true' && + (needs.plan.outputs.promote == 'true' || needs.ci.result == 'success') + environment: ${{ inputs.environment || 'production' }} + env: + TAG: ${{ needs.plan.outputs.tag }} steps: - uses: actions/checkout@v4 - - name: Derive image tag - id: meta - # The commit SHA is the tag. `latest` also moves, but every deploy is - # pinned to an immutable tag so a rollback is just a re-deploy of one. - run: echo "tag=${GITHUB_SHA::12}" >> "$GITHUB_OUTPUT" - - uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }} @@ -69,65 +135,112 @@ jobs: - uses: docker/setup-buildx-action@v3 + # The same image digests that passed staging; nothing is rebuilt. Needs + # both stacks' repositories in one AWS account and registry. + - name: Copy the staging images + if: needs.plan.outputs.promote == 'true' + env: + REGISTRY: ${{ steps.ecr.outputs.registry }} + run: | + set -euo pipefail + repos="web migrate worker" + if [ "${{ inputs.deploy_keycloak }}" = "true" ]; then repos="$repos keycloak"; fi + for repo in $repos; do + docker buildx imagetools create \ + --tag "$REGISTRY/$STACK/$repo:$TAG" --tag "$REGISTRY/$STACK/$repo:latest" \ + "$REGISTRY/match-maker-staging/$repo:$TAG" + done + - name: Build & push web + if: needs.plan.outputs.promote != 'true' uses: docker/build-push-action@v6 with: context: . file: apps/web/Dockerfile push: true + build-args: APP_VERSION=${{ env.TAG }} tags: | - ${{ steps.ecr.outputs.registry }}/match-maker-prod/web:${{ steps.meta.outputs.tag }} - ${{ steps.ecr.outputs.registry }}/match-maker-prod/web:latest + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/web:${{ env.TAG }} + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/web:latest cache-from: type=gha cache-to: type=gha,mode=max - name: Build & push migrate + if: needs.plan.outputs.promote != 'true' uses: docker/build-push-action@v6 with: context: . file: infra/docker/migrate.Dockerfile push: true tags: | - ${{ steps.ecr.outputs.registry }}/match-maker-prod/migrate:${{ steps.meta.outputs.tag }} - ${{ steps.ecr.outputs.registry }}/match-maker-prod/migrate:latest + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/migrate:${{ env.TAG }} + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/migrate:latest cache-from: type=gha cache-to: type=gha,mode=max - name: Build & push worker + if: needs.plan.outputs.promote != 'true' uses: docker/build-push-action@v6 with: context: . file: infra/docker/worker.Dockerfile push: true + build-args: APP_VERSION=${{ env.TAG }} tags: | - ${{ steps.ecr.outputs.registry }}/match-maker-prod/worker:${{ steps.meta.outputs.tag }} - ${{ steps.ecr.outputs.registry }}/match-maker-prod/worker:latest + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/worker:${{ env.TAG }} + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/worker:latest cache-from: type=gha cache-to: type=gha,mode=max - name: Build & push Keycloak - if: inputs.deploy_keycloak + if: inputs.deploy_keycloak && needs.plan.outputs.promote != 'true' uses: docker/build-push-action@v6 with: context: . file: infra/docker/keycloak.Dockerfile push: true tags: | - ${{ steps.ecr.outputs.registry }}/match-maker-prod/keycloak:${{ steps.meta.outputs.tag }} - ${{ steps.ecr.outputs.registry }}/match-maker-prod/keycloak:latest + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/keycloak:${{ env.TAG }} + ${{ steps.ecr.outputs.registry }}/${{ env.STACK }}/keycloak:latest cache-from: type=gha cache-to: type=gha,mode=max migrate: name: Run migrations runs-on: ubuntu-latest - needs: [build-and-push] + needs: [plan, build-and-push] + if: >- + !cancelled() && needs.plan.outputs.rollback != 'true' && needs.build-and-push.result == 'success' + environment: ${{ inputs.environment || 'production' }} + env: + TAG: ${{ needs.plan.outputs.tag }} steps: - uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }} aws-region: ${{ env.AWS_REGION }} + # Running the family name would start its newest revision, which points + # at the mutable `latest` tag. Register a revision pinned to this release + # so exactly the migrator that was just built runs. + - name: Pin migrate task definition to the new image + id: migrate-taskdef + run: | + set -euo pipefail + REGISTRY="$(aws sts get-caller-identity --query Account --output text).dkr.ecr.${AWS_REGION}.amazonaws.com" + aws ecs describe-task-definition --task-definition "$MIGRATE_TASK_FAMILY" \ + --query 'taskDefinition' > migrate-taskdef.json + jq --arg IMAGE "$REGISTRY/$STACK/migrate:$TAG" ' + .containerDefinitions[0].image = $IMAGE + | del(.taskDefinitionArn, .revision, .status, .requiresAttributes, + .compatibilities, .registeredAt, .registeredBy, .deregisteredAt) + ' migrate-taskdef.json > new-migrate-taskdef.json + NEW_ARN=$(aws ecs register-task-definition \ + --cli-input-json file://new-migrate-taskdef.json \ + --query 'taskDefinition.taskDefinitionArn' --output text) + echo "arn=$NEW_ARN" >> "$GITHUB_OUTPUT" + echo "Registered $NEW_ARN" + # Migrations run BEFORE the new tasks roll out, so they must be # backwards-compatible with the version currently serving traffic. - name: Run migration task and wait @@ -136,7 +249,7 @@ jobs: TASK_ARN=$(aws ecs run-task \ --cluster "$ECS_CLUSTER" \ - --task-definition "$MIGRATE_TASK_FAMILY" \ + --task-definition "${{ steps.migrate-taskdef.outputs.arn }}" \ --launch-type FARGATE \ --network-configuration "awsvpcConfiguration={subnets=[${{ secrets.PRIVATE_SUBNET_IDS }}],securityGroups=[${{ secrets.TASK_SECURITY_GROUP_ID }}],assignPublicIp=DISABLED}" \ --query 'tasks[0].taskArn' --output text) @@ -151,14 +264,22 @@ jobs: echo "Exit code: $EXIT_CODE ($REASON)" if [ "$EXIT_CODE" != "0" ]; then - echo "::error::Migration failed — aborting deploy. Check /ecs/match-maker-prod/migrate." + echo "::error::Migration failed — aborting deploy. Check /ecs/$STACK/migrate." exit 1 fi deploy: name: Roll out runs-on: ubuntu-latest - needs: [build-and-push, migrate] + needs: [plan, build-and-push, migrate] + environment: ${{ inputs.environment || 'production' }} + # A rollback skips checks, build and migrations (the schema only moves + # forward); a normal release needs all of them to have succeeded. + if: >- + !cancelled() && needs.plan.result == 'success' && + (needs.plan.outputs.rollback == 'true' || needs.migrate.result == 'success') + env: + TAG: ${{ needs.plan.outputs.tag }} steps: - uses: actions/checkout@v4 @@ -167,20 +288,58 @@ jobs: role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }} aws-region: ${{ env.AWS_REGION }} + - name: Check the rollback images exist + if: needs.plan.outputs.rollback == 'true' + run: | + set -euo pipefail + repos="web worker" + if [ "${{ inputs.deploy_keycloak }}" = "true" ]; then repos="$repos keycloak"; fi + for repo in $repos; do + aws ecr describe-images --repository-name "$STACK/$repo" \ + --image-ids imageTag="$TAG" >/dev/null \ + || { echo "::error::No $repo image tagged $TAG in ECR."; exit 1; } + done + + # Remembered so a failed smoke test can put these back. + - name: Record the revisions currently serving + id: previous + run: | + set -euo pipefail + for svc in web worker; do + name_var="ECS_${svc^^}_SERVICE" + arn=$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "${!name_var}" \ + --query 'services[0].taskDefinition' --output text) + echo "$svc=$arn" >> "$GITHUB_OUTPUT" + echo "$svc is serving $arn" + done + - name: Pin web task definition to the new image id: taskdef run: | set -euo pipefail - TAG="${{ needs.build-and-push.outputs.image_tag }}" REGISTRY="$(aws sts get-caller-identity --query Account --output text).dkr.ecr.${AWS_REGION}.amazonaws.com" - aws ecs describe-task-definition \ - --task-definition "$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$ECS_WEB_SERVICE" --query 'services[0].taskDefinition' --output text)" \ + # Start from the family's newest revision, not the one the service is + # running, so settings and secrets changed by Terraform ship too. + FAMILY=$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$ECS_WEB_SERVICE" \ + --query 'services[0].taskDefinition' --output text | sed -E 's#^.*task-definition/([^:]+):[0-9]+$#\1#') + aws ecs describe-task-definition --task-definition "$FAMILY" \ --query 'taskDefinition' > taskdef.json + # Production login must send real e-mail: never ship the dev fallback, + # and require the Resend key (an empty value fails the app's startup check). + if jq -e '[.containerDefinitions[].environment[]? | select(.name == "EMAIL_DEV_FALLBACK" and .value == "true")] | length > 0' taskdef.json >/dev/null; then + echo "::error::EMAIL_DEV_FALLBACK=true is set on the web task; login codes would be logged instead of sent." + exit 1 + fi + if ! jq -e '[.containerDefinitions[].secrets[]? | select(.name == "RESEND_API_KEY")] | length > 0' taskdef.json >/dev/null; then + echo "::error::The web task has no RESEND_API_KEY secret; login e-mail cannot be delivered." + exit 1 + fi + # Strip the server-managed fields that RegisterTaskDefinition rejects, # then point the container at the immutable tag. - jq --arg IMAGE "$REGISTRY/match-maker-prod/web:$TAG" ' + jq --arg IMAGE "$REGISTRY/$STACK/web:$TAG" ' .containerDefinitions[0].image = $IMAGE | del(.taskDefinitionArn, .revision, .status, .requiresAttributes, .compatibilities, .registeredAt, .registeredBy, .deregisteredAt) @@ -205,14 +364,14 @@ jobs: id: worker-taskdef run: | set -euo pipefail - TAG="${{ needs.build-and-push.outputs.image_tag }}" REGISTRY="$(aws sts get-caller-identity --query Account --output text).dkr.ecr.${AWS_REGION}.amazonaws.com" - aws ecs describe-task-definition \ - --task-definition "$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$ECS_WORKER_SERVICE" --query 'services[0].taskDefinition' --output text)" \ + FAMILY=$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$ECS_WORKER_SERVICE" \ + --query 'services[0].taskDefinition' --output text | sed -E 's#^.*task-definition/([^:]+):[0-9]+$#\1#') + aws ecs describe-task-definition --task-definition "$FAMILY" \ --query 'taskDefinition' > worker-taskdef.json - jq --arg IMAGE "$REGISTRY/match-maker-prod/worker:$TAG" ' + jq --arg IMAGE "$REGISTRY/$STACK/worker:$TAG" ' .containerDefinitions[0].image = $IMAGE | del(.taskDefinitionArn, .revision, .status, .requiresAttributes, .compatibilities, .registeredAt, .registeredBy, .deregisteredAt) @@ -232,39 +391,84 @@ jobs: --task-definition "${{ steps.worker-taskdef.outputs.arn }}" \ --query 'service.deployments[0].id' --output text - - name: Force Keycloak rollout + # Forcing a new deployment would restart Keycloak's current revision, + # which points at `latest`; pin it to the tag that was just built. + - name: Pin and roll out Keycloak if: inputs.deploy_keycloak run: | - aws ecs update-service \ - --cluster "$ECS_CLUSTER" \ - --service "$ECS_KEYCLOAK_SERVICE" \ - --force-new-deployment >/dev/null + set -euo pipefail + REGISTRY="$(aws sts get-caller-identity --query Account --output text).dkr.ecr.${AWS_REGION}.amazonaws.com" + FAMILY=$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$ECS_KEYCLOAK_SERVICE" \ + --query 'services[0].taskDefinition' --output text | sed -E 's#^.*task-definition/([^:]+):[0-9]+$#\1#') + aws ecs describe-task-definition --task-definition "$FAMILY" \ + --query 'taskDefinition' > keycloak-taskdef.json + jq --arg IMAGE "$REGISTRY/$STACK/keycloak:$TAG" ' + .containerDefinitions[0].image = $IMAGE + | del(.taskDefinitionArn, .revision, .status, .requiresAttributes, + .compatibilities, .registeredAt, .registeredBy, .deregisteredAt) + ' keycloak-taskdef.json > new-keycloak-taskdef.json + NEW_ARN=$(aws ecs register-task-definition \ + --cli-input-json file://new-keycloak-taskdef.json \ + --query 'taskDefinition.taskDefinitionArn' --output text) + aws ecs update-service --cluster "$ECS_CLUSTER" --service "$ECS_KEYCLOAK_SERVICE" \ + --task-definition "$NEW_ARN" >/dev/null + echo "Keycloak rolling out $NEW_ARN" - # The service's deployment circuit breaker rolls back automatically on - # failure; this makes the workflow reflect that outcome. - name: Wait for the service to stabilise run: | aws ecs wait services-stable --cluster "$ECS_CLUSTER" --services "$ECS_WEB_SERVICE" "$ECS_WORKER_SERVICE" echo "Web and worker deployments are stable." + # The deployment circuit breaker rolls a failed rollout back, after which + # the service is "stable" on the OLD revision. Check what is serving. + - name: Confirm the new revisions are serving + run: | + set -euo pipefail + check() { + local service=$1 expected=$2 serving + serving=$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$service" \ + --query "services[0].deployments[?status=='PRIMARY'].taskDefinition | [0]" --output text) + if [ "$serving" != "$expected" ]; then + echo "::error::$service is serving $serving, not $expected (ECS rolled the deployment back)." + return 1 + fi + echo "$service is serving $expected" + } + check "$ECS_WEB_SERVICE" "${{ steps.taskdef.outputs.arn }}" + check "$ECS_WORKER_SERVICE" "${{ steps.worker-taskdef.outputs.arn }}" + - name: Smoke test + env: + URL: ${{ vars.APP_BASE_URL }} run: | set -euo pipefail - URL="${{ vars.APP_BASE_URL }}" if [ -z "$URL" ]; then - echo "APP_BASE_URL variable not set — skipping smoke test." - exit 0 + echo "::error::Set the APP_BASE_URL repository variable; a release is not verified without a smoke test." + exit 1 fi - echo "Checking $URL/api/health/ready" for attempt in 1 2 3 4 5; do - if curl -fsS --max-time 15 "$URL/api/health/ready" | tee /tmp/ready.json; then + version=$(curl -fsS --max-time 15 "$URL/api/health" | jq -r '.version' || true) + if [ "$version" = "$TAG" ] && curl -fsS --max-time 15 "$URL/api/health/ready" | tee /tmp/ready.json; then echo + echo "$URL is serving $TAG and its dependencies are ready." exit 0 fi - echo "attempt $attempt failed; retrying in 10s" + echo "attempt $attempt: serving '${version:-nothing}', expected '$TAG'; retrying in 10s" sleep 10 done - echo "::error::Readiness check never passed after deploy." + echo "::error::Smoke test failed for $TAG." exit 1 + + - name: Roll back to the previous revisions + if: failure() && steps.previous.outputs.web != '' + run: | + set -euo pipefail + echo "::warning::Deploy of $TAG failed; restoring the revisions that were serving before." + aws ecs update-service --cluster "$ECS_CLUSTER" --service "$ECS_WEB_SERVICE" \ + --task-definition "${{ steps.previous.outputs.web }}" >/dev/null + aws ecs update-service --cluster "$ECS_CLUSTER" --service "$ECS_WORKER_SERVICE" \ + --task-definition "${{ steps.previous.outputs.worker }}" >/dev/null + aws ecs wait services-stable --cluster "$ECS_CLUSTER" --services "$ECS_WEB_SERVICE" "$ECS_WORKER_SERVICE" + echo "Restored ${{ steps.previous.outputs.web }} and ${{ steps.previous.outputs.worker }}." diff --git a/.gitignore b/.gitignore index 22f52aa..88b2c56 100644 --- a/.gitignore +++ b/.gitignore @@ -68,6 +68,8 @@ infra/terraform/*.tfstate infra/terraform/*.tfstate.* infra/terraform/*.tfvars !infra/terraform/*.tfvars.example +infra/terraform/environments/*.tfvars +!infra/terraform/environments/*.tfvars.example infra/terraform/*.tfplan infra/terraform/.terraform.lock.hcl infra/terraform/override.tf @@ -116,7 +118,8 @@ temp/ *.swp *.swo *~ -.claude/settings.local.json +# Local Claude Code settings and agents; never pushed. +.claude/ # OS files .DS_Store diff --git a/ReadMe.md b/ReadMe.md index f003029..6a6b387 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -4,7 +4,7 @@ Mr. Bridge is a multi event networking and matchmaking app. Organizers create ev The implementation follows the architecture described in [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md). The [end-to-end flow](docs/END_TO_END_FLOW.md) and [matching pipeline](docs/BRIDGE_ENGINE_PIPELINE.md) docs show the product journeys. -See the [production roadmap](docs/PRODUCTION_ROADMAP.md) for authentication findings, the invited-account signup policy, Google setup, and remaining work ordered by implementation effort. +See the [production roadmap](docs/PRODUCTION_ROADMAP.md) for authentication findings, the invited-account signup policy, Google setup, and remaining work ordered by implementation effort. The [operations runbook](docs/OPERATIONS.md) covers releases, staging, rollback, alarms, database restore, secret rotation and the launch checklist. ## Architecture @@ -102,11 +102,20 @@ The first command imports the global attendee directory so the organizer account | `npm run build` | Build workspace packages and the app | | `npm run typecheck` | Type-check all workspaces | | `npm run lint` | Run ESLint | -| `npm test` | Run unit and integration suites | +| `npm test` | Run unit and integration suites. Integration suites skip without Postgres/Keycloak; set `REQUIRE_SERVICES=db,keycloak` to fail instead (CI does, and `tools/check-test-report.ts` fails on any skipped test). Stop a locally running worker first, or it claims the pipeline test's jobs | +| `npm run test:e2e` | Browser acceptance suite (Playwright) against a running app and worker started with `EMAIL_DEV_FALLBACK=true`; set `E2E_BASE_URL` and `E2E_WEB_LOG` (the app's output, where login codes are read) | | `npm run db:migrate` | Apply pending PostgreSQL migrations | +| `npm run capacity:check` | Measure matching throughput, search latency and model calls for an event size against the budgets in the runbook | +| `npm run db:verify` / `db:restore-rehearsal` | Check a database (or a restored copy) is usable; rehearse dump and restore locally | | `npm run db:seed` | Upsert demo roster, organization, event, and organizer | | `npm run db:import -- [event-slug]` | Import attendee rows and optionally attach them to an event | | `npm run keycloak:wait` | Wait for the configured Keycloak realm to respond | +| `npm run keycloak:sync` | Bring an existing realm up to date: client secret, Google credentials, the account-linking flow (Google joins an account an e-mail code created), and the site login theme. Run after the first Keycloak start and after upgrades | +| `npm run account:disable -- ` | Block sign-in and end every session (database and Keycloak); `account:enable` undoes it | +| `npm run account:revoke-sessions -- ` | Sign the person out everywhere without disabling the account | +| `npm run jobs:failed` | List background matching jobs that failed after every retry, with their last error | +| `npm run jobs:retry -- ` | Queue failed jobs again with fresh attempts | +| `npm run account:erase -- --yes` | Deletion request: delete the person, their event profiles, matches, introductions, cached explanations and Keycloak user (recorded in the audit log) | | `npm run docker:up` | Build images and start the local Compose stack | `DATABASE_URL` should point at `localhost` for commands run on the host. Compose sets the service hostname `postgres` inside containers. @@ -125,6 +134,22 @@ See `.env.example` for the full list. The main settings are: | `DEFAULT_EVENT_SLUG` | Event used by the `/` redirect | | `SEED_ON_MIGRATE` | Seeds demo data in the local stack; leave false in production | +## Activating real e-mail and Google sign-in + +Locally, login codes are printed to the web log (`EMAIL_DEV_FALLBACK=true`) and the Google option is hidden. To switch on the real services: + +1. **E-mail:** verify a sending domain in [Resend](https://resend.com), then set `RESEND_API_KEY` and `EMAIL_FROM` (for example `Mr. Bridge `). Set `EMAIL_DEV_FALLBACK=false` to prove delivery works. +2. **Google:** create an OAuth web client in Google Cloud Console with the authorised redirect URI `http://localhost:8080/realms/match-maker/broker/google/endpoint` (use your Keycloak host in other environments). Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. +3. Apply the credentials to the running realm and restart the web app: + + ```powershell + npm run keycloak:sync + ``` + + Keycloak imports `realm-export.json` only on first boot, so editing `.env` alone does not update an existing realm. + +In AWS, put the same values in the app's Secrets Manager secret (see `terraform output`). The web app refuses to start without `RESEND_API_KEY`, and the deploy workflow rejects a web task that enables `EMAIL_DEV_FALLBACK` or lacks the Resend secret. + ## Docker and deployment Build from the repository root: diff --git a/apps/web/Dockerfile b/apps/web/Dockerfile index e5ad9a0..e5fffc4 100644 --- a/apps/web/Dockerfile +++ b/apps/web/Dockerfile @@ -56,6 +56,16 @@ COPY --from=builder --chown=node:node /repo/apps/web/.next/standalone ./ COPY --from=builder --chown=node:node /repo/apps/web/.next/static ./apps/web/.next/static COPY --from=builder --chown=node:node /repo/apps/web/public ./apps/web/public +# Amazon's RDS CA bundle, so DATABASE_SSL=verify can check the database +# certificate (DATABASE_CA_CERT_FILE points here in the task definitions). +ADD --chmod=644 https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /etc/ssl/certs/rds-global-bundle.pem + +# The release tag (commit SHA) the deploy built, reported by /api/health so +# smoke tests and rollbacks can tell which version is serving. Declared late +# so a new tag does not invalidate the cached layers above. +ARG APP_VERSION=dev +ENV APP_VERSION=$APP_VERSION + USER node EXPOSE 3000 diff --git a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx index ea60a5e..f246a3f 100644 --- a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx +++ b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/analytics/page.tsx @@ -1,25 +1,51 @@ import Link from "next/link"; +import SignOutButton from "@/components/ui/SignOutButton"; import { requireOrganizerEvent } from "@/src/lib/auth"; export default async function AnalyticsPage({ params }: { params: Promise<{ orgSlug: string; eventSlug: string }> }) { const { orgSlug, eventSlug } = await params; const { event, container } = await requireOrganizerEvent(orgSlug, eventSlug); - const analytics = await container.events.analytics(event.id); + const [analytics, activity] = await Promise.all([container.events.analytics(event.id), container.audit.recent(event.id)]); const completion = analytics.roster ? Math.round(analytics.profiles / analytics.roster * 100) : 0; return
- +

Event analytics

{event.name} · {event.status}

- + + +
+

Recent activity

+ {!activity.length ?

No recorded activity yet.

:
    + {activity.map((item) =>
  • + {ACTIVITY_LABELS[item.action] ?? item.action} + {item.subjectName && <> · {item.subjectName}} +
    {item.actorName ?? "System"} · {item.createdAt.toLocaleString("en-IN", { dateStyle: "medium", timeStyle: "short" })}{summary(item.details)} +
  • )} +
}
; } +const ACTIVITY_LABELS: Record = { + "roster.imported": "Roster imported", + "invitations.sent": "Invitations sent", + "access.removed": "Access removed", + "access.restored": "Access restored", + "event.updated": "Settings changed", + "profile_form.updated": "Profile form changed", + "contacts.revealed": "Introduction accepted, contacts shared", +}; + +function summary(details: Record): string { + const parts = ["attached", "sent", "failed", "version"].filter((key) => typeof details[key] === "number").map((key) => `${key} ${details[key]}`); + return parts.length ? ` · ${parts.join(", ")}` : ""; +} + function Card({ label, value, note }: { label: string; value: number | string; note?: string }) { return
{label}{value}{note && {note}}
; } diff --git a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/matching/page.tsx b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/matching/page.tsx index e8b4050..967ca4e 100644 --- a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/matching/page.tsx +++ b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/matching/page.tsx @@ -1,6 +1,14 @@ import Link from "next/link"; +import SignOutButton from "@/components/ui/SignOutButton"; import { computeEventMatchesAction } from "../../../../../../actions/organizer.actions"; import { requireOrganizerEvent } from "@/src/lib/auth"; +import { ActionForm } from "@/components/ui/form"; +import { getEventQueueSummary } from "@/src/application/use-cases/get-match-status"; +import { eventAllows } from "@/src/domain/shared/event-lifecycle"; + +const QUEUE_LABELS = [ + ["queued", "Queued"], ["running", "Running"], ["stuck", "Stuck (running over 10 min)"], ["failed", "Failed"], ["done", "Finished"], +] as const; export default async function MatchingPage({ params, searchParams }: { params: Promise<{ orgSlug: string; eventSlug: string }>; @@ -9,21 +17,33 @@ export default async function MatchingPage({ params, searchParams }: { const { orgSlug, eventSlug } = await params; const query = await searchParams; const { event, container } = await requireOrganizerEvent(orgSlug, eventSlug); - const analytics = await container.events.analytics(event.id); + const [analytics, queue] = await Promise.all([ + container.events.analytics(event.id), + getEventQueueSummary({ eventId: event.id }, container.matchQueue), + ]); const action = computeEventMatchesAction.bind(null, orgSlug, eventSlug); return
- +

Matching pipeline

Embeddings and ranked matches run in the background for profiles already completed.

- {query.queued &&

Queued profile matching for {query.queued} attendee(s).

} + {query.queued &&

Queued profile matching for {query.queued} attendee(s).

}
{analytics.profiles} completed profiles
{analytics.matches} saved match results
-
+ {eventAllows(event.status, "computeMatches") + ? + :

This event is closed. Reopen it from the dashboard to compute matches again.

}
- {event.status !== "open" &&

Registration is currently {event.status}. Starting matching opens the event to participants.

} + {event.status === "draft" &&

Registration is currently draft. Starting matching opens the event to participants.

} +

Queue

+

Where each participant's latest matching job stands.

+
+ {QUEUE_LABELS.map(([key, label]) =>
{label}
{queue[key]}
)} +
+ {(queue.failed > 0 || queue.stuck > 0) &&

Some participants have no fresh matches. “Compute matches” queues failed and stuck participants again.

}
; } const shell = { minHeight: "100vh", maxWidth: 900, margin: "0 auto", padding: "36px 24px", color: "#f4f4f5" } as const; const card = { display: "flex", justifyContent: "space-between", flexWrap: "wrap", gap: 20, alignItems: "center", padding: 24, background: "#151519", border: "1px solid #333", borderRadius: 12, marginTop: 24 } as const; -const button = { border: 0, borderRadius: 8, padding: 14, background: "#f59e0b", color: "#0a0a0e", fontWeight: 700, cursor: "pointer" } as const; +const grid = { display: "grid", gridTemplateColumns: "repeat(auto-fit,minmax(140px,1fr))", gap: 12, margin: "16px 0" } as const; +const stat = { display: "grid", gap: 6, padding: 16, borderRadius: 12, background: "#151519", border: "1px solid #333" } as const; diff --git a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/page.tsx b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/page.tsx index 1d7627a..6c5e849 100644 --- a/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/page.tsx +++ b/apps/web/app/(organizer)/orgs/[orgSlug]/events/[eventSlug]/page.tsx @@ -1,10 +1,18 @@ import Link from "next/link"; -import { updateEventAction } from "../../../../../actions/organizer.actions"; +import SignOutButton from "@/components/ui/SignOutButton"; +import { updateEventAction, updateProfileFormAction } from "../../../../../actions/organizer.actions"; +import ProfileFormSettings from "@/components/organizer/ProfileFormSettings"; +import { readProfileForm } from "@/src/domain/participant/profile-form"; import { requireOrganizerEvent } from "@/src/lib/auth"; +import { EventSetupForm } from "@/components/organizer/EventForms"; -export default async function EventDashboardPage({ params }: { params: Promise<{ orgSlug: string; eventSlug: string }> }) { +export default async function EventDashboardPage({ params, searchParams }: { + params: Promise<{ orgSlug: string; eventSlug: string }>; + searchParams: Promise<{ saved?: string; form?: string }>; +}) { const { orgSlug, eventSlug } = await params; - const { event, container } = await requireOrganizerEvent(orgSlug, eventSlug); + const notice = await searchParams; + const { event, container, can } = await requireOrganizerEvent(orgSlug, eventSlug); const analytics = await container.events.analytics(event.id); const action = updateEventAction.bind(null, orgSlug, eventSlug); return
@@ -16,7 +24,7 @@ export default async function EventDashboardPage({ params }: { params: Promise<{ Matching Analytics Create event - +
@@ -24,16 +32,18 @@ export default async function EventDashboardPage({ params }: { params: Promise<{

Event setup

-
- -