221 lines
8.2 KiB
Markdown
221 lines
8.2 KiB
Markdown
# 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.
|