Skip to content

Operations, CI/CD & Deployment Runbook (HUB-OPS-001)

Field Value
Document ID HUB-OPS-001
Pillar Software Engineering
Standard Alignment ISO/IEC/IEEE 26514 / SRE Runbook Standard
Status Active / Synchronized with Codebase
Last Updated 2026-11-21
Source of Truth .github/workflows/portal.yml, Dockerfile, docker-compose.yml, nginx.conf, vercel.json, .env.example, ops/deploy-ssh.sh, ops/release-on-vm.sh, ops/p3mdi-sso/Dockerfile, ops/p3mdi-sso/compose.yaml, ops/authentik/README.md, google-apps-script/Code.gs, scripts/generate-master-sql.mjs, docs/SECURITY.md, docs/p3mdi-sso.md

Soedirman Hub runs in three primary topologies:

  1. Local Development (npm run dev or docker compose up --build -d): Vite 6 hot-reload server or local Docker container (127.0.0.1:${PORTAL_PORT:-8080}:80) backed by a Supabase project (or ?demo=true offline synthetic sandbox).
  2. Production VM Edge (https://app.p3mdi.id): Containerized static SPA served by nginxinc/nginx-unprivileged (UID 101, port 80) under /opt/legacy-batch-p3md, paired with the Traefik-routed Deno SSO & Core Broker (ops/p3mdi-sso/ on :8000) and external P3MDI Authentik IdP (https://auth.p3mdi.id).
  3. Static Preview / Alternative Edge (vercel.json): Compatible SPA rewrite + identical security header configuration for Vercel static builds.
flowchart TD
    Push["GitHub PR / Push to main"] -->|"Job 1: security"| Sec["npm audit --audit-level=high + Gitleaks Scan"]
    Push -->|"Job 2: build"| Build["npm test (240 tests) + Deno Test + Postgres SQL Test + npm run build"]
    Build -->|"Site Bundle Artifact"| Art["site.tar.gz + site.tar.gz.sha256"]
    Sec --> Gate{"main push & PORTAL_AUTO_DEPLOY == 'true'?"}
    Build --> Gate
    Gate -->|Yes| DBCheck["POST portal_critical_batch_ready & portal_pengasuh_release_ready"]
    DBCheck -->|"Both true"| SSH["Forced-Command SSH -> ops/deploy-ssh.sh"]
    SSH -->|"flock lock"| VM["ops/release-on-vm.sh (Build Container + Tag last-good + Health Verify)"]
    VM -->|"/healthz or asset cmp fails"| Rollback["Automatic Rollback to legacy-batch-p3md:last-good"]

2. Environment Variables & Configuration Catalog

Section titled “2. Environment Variables & Configuration Catalog”

2.1 Frontend Build & Runtime Variables (.env.example, Dockerfile, .github/workflows/portal.yml)

Section titled “2.1 Frontend Build & Runtime Variables (.env.example, Dockerfile, .github/workflows/portal.yml)”

(Vite embeds VITE_* variables statically into dist/ at npm run build time.)

Variable Required Used By Purpose
VITE_SUPABASE_URL Yes (fails closed if missing) src/lib/supabase.js HTTPS Supabase project URL (http://localhost / 127.0.0.1 allowed locally).
VITE_SUPABASE_ANON_KEY Yes (fails closed if missing) src/lib/supabase.js Supabase publishable/anon key sent in apikey header (never use service_role / sb_secret_ here).
VITE_GDRIVE_WEBHOOK_URL For photo uploads src/lib/supabase.js HTTPS script.google.com or script.googleusercontent.com /exec URL (VITE_GAS_UPLOAD_URL supported as fallback).
VITE_GDRIVE_FOLDER_URL Optional src/store/portal.js External Google Drive root folder quick-link displayed in Dokumentasi UI.
VITE_NOMINATIM_REVERSE_URL Optional src/components/absensi/LivePhotoModal.vue Same-origin reverse geocoding proxy (e.g., /api/geocoding/reverse) for coarse photo labels.
VITE_GOOGLE_MAPS_API_KEY Optional .env.example, PetaPersebaranView.vue Build-time Maps JS key alternative to user-supplied browser key.
PORTAL_PORT Local Docker docker-compose.yml Host loopback port mapped to container :80 (default 8080).

2.2 Deno SSO & Core Broker Variables (ops/p3mdi-sso/Dockerfile & compose.yaml)

Section titled “2.2 Deno SSO & Core Broker Variables (ops/p3mdi-sso/Dockerfile & compose.yaml)”

The container runs under UID deno with strict --allow-env=... enumeration:

Variable Required Used By Purpose
P3MDI_OIDC_CLIENT_ID Yes index.ts, profile.ts Public OIDC client identifier returned on GET /api/sso.
P3MDI_OIDC_CLIENT_SECRET Yes index.ts, profile.ts, security.ts Confidential OIDC secret for /application/o/token/.
P3MDI_HUB_ORIGIN Yes index.ts, profile.ts, security.ts Exact origin enforced on Origin header (https://app.p3mdi.id) & OIDC redirect_uri.
P3MDI_HUB_PUBLIC_KEY Yes profile.ts, accounts.ts Supabase publishable/anon key used to validate caller sessions via portal_me.
P3MDI_ACCOUNT_API_TOKEN Yes profile.ts, security.ts, accounts.ts Bearer token for https://auth.p3mdi.id/api/v3/core/*.
P3MDI_SERDIK_GROUP_ID Yes profile.ts, security.ts, accounts.ts Target Authentik group UUID/PK (Soedirman Hub Serdik).
SUPABASE_URL Yes index.ts, profile.ts, accounts.ts, core.ts Supabase project base URL.
SUPABASE_SECRET_KEY Yes (sb_secret_*) index.ts, profile.ts, accounts.ts, core.ts Privileged Supabase API key passed only from broker -> PostgREST RPCs.
P3MDI_CORE_URL Optional core.ts Core Directory base URL (defaults to https://core.p3mdi.id).
P3MDI_CORE_TOKEN For /api/sso/core core.ts Bearer token for /v1/bridge/members/*.

2.3 External Integrations (Code.gs, GitHub Actions, Authentik)

Section titled “2.3 External Integrations (Code.gs, GitHub Actions, Authentik)”
  • Google Apps Script Properties (google-apps-script/Code.gs): SUPABASE_URL, SUPABASE_ANON_KEY. Optional script constant SPECIFIC_FOLDER_ID pins an existing Drive folder instead of creating P3MD_Grup1_Dokumentasi.
  • GitHub Actions (portal.yml): Repository vars PORTAL_AUTO_DEPLOY, VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, VITE_GDRIVE_WEBHOOK_URL, VITE_GDRIVE_FOLDER_URL, VITE_NOMINATIM_REVERSE_URL, PORTAL_SSH_KNOWN_HOSTS; Repository secret PORTAL_DEPLOY_KEY.
  • Authentik Custom App (ops/authentik/README.md): Mount ops/authentik/p3mdi_hub read-only (/p3mdi_hub:ro) into Authentik server & worker, register p3mdi_hub.apps.HubConfig in INSTALLED_APPS, grant global authentik_core.add_user to role Soedirman Hub Serdik Activation, and run the one-time Django shell sync_user loop.

3. CI/CD Pipeline & Atomic VM Release (.github/workflows/portal.yml)

Section titled “3. CI/CD Pipeline & Atomic VM Release (.github/workflows/portal.yml)”

3.1 Pull Request & Main CI Jobs (ubuntu-24.04)

Section titled “3.1 Pull Request & Main CI Jobs (ubuntu-24.04)”
  1. security Job:
    • Checks out full commit history (fetch-depth: 0, persist-credentials: false).
    • Runs npm audit --audit-level=high (Node 22).
    • Scans entire reachable Git history with pinned ghcr.io/gitleaks/gitleaks (git --redact --log-opts=HEAD .).
  2. build Job:
    • npm ci --ignore-scripts -> npm test (240 Node tests).
    • Builds ops/p3mdi-sso Docker image (runs deno check --no-lock index.ts during image build) and runs setup_test.ts, security_test.ts, and accounts_test.ts inside Deno.
    • Boots ephemeral postgres:16-alpine (--network none), copies tests/ + supabase/, and executes psql -f /tests/sql/sso-management.test.sql.
    • Builds production SPA (npm run build), archives dist/ into site.tar.gz + site.tar.gz.sha256, and uploads portal-<sha> artifact (7-day retention).

3.2 Gated Production Deployment (deploy Job)

Section titled “3.2 Gated Production Deployment (deploy Job)”

Triggered only on pushes to main when vars.PORTAL_AUTO_DEPLOY == 'true':

  1. Verifies site.tar.gz.sha256 and checks GitHub API confirming github.sha is still refs/heads/main HEAD (prevents stale concurrent overwrites).
  2. Queries Supabase RPCs portal_critical_batch_ready and portal_pengasuh_release_ready with curl. If either returns anything other than true, skips release gracefully with an operator notice until pending migrations are applied.
  3. Streams site.tar.gz over pinned SSH (BatchMode=yes, StrictHostKeyChecking=yes) to forced-command wrapper ops/deploy-ssh.sh (portal-deploy@76.13.21.243 "deploy $GITHUB_SHA $GITHUB_RUN_NUMBER").

3.3 VM Execution & Automatic Rollback (ops/deploy-ssh.sh & ops/release-on-vm.sh)

Section titled “3.3 VM Execution & Automatic Rollback (ops/deploy-ssh.sh & ops/release-on-vm.sh)”
  • ops/deploy-ssh.sh enforces strict ^deploy ([0-9a-f]{40}) ([1-9][0-9]{0,11})$ regex validation and delegates to /usr/local/sbin/portal-release or legacy-portal-release via sudo -n.
  • ops/release-on-vm.sh executes inside /opt/legacy-batch-p3md:
    • Acquires exclusive flock (/run/lock/legacy-portal-release.lock) and discards out-of-order run numbers (last-release-run).
    • Streams tar safely via Python tarfile (filter="data", hard <= 100 MB size bound), verifies non-empty index.html and primary /assets/*.js chunk.
    • Tags running container image as legacy-batch-p3md:last-good and builds legacy-batch-p3md:release-<sha> atop pinned nginxinc/nginx-unprivileged SHA-256 digest.
    • Updates compose.override.yaml atomically and runs docker compose up -d --no-build --wait --wait-timeout 90.
    • Runs live parity verification against https://app.p3mdi.id/healthz (ok), /login (byte-equal index.html), and /assets/*.js. Any mismatch triggers immediate restore to legacy-batch-p3md:last-good and non-zero exit.

4. Database Migration, Backup & Seeding Runbook

Section titled “4. Database Migration, Backup & Seeding Runbook”
  1. Pre-Deploy Migration Order: Always apply new SQL files under supabase/migrations/ chronologically in Supabase SQL Editor (or Postgres superuser session owning public.serdik) before promoting frontend code.
    • Specifically, when 20261130060000 (portal_critical_batch_ready) and 20261130070000 (portal_pengasuh_release_ready) are applied, re-run CI workflow dispatch (workflow_dispatch) if a deploy was previously skipped.
  2. View Ownership Verification: Whenever altering public.serdik or views touching it, verify public.portal_serdik_directory retains security_invoker = false, security_barrier = true, and identical relowner as public.serdik (HTTP 200 on GET /rest/v1/portal_serdik_directory?select=id,nosis&limit=1).
  3. Backup & Rollback: Before schema changes affecting state tables, capture a Supabase/Postgres logical dump (pg_dump). Migrations are written idempotently (IF NOT EXISTS, CREATE OR REPLACE) to permit safe re-application.
  4. Master Data PIN Generation: Run node scripts/generate-master-sql.mjs --rotate=pengasuh (or all/none) locally to produce supabase/private/01_master_data.sql (crypt(..., gen_salt('bf', 8))) and temporary distribution sheet supabase/private/pin-baru.csv without storing plaintext PINs in repository code.
  5. Local Container Smoke Test: Validate edge headers, MIME types (/manifest.webmanifest -> application/manifest+json; charset=utf-8), and /healthz locally with:
    Terminal window
    docker compose down
    docker compose up --build -d

Endpoint / Check Expected Output Diagnostic Command
Edge Liveness (nginx.conf) HTTP 200, body ok curl -fsS https://app.p3mdi.id/healthz
Container Loopback (docker-compose.yml) Healthy Docker status wget -qO- http://127.0.0.1/healthz
Directory View Health HTTP 200 (NOT 42501) curl -s -o /dev/null -w "%{http_code}\n" "$SUPABASE_URL/rest/v1/portal_serdik_directory?select=id,nosis&limit=1" -H "apikey: $ANON_KEY"
SSO Broker Readiness HTTP 200, JSON {"clientId":"..."} (503 if unconfigured) curl -fsS https://app.p3mdi.id/api/sso
GAS Drive Webhook Health HTTP 200, JSON {"status":"active"} curl -fsSL "$VITE_GDRIVE_WEBHOOK_URL"
  • Sync Banner HTTP 42501 (permission denied for table serdik): A manual edit or Supabase Security Advisor action flipped portal_serdik_directory to security_invoker = true or mismatched its owner. Re-apply supabase/migrations/20261121_restore_serdik_directory_view.sql (and 20261128_core_member_cache.sql if missing core_* columns) as the owner of public.serdik.
  • Users Locked Out After 5 Failed PINs (locked / retry_after_seconds: 900): Wait 15 minutes for sliding-window expiry or ask super_admin to invoke Unlock Login in AdminConsoleView (portal_admin_unlock_login).
  • Stuck Service Worker / Chunk Load Error After Release: nginx.conf & vercel.json mark /index.html and /sw.js no-cache, max-age=0, must-revalidate, while src/router/index.js performs one automatic window.location.assign(target) using sessionStorage['soedirman_chunk_reload']. Instruct affected mobile PWA users to clear site data or log out and tap Settings -> Clear Cache if stale UI persists.
  • Account Stays Disabled in Core After Sync (core_is_active = false): portal_login intentionally blocks archived Core accounts (20261129). Reactivate the member in P3MDI Core (core.p3mdi.id) or trigger /api/sso/core cache sync.