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.

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 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:

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.