ThothII/docs/plans/2026-08-20-psd-server-deployment-program.md

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:

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:

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:

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

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.