docs: plan PSD server deployment program
This commit is contained in:
@@ -0,0 +1,220 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user