# 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. ## Owner-approved sequencing amendment — 2026-08-21 The Mac `rest_api` acceptance and revocation of `legacy-shared` move to a mandatory gate immediately before Project B. The survey therefore records two distinct decisions: - `SURVEY_GO_PROJECT_A_PRIVATE`: technical prerequisite for requesting Project A private execution; - `SURVEY_GO_PROJECT_B`: the complete shared-infrastructure decision, including Mac acceptance, observation and legacy revocation. The amendment authorizes the read-only survey and static preparation of non-secret Project A candidate facts and artifacts. While the current decision is `SURVEY_NO_GO`, it does not authorize creating installation roots, cloning/building the candidate, creating protected configuration or backup state, stopping the legacy stack, starting the new stack, changing public ingress, or starting Project B. Those remain separate explicit gates after the scoped survey passes. ### 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 scoped survey GO/NO-GO** Expected: `SURVEY_GO_PROJECT_A_PRIVATE` requires a verified old-stack recovery path, an approved new-installation root, enough resources, a direct read-only DWH path, workspace/model inputs, and no unresolved mutation in the private Project A scope. Public-origin, load-balancer and Authentik unknowns may remain explicitly deferred only while Project A is loopback-only and Task 10 is omitted. `SURVEY_GO_PROJECT_B` retains the complete survey requirements. **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 for Project A private scope** Expected: the survey report hash matches the journal and no unresolved blocker remains inside the Project A private scope. Before any stop/start, obtain a separate explicit owner authorization. **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. The Mac REST row may be `DEFERRED_PRE_PROJECT_B` only under the dated owner amendment. **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. The accepted report must list the Mac REST item as an explicit deferred prerequisite rather than silently treating it as PASS. **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** Before freezing the candidate, close the pre-Project-B gate: validate the Mac installation with its per-installation key, finish the 48-hour observation window including two 03:00 ETL cycles, revoke `legacy-shared`, prove legacy `401` and v1 success, and obtain `SURVEY_GO_PROJECT_B`. 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.