# PSD Server Deployment Program Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. **Goal:** Replace the legacy PSD ThothII installation, prove the replacement with local authentication, and then integrate the accepted release with Supabase, Authentik, Nginx, the load balancer, and the Aritmolab sidebar. **Architecture:** A read-only common survey freezes the actual server topology before any mutation. Project A installs a clean private stack and proves a complete PSD workflow; Project B begins only after a signed Project A PASS and performs the public OIDC/SSO cutover. Each project has an independent rollback boundary, human test guide, and evidence report. **Tech Stack:** Linux, Docker Engine, Docker Compose v2, native `tht`, Fastify/React/Pi, PostgreSQL/Supabase, Qdrant, Ollama, Nginx, Authentik OIDC, Aritmolab, load balancer. --- ## Required reading and authority Read these files completely before starting: - `AGENTS.md` - `PROJECT_STATE.md` - `docs/plans/2026-08-20-psd-server-deployment-program-design.md` - `docs/install/server.md` - `docs/install/server-workspace-registry.md` - `docs/install/authentication-local.md` - `docs/install/authentication-oidc.md` - `docs/install/authentik.md` - `docs/contracts/workspace-preprocessing-cli.md` - `docs/testing/authentication-manual-acceptance.md` The current `compose.yaml`, `deploy/compose.server.yaml`, repository instructions, and design are authoritative where older server prose still describes Qdrant or Ollama as external. Run only from a terminal local to the server. Do not require SSH port forwarding. Do not print or paste passwords, tokens, cookies, private keys, hashes, or raw identity claims. Commands that need a credential must read a protected file or use an echo-free prompt. ## Documents used during execution - Survey plan: `docs/plans/2026-08-20-psd-server-survey.md` - Survey report: `docs/testing/evidence/psd-server-survey-report-template.md` - Project A plan: `docs/plans/2026-08-20-psd-server-project-a-standalone.md` - Project A human guide: `docs/testing/psd-server-project-a-manual.md` - Project A report: `docs/testing/evidence/psd-server-project-a-report-template.md` - Project B plan: `docs/plans/2026-08-20-psd-server-project-b-authentik.md` - Project B human guide: `docs/testing/psd-server-project-b-manual.md` - Project B report: `docs/testing/evidence/psd-server-project-b-report-template.md` The detailed evidence directory is a protected path on the server selected during the survey. The repository receives only redacted reports after explicit owner review. ### Task 1: Freeze the planning source **Files:** - Read: `docs/plans/2026-08-20-psd-server-deployment-program-design.md` - Record: protected server execution journal selected during the survey **Step 1: Verify the application checkout** Run: ```bash git status --short --branch git rev-parse HEAD git rev-parse origin/main git show -s --format='%H%n%P%n%s' HEAD ``` Expected: the tree is clean and `HEAD` is the explicitly approved `origin/main` SHA. A newer SHA than the design-time `5c0dc8c` is allowed only after recording and reviewing the intervening commits. **Step 2: Verify the plan files exist at that SHA** Run: ```bash test -f docs/plans/2026-08-20-psd-server-survey.md test -f docs/plans/2026-08-20-psd-server-project-a-standalone.md test -f docs/plans/2026-08-20-psd-server-project-b-authentik.md git diff --check ``` Expected: every command exits zero. **Step 3: Record the immutable planning identity** Record the application SHA, plan commit, UTC timestamp, operator identity, and terminal-local access method in the protected journal. Do not record CyberArk session secrets or screenshots. ### Task 2: Execute and approve the common survey **Files:** - Execute: `docs/plans/2026-08-20-psd-server-survey.md` - Create from: `docs/testing/evidence/psd-server-survey-report-template.md` **Step 1: Execute every survey task without mutation** Expected: the survey identifies exact paths and owners for the old and new installations, Nginx, load balancer, Aritmolab, Authentik, Supabase, the DWH, and protected credentials. **Step 2: Resolve every unknown** If an Authentik credential cannot be located, stop and ask the owner. If a configuration owner or rollback boundary is unclear, stop; do not infer authority from file readability. **Step 3: Review the survey GO/NO-GO** Expected: GO requires a verified old-stack recovery path, a new-installation root, enough resources, a read-only DWH path, and no unresolved shared-infrastructure mutation. **Step 4: Checkpoint the survey** Hash the protected report and record only its path, SHA-256, timestamp, and GO result in the journal. ### Task 3: Execute Project A **Files:** - Execute: `docs/plans/2026-08-20-psd-server-project-a-standalone.md` - Complete: `docs/testing/evidence/psd-server-project-a-report-template.md` **Step 1: Confirm the survey is GO** Expected: the survey report hash matches the journal and no unresolved blocker remains. **Step 2: Execute Project A task-by-task** Do not configure Authentik, change the production Aritmolab sidebar, or open the production route. **Step 3: Run the Project A human guide** Follow `docs/testing/psd-server-project-a-manual.md`. Record PASS/FAIL for every case; do not infer manual PASS from automated output. **Step 4: Close the Project A report** Expected: automated gates and the human guide are PASS; one harmless PSD session reached F8 and produced validated read-only SQL; rollback remains available. **Step 5: Obtain explicit owner approval** Record the approval and report digest. Project B remains forbidden without it. ### Task 4: Freeze the Project B candidate **Files:** - Read: accepted Project A report - Record: protected server execution journal **Step 1: Recheck source and running images** Run the Project A plan's identity commands again. Record application SHA, workspace SHA, core image ID, frontend image ID, Qdrant image digest, Ollama image digest, and local-auth configuration revision. Expected: all values match the accepted Project A report. **Step 2: Recheck rollback** Prove that the public route is still closed and the protected Project A configuration can be selected without reconstructing it from memory. ### Task 5: Execute Project B **Files:** - Execute: `docs/plans/2026-08-20-psd-server-project-b-authentik.md` - Complete: `docs/testing/evidence/psd-server-project-b-report-template.md` **Step 1: Execute Project B task-by-task** Keep public traffic closed until Authentik, Supabase migrations, ThothII diagnostics, Nginx, TLS, and load-balancer preflight all pass. **Step 2: Run the Project B human guide** Follow `docs/testing/psd-server-project-b-manual.md` using approved ordinary and administrator identities. The final path begins at the Aritmolab homepage and uses its existing sidebar link. **Step 3: Close the Project B report** Expected: SSO, roles, PostgreSQL ownership, the F1-F8 session, rollback rehearsal, and cleanup of the temporary Project A endpoint all pass. ### Task 6: Close the program **Files:** - Modify: `PROJECT_STATE.md` - Optionally create: reviewed redacted acceptance reports under `docs/testing/evidence/` **Step 1: Reconcile final state** Record final SHAs, image identities, workspace revision, Authentik object names/IDs (never secrets), Supabase database/schema names, public origin, sidebar source revision, Nginx configuration identity, and both report digests. **Step 2: Verify final negative boundaries** Expected: old stack stopped; Project A private endpoint removed; core/Qdrant/Ollama not externally published; `thoth_sessions` absent from PostgREST exposed schemas; no secret appears in reports. **Step 3: Update project state** Add a dated factual section to `PROJECT_STATE.md`. Mark anything not actually run as PENDING. **Step 4: Run documentation checks** Run: ```bash git diff --check bash scripts/auth-docs-smoke.sh bash scripts/verify-workspace-install-docs.sh --fixtures-only ``` Expected: all checks pass. **Step 5: Commit only reviewed redacted documentation** ```bash git add PROJECT_STATE.md docs/testing/evidence git diff --cached --check git commit -m "docs: record PSD server deployment acceptance" ``` Expected: the commit contains no raw server inventory or secret material.