docs: adopt clean PSD replacement model
This commit is contained in:
@@ -36,8 +36,13 @@ manual-test document for each project.
|
||||
- The new source clone is prepared beside the old source directory. The old and new stacks are not
|
||||
kept running simultaneously: inventory and backup happen first, the old stack is stopped, and
|
||||
only then is the new stack started.
|
||||
- Preserve the old directory, configuration, and volumes as a recovery source until both projects
|
||||
pass. Do not migrate legacy application sessions, Qdrant data, Ollama caches, or derived indexes.
|
||||
- Keep the old directory, configuration, containers, images, and data only as a temporary recovery
|
||||
boundary until the real Aritmolab journey passes Project B. They are disposable after Project B
|
||||
automated, human, and owner PASS. Do not migrate legacy application sessions, Qdrant data,
|
||||
Ollama caches, or derived indexes.
|
||||
- Do not create a host `thothii` user or group. Keep UID/GID `10001:10001` as the image's unmapped
|
||||
numeric runtime identity and confine numeric ownership to the new installation's writable bind
|
||||
trees. Stop if either number becomes mapped to a host account before installation.
|
||||
- Recover configuration only: endpoints, non-secret policy, provider/model selection, relevant
|
||||
paths, and references to protected credentials. Never copy an old setting without validating it
|
||||
against the current contract.
|
||||
@@ -149,8 +154,10 @@ proved safe.
|
||||
pre-Project-B gate.
|
||||
4. Prepare the new source clone and protected operator/runtime directories beside the old source.
|
||||
5. Extract only approved configuration facts from the legacy installation.
|
||||
6. Create and verify backups and a restart recipe for the legacy stack.
|
||||
7. Stop the legacy stack without deleting its source, configuration, images, or volumes.
|
||||
6. Record and verify the exact restart recipe for the legacy stack. No data backup is required
|
||||
because the owner declared legacy sessions and configuration disposable; the still-present
|
||||
containers, images, source, and data are the temporary rollback boundary.
|
||||
7. Stop the legacy stack without deleting its source, configuration, images, or data.
|
||||
8. Build/install the current native `tht` and application images from the frozen source.
|
||||
9. Configure local authentication, direct DWH bindings, Pi/provider access, and the Git workspace.
|
||||
10. Start through `tht`, then validate health, authentication, workspace, workflow, and Pi.
|
||||
@@ -313,8 +320,8 @@ current gate is satisfied.
|
||||
|
||||
## Rollback boundaries
|
||||
|
||||
- **Project A:** stop the new stack and restart the preserved legacy installation. No new volume is
|
||||
copied into the legacy installation.
|
||||
- **Project A:** stop the new stack and restart the still-present legacy installation. No new
|
||||
volume is copied into it and no promise is made to retain it after Project B PASS.
|
||||
- **Project B ingress:** close the public route first, then restore the prior Nginx,
|
||||
load-balancer, certificate reference, and sidebar configuration.
|
||||
- **Project B application:** return to the accepted Project A local-auth operator configuration
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**Goal:** Install a clean PSD ThothII stack with local authentication, direct read-only DWH access, internal Qdrant/Ollama, rebuilt preprocessing, and one completed F1-F8 work session.
|
||||
|
||||
**Architecture:** Preserve the stopped legacy installation and deploy the current canonical five-service Compose stack from an adjacent clean clone. A reviewed server-local override disables public exposure and uses filesystem work sessions; an optional load-balancer route is permitted only when it is operator-only and its denial boundary is proved first.
|
||||
**Architecture:** Keep the stopped legacy installation intact only as a temporary rollback boundary and deploy the current canonical five-service Compose stack from an adjacent clean clone. Create no host service identity: the image's UID/GID 10001 remains numeric and unmapped, confined to the new writable bind roots. A reviewed server-local override disables public exposure and uses filesystem work sessions; an optional load-balancer route is permitted only when it is operator-only and its denial boundary is proved first.
|
||||
|
||||
**Tech Stack:** Git, Docker/Compose, native `tht`, local Argon2id authentication, PSD Supabase PostgreSQL direct transport, Qdrant, Ollama, Pi, Nginx/load-balancer test route where safe.
|
||||
|
||||
@@ -15,10 +15,15 @@
|
||||
- Common survey result is `SURVEY_GO_PROJECT_A_PRIVATE` and its digest is recorded.
|
||||
- Every path below is replaced by the exact survey result before execution.
|
||||
- No production Nginx/load-balancer/sidebar/Authentik change is in scope.
|
||||
- The old stack remains running only until backup verification finishes; old and new stacks never
|
||||
run together.
|
||||
- The old stack remains running until its exact inventory and restart recipe are verified; old and
|
||||
new stacks never run together.
|
||||
- The server's workspace deploy credential remains read-only. A curator with write access publishes
|
||||
the workspace change.
|
||||
- Owner amendment 2026-08-21 declares legacy sessions/configuration disposable. Retain old resources
|
||||
only until Project B proves the production Aritmolab journey, then delete them under a separate
|
||||
exact cleanup authorization. No legacy backup is required.
|
||||
- Do not create a host user or group for 10001. Immediately before preparing `/srv/thothii`, both
|
||||
`getent passwd 10001` and `getent group 10001` must return no match.
|
||||
- Owner amendment 2026-08-21 defers live Mac `rest_api` acceptance and `legacy-shared` revocation to
|
||||
the mandatory pre-Project-B gate. It does not authorize stop/start; those require a later explicit
|
||||
owner gate even after private preparation is complete.
|
||||
@@ -56,7 +61,8 @@ Expected: one SHA recorded as the pre-change workspace revision.
|
||||
**Step 3: Check old-stack recoverability**
|
||||
|
||||
Expected: exact old start/stop procedure, source SHA, Compose identity, volumes/binds, proxy closure
|
||||
procedure, and backup destination are present in the survey. Stop if any is missing.
|
||||
procedure, restart recipe, and shared-resource exclusions are present in the survey. Stop if any is
|
||||
missing.
|
||||
|
||||
### Task 2: Publish the multi-transport workspace revision
|
||||
|
||||
@@ -146,11 +152,12 @@ active user work. Do not use the new `tht` against an incompatible old descripto
|
||||
Change only the surveyed ThothII-specific route using its established mechanism. Validate Nginx and
|
||||
load-balancer configuration before applying. Confirm external requests no longer reach the app.
|
||||
|
||||
**Step 3: Create the legacy backup**
|
||||
**Step 3: Record the disposable legacy boundary**
|
||||
|
||||
Use the surveyed, version-compatible backup procedure. Include source/config metadata and all old
|
||||
runtime volumes/binds needed to restart; store credentials separately under existing protected
|
||||
custody. Create SHA-256 checksums and verify them.
|
||||
Record exact container and image IDs plus filesystem device/inode/ownership/size for
|
||||
`/home/chirone/ThothII` and `/home/chirone/thothii-data`. Do not archive their contents: the owner
|
||||
declared them disposable. Prove that the external Evidence bind and both shared Docker networks
|
||||
are excluded from any later cleanup manifest.
|
||||
|
||||
**Step 4: Stop the old stack**
|
||||
|
||||
@@ -168,10 +175,12 @@ be stated unambiguously, stop before creating the new stack.
|
||||
- Create: survey-selected new source root
|
||||
- Create: survey-selected operator, secret, data, Pi-state, registry, and backup roots
|
||||
|
||||
**Step 1: Create dedicated identities and paths**
|
||||
**Step 1: Create dedicated paths without creating identities**
|
||||
|
||||
Follow `docs/install/server.md` ownership rules using the surveyed available UID/GID. Do not reuse a
|
||||
UID already owned by another service and do not change image UID 10001 without a reviewed mapping.
|
||||
Follow `docs/install/server.md` numeric-ownership rules. Do not call `useradd`, `groupadd`, or
|
||||
`usermod`. The existing operator owns source/operator files; only the new data, Pi-state, and
|
||||
workspace-registry roots use unmapped numeric `10001:10001`. Stop if UID or GID 10001 resolves to a
|
||||
host account, and do not change the image identity without a reviewed design amendment.
|
||||
|
||||
**Step 2: Clone the frozen application source**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user