diff --git a/00-overview/postgres-migration-roadmap.md b/00-overview/postgres-migration-roadmap.md index 67c3070..0d10bad 100644 --- a/00-overview/postgres-migration-roadmap.md +++ b/00-overview/postgres-migration-roadmap.md @@ -1,7 +1,7 @@ --- owner: gmikcon status: draft -last_reviewed: 2026-11-19 +last_reviewed: 2026-11-20 review_interval: 30d confidence: medium source_of_truth: analysis-2026-11-19 @@ -505,8 +505,11 @@ | 2026-11-19 | Phase 8: health/monitoring | Healthcheck script, public `/health` contract, Synapse alert plumbing; hard-panel registration and Synapse source remain owner actions | | 2026-11-19 | Phase 8: deploy/docs | `deploy.sh` applies migrations and refreshes units; operations and decommission runbooks; service page updated | | 2026-11-19 | Phase 8: decommission | Blocked on production cutover and owner sign-off; file backend retained for rollback | -| 2026-11-20 | Data ownership | `documents.owner_user_id` and `inventory_items.owner_user_id`; `assign-owner`/`ownership` CLI; current 33 documents and 84 inventory items assigned to the first user (`sub=1`, superadmin); historical import authorship preserved | -| 2026-11-20 | Rollout state | Local database/auth rollout verified; production deployment target not available on the development machine and remains pending | +| 2026-11-20 | Data ownership | `documents.owner_user_id` and `inventory_items.owner_user_id`; `assign-owner`/`ownership` CLI; current 76 documents and 120 inventory items assigned to the bootstrap administrator; production owner transfer pending the real gnexus-auth `sub`; historical import authorship preserved | +| 2026-11-20 | Production cutover | gnbook runs `GNEXUS_BOOK_STORAGE_BACKEND=db`: 76 documents, 120 inventory items, 78 document versions; `/health` reports `storage: db`, `checks.db: ok` | +| 2026-11-20 | History published | `master` consolidated and pushed; `origin/master` matches gnbook HEAD `68a010a`; `deployed-2026-11-20` tag retains the deployment commit | +| 2026-11-20 | Operations hardening | Healthcheck timer every five minutes, backup-disk warning/critical checks, forced backup and restore drill (76/120, validation ok), legacy pending-change archive, file write freeze | +| 2026-11-20 | Production blockers | Production gnexus-auth/real owner `sub`, public DNS/HTTPS for `book.gnexus.space`, and Synapse alert credentials remain owner actions | Notes: @@ -516,7 +519,7 @@ `POST /commit` is blocked. - Search keeps the current substring semantics for exact response parity. A full-text index is a later optimization, not a correctness requirement. -- The date-dependent freshness test still fails because 25 documents are past their +- The date-dependent freshness test still fails because many documents are past their review interval. This is the recorded baseline, not a regression. - Phase 4 is scaffolded without production credentials. Real login needs an OAuth client registered by the owner in gnexus-auth (`client_id`, `client_secret`, @@ -525,33 +528,39 @@ not blocked may write". MCP keys carry `read`/`write` scopes. - The Vue UI now covers the current functionality, the auth gate, i18n and the MCP keys page. Real gnexus-auth credentials are still required to exercise live login. -- Phase 7 tooling and the cutover rehearsal are complete. The actual production flip - is a deployment action: set `GNEXUS_BOOK_STORAGE_BACKEND=db` and the database URL in - `server/.env`, restart the backend and MCP units, then run the post-cutover checks in - [cutover-postgres.md](../30-runbooks/cutover-postgres.md). The Git checkout is - untouched and remains the rollback source. +- Phase 7 tooling, the rehearsal and the production cutover are complete. PostgreSQL + is canonical on gnbook; the code default remains `file` for tests and local + development. Set `GNEXUS_BOOK_STORAGE_BACKEND=db` and the database URL in + `server/.env` for a database deployment, then run the post-cutover checks in + [cutover-postgres.md](../30-runbooks/cutover-postgres.md). +- Parity is a cutover check, not a permanent invariant. After database writes begin, + the file backend is older by design; a later parity run may report expected + differences and must not be "fixed" by copying files over the database. - The retained cutover evidence is the migration report under - `~/backup/gnexus-book/` and the off-host dump on NetTera8. + `~/backup/gnexus-book/`, the 2026-11-20 off-host dumps, the restore-drill output and + the legacy pending-change archive on NetTera8. - The local gnexus-auth instance is connected and verified end to end through the - owner-provided `gnexus-book-local` client, including a dedicated test user, the - `editor` role and a real signed webhook delivery. Credentials live only in - `server/.env` and `~/.config/gnexus-book/`, never in the repository. -- The local client uses the permissive `all_active_users` access mode for testing. - Production must use an owner-registered client with HTTPS URLs, a narrower access - mode and defined client permissions; role-specific publish policy is still open. + owner-provided client and a signed webhook delivery. Production authentication still + needs an owner-registered client with HTTPS URLs, a narrower access mode and defined + client permissions; role-specific publish policy is still open. +- Production MCP allowlists include `book.gnexus.space`, its HTTPS origin and the LAN + address with a port wildcard. LAN `initialize`/`tools/list` with a personal key + returns 200; public HTTPS is blocked until DNS and the front end exist. - A full review on 2026-11-19 found 12 issues; all are fixed and covered by regression - tests. Production deployment must set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` to include the - public MCP hostname and `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` to include its HTTPS origin, - because FastMCP rejects unknown Host headers with `421`. -- Phase 8 operations are implemented locally: scheduled backups, restore drill, - healthcheck and Synapse alert plumbing, deploy migrations and runbooks. The actual - hard-panel probe and Synapse source/alert route still require owner credentials. -- Phase 8 decommission is not executed. The file backend, Git adapter and original - repository remain until the production cutover has run for the agreed stability - window and the owner signs off + tests. FastMCP rejects unknown Host headers with `421`, so any new public hostname + must be added to both allowlists before it is used. +- Phase 8 operations are implemented on gnbook: daily backup timer, monthly restore + drill timer, five-minute healthcheck timer and disk-space checks. The hard-panel + probe and Synapse source/alert route still require owner credentials. +- Phase 8 decommission is partially executed. File writes are frozen with + `GNEXUS_BOOK_FILE_BACKEND_FROZEN=true`, legacy pending JSON was archived and removed, + and the file backend remains a read-only rollback source. Code removal is still + pending the stability window and owner sign-off [decommission-file-backend.md](../30-runbooks/decommission-file-backend.md). -- Current data ownership is assigned locally to the first user (`sub=1`, superadmin): - 33 documents and 84 inventory items, 0 unowned. Production assignment should use - `GNEXUS_BOOK_OWNER_JSON` during cutover or the `assign-owner` CLI afterwards. -- Production rollout is pending a deployment target: the development machine has no - `/home/ubuntu/gnexus-book`, `/var/www/gnexus-book`, or running Gnexus Book services. +- Current data ownership is 76 documents and 120 inventory items assigned to the + bootstrap administrator, 0 unowned in the database. Transfer to the real owner must + wait for the production `sub` and a fresh dump; keep `owner.json` outside the + repository. +- Production rollout is complete on gnbook (192.168.1.170). Remaining blockers are + production authentication/owner identity, public DNS/HTTPS for `book.gnexus.space`, + and Synapse alert credentials. diff --git a/10-systems/applications/gnexus-book.md b/10-systems/applications/gnexus-book.md index 8458887..9439648 100644 --- a/10-systems/applications/gnexus-book.md +++ b/10-systems/applications/gnexus-book.md @@ -14,9 +14,12 @@ ## Access -- UI and REST: gnexus-auth SSO when authentication is configured; otherwise the - local-development installation runs open. +- UI and REST: gnexus-auth SSO. The gnbook deployment is currently wired to the + local gnexus-auth test instance; production authentication and owner transfer are + still pending. - Agents: personal `mcp_*` keys over streamable HTTP at `/mcp-protocol/`. +- MCP transport: streamable HTTP only. The legacy SSE endpoint is not served; + `GNEXUS_BOOK_MCP_TOKEN` is a break-glass token, not the normal agent credential. - Service-to-service key provisioning: `/internal/keys`, protected by a service secret, blocked in nginx. - Secrets are references only; no raw credentials are documented here. @@ -27,86 +30,102 @@ `hp-proliant-dl380-g6` (192.168.1.130). - SSH: `ubuntu` on 192.168.1.170; credentials live in gnexus-creds as `gnauth-gnbook-ssh`. -- Repository path: `/home/ubuntu/gnexus-book` (branch `master`). -- Current pre-cutover runtime: backend `http://192.168.1.170:8000/`, MCP SSE on - `:8001/sse`, UI `http://192.168.1.170/` via nginx, file-backed storage. -- Target runtime after the PostgreSQL cutover: MCP streamable HTTP at - `/mcp-protocol/`, PostgreSQL as the canonical store, SSO enforced when configured. -- Git remains the code repository and rollback source until the file backend is - decommissioned. +- Repository path: `/home/ubuntu/gnexus-book` (branch `master`, tracking + `origin/master`). +- Current runtime (since 2026-11-20): backend `http://192.168.1.170:8000/`, + MCP streamable HTTP at `/mcp-protocol/`, UI `http://192.168.1.170/` via nginx, + PostgreSQL canonical store, healthcheck and backup timers. +- PostgreSQL cutover completed on 2026-11-20. File backend writes are frozen with + `GNEXUS_BOOK_FILE_BACKEND_FROZEN=true`; the checkout remains a read-only rollback + source. +- History was consolidated and published on 2026-11-20; the `deployed-2026-11-20` tag + archives the deployment commit. ## Storage and ownership -- PostgreSQL database `gnexus_book` is the target canonical store, with immutable +- PostgreSQL database `gnexus_book` is the canonical store, with immutable document and inventory versions grouped into changesets. -- Documents and inventory items carry `owner_user_id`. Current data is assigned to the - first admin user (`sub=1`, superadmin); historical import authorship remains - `system`/`importer`. -- The file backend (Markdown/YAML + Git) remains readable for rollback until the - production cutover is accepted and the decommission runbook is executed. +- Documents and inventory items carry `owner_user_id`. Current rows are assigned to + the bootstrap administrator; transfer to the real owner is pending production + authentication. Historical import authorship remains `system`/`importer`. +- The file backend (Markdown/YAML + Git) is frozen for writes and remains readable + only for rollback and tests until the decommission runbook is executed. ## Runtime components - Backend: FastAPI under `server/`. - MCP: `server/app/mcp_http.py`, streamable HTTP at `/mcp-protocol/`. -- UI: Vue/Vite under `ui/`, using `gnexus-ui-kit`. -- Auth: gnexus-auth SSO plus per-user service keys. +- UI: Vue/Vite under `ui/`, using `gnexus-ui-kit`; nginx serves the built bundle. +- Auth: gnexus-auth SSO, personal MCP keys and service-to-service provisioning. ## Endpoints - REST API on gnbook: `http://192.168.1.170:8000/` (uvicorn). - UI on gnbook: `http://192.168.1.170/` (nginx serves the built SPA and proxies `/api/`, `/auth/`, `/webhooks/gnexus-auth`, `/mcp-protocol/`). -- MCP on gnbook: `http://192.168.1.170:8001/mcp-protocol/`. +- MCP on gnbook: `http://192.168.1.170:8001/mcp-protocol/` (personal key required; + no SSE endpoint). - Local development: backend `127.0.0.1:3005`, UI `127.0.0.1:3006`, MCP `127.0.0.1:8001/mcp-protocol/`. -- systemd user units under `user@1000.service`: backend, frontend, MCP, daily backup, - optional monthly restore drill. +- systemd user units under `user@1000.service`: backend, frontend, MCP, healthcheck, + daily backup and monthly restore drill. The frontend unit on `:3006` is a legacy + Vite preview; the public UI is the static bundle served by nginx on port 80. ## Backups and recovery Legacy file-level backup (set up 2026-10-09): - Script `/home/ubuntu/gnexus-book-backup.sh` on gnbook; full repo `tar.gz` including - `.git`, modified inventory, and untracked pending-change JSON files, plus a + `.git`, modified inventory, and legacy pending-change JSON files, plus a `git bundle --all`. - Daily 03:10 UTC via ubuntu crontab; 10-day retention; tar and bundle sanity checks. -- Typical size: tar ~34.5 MB, bundle ~615 KB. The VM has about 2 GB free; retention - is mandatory. -- `master` is ahead of `origin/master` by 309 commits, so local backups are currently - the only copy of recent history. -- Restore: extract the tar for the full repository including pending changes; a bundle - clone restores history only. +- `master` now tracks `origin/master`; the Git backup is no longer the only copy of + recent history. Keep the legacy backup until the file backend is decommissioned. +- Restore: extract the tar for the full repository including legacy pending changes; a + bundle clone restores history only. PostgreSQL backup and recovery: - Daily off-host `pg_dump` through `gnexus-book-backup.timer`; retention is configured by `GNEXUS_BOOK_BACKUP_KEEP`. +- The latest verified dump on 2026-11-20 is + `gnexus_book_2026-11-20_151745.dump` under + `/mnt/NetTera8/service/backups/gnexus-book/db/target-gnbook/`. - Restore procedure and periodic drill: [../../30-runbooks/postgres-operations.md](../../30-runbooks/postgres-operations.md). -- Backup failures and failed health probes alert through Gnexus Synapse when a `syn_*` - source key is configured. +- Backup failures and failed health probes can alert through Gnexus Synapse, but + `SYNAPSE_URL`/`SYNAPSE_API_KEY` are not configured on this host yet. - Keep the legacy file backup until the decommission is complete. -## Legacy file pending-changes protection +## Legacy file pending-changes archive -The file backend has poisoned-pending protection (commit `c77bcb1`, 2026-09-24): +After the cutover, the file pending-change records were treated as legacy: -- create rejects secrets and unsafe doc targets before writing any pending file; -- failed apply rolls back the target and removes the change's own pending JSON; -- `delete_pending_change` / `DELETE /changes/{id}` deletes pending or corrupt records; -- corrupt pending JSON is listed with status `corrupt`, can be deleted, cannot be - applied; -- `update_doc` cleans up its pending JSON if apply or commit fails. - -In database mode the equivalent unit is a draft changeset; deletion is allowed only -while it is still a draft. +- 418 records (189 tracked, 229 untracked; 37 still unapplied) were archived off-host at + `/mnt/NetTera8/service/backups/gnexus-book/legacy-pending-changes/2026-11-20/` with + a SHA-256 checksum and a metadata manifest; +- the tracked and untracked JSON files were then removed from the working tree, so + database changesets are the only active proposal path; +- the archive preserves unapplied drafts for review; nothing was applied implicitly. ## Monitoring - `GET /health` follows the platform contract (`status`, `checks.db`, service, version, timestamp); it is public and contains no personal data. -- hard-panel probes the same endpoint; alerts are routed through Synapse. -- Local check: `scripts/healthcheck.sh`. +- `gnexus-book-healthcheck.timer` runs `scripts/healthcheck.sh` every five minutes. + It checks `/health`, the database check and the backup filesystem. +- The backup filesystem check warns at 90% and fails at 98%; NetTera8 is currently + about 97% used, so the check reports a warning. +- hard-panel registration and Synapse alert routing are still pending owner + credentials; local failure paths are logged but do not deliver notifications. + +## Current blockers (2026-11-20) + +- Production authentication and the real owner `sub` are not configured; data is still + owned by the bootstrap administrator. +- `book.gnexus.space` does not resolve and public HTTPS is not configured. The MCP + allowlist already contains the public host and origin. +- Synapse alert credentials are absent, so backup/health alerts are not delivered. +- Ownership counts must be rechecked after the real owner is established. ## Maintenance model diff --git a/30-runbooks/cutover-postgres.md b/30-runbooks/cutover-postgres.md index 4f86b8f..aa13077 100644 --- a/30-runbooks/cutover-postgres.md +++ b/30-runbooks/cutover-postgres.md @@ -1,7 +1,7 @@ --- owner: gmikcon status: draft -last_reviewed: 2026-11-19 +last_reviewed: 2026-11-20 review_interval: 90d confidence: high source_of_truth: migration-runbook @@ -9,9 +9,10 @@ # PostgreSQL cutover runbook -Move Gnexus Book from the file backend to PostgreSQL. The Git checkout is never -modified by this procedure; it remains the rollback source until the cutover is -accepted. +Move Gnexus Book from the file backend to PostgreSQL. The production cutover was +completed on 2026-11-20; this runbook remains the procedure for a rehearsal or a +future rebuild. The Git checkout is never modified by the cutover and remains a +read-only rollback source after the file write path is frozen. ## Preconditions @@ -40,8 +41,9 @@ ## Cutover 1. Announce the maintenance window and the rollback plan. -2. Freeze writes to the file backend (stop the backend service or put it in - maintenance mode). +2. Freeze writes to the file backend: stop the backend service or set + `GNEXUS_BOOK_FILE_BACKEND_FROZEN=true` before switching the backend. File writes + then fail with a clear error instead of silently diverging from PostgreSQL. 3. Run the cutover against the target database: ```bash @@ -68,12 +70,13 @@ ```text GNEXUS_BOOK_STORAGE_BACKEND=db + GNEXUS_BOOK_FILE_BACKEND_FROZEN=true GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://... ``` 6. Restart `gnexus-book-backend` and `gnexus-book-mcp`. 7. Run the post-cutover checks below. -8. Unfreeze writes and announce completion. +8. Leave the file write path frozen and announce completion. ## Post-cutover checks @@ -88,19 +91,33 @@ `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` includes its HTTPS origin. - A fresh off-host dump exists and its checksum verifies. +Parity is a cutover check, not a permanent invariant. Once PostgreSQL is canonical, +writes through MCP/API make the file backend older by design; a later parity run may +report differences and that is expected. Do not "fix" parity by copying files over the +database. + ## Rollback -The file backend remains intact. To roll back: +The file backend is frozen but intact. To roll back: -1. Set `GNEXUS_BOOK_STORAGE_BACKEND=file`. -2. Restart `gnexus-book-backend` and `gnexus-book-mcp`. -3. Run `scripts/rollback-cutover.sh` to verify file validation and document reads. -4. If the database must be restored separately, use `scripts/restore-db.sh` with the +1. Take a fresh PostgreSQL dump and record it as the current database point. +2. Stop `gnexus-book-backend` and `gnexus-book-mcp`. +3. Set `GNEXUS_BOOK_STORAGE_BACKEND=file` and, as an explicit break-glass action, + `GNEXUS_BOOK_FILE_BACKEND_FROZEN=false`. +4. Restore the pre-cutover file tree from the Git archive/tar if it has changed since + the cutover. +5. Restart the services and run `scripts/rollback-cutover.sh` to verify file validation + and document reads. +6. If the database must be restored separately, use `scripts/restore-db.sh` with the pre-cutover dump and `GNEXUS_BOOK_RESTORE_YES=1`. +7. Record the rollback and re-freeze file writes once the database is selected again. ## After acceptance - Keep the pre-cutover dump and the Git archive for the agreed retention period. -- Remove the file write path only after the database backend has run without incident. +- Keep file writes frozen; remove the write path only after the database backend has + run without incident and the owner signs off the decommission runbook. +- Archive legacy pending-change JSON before deleting it; the 2026-11-20 archive is the + precedent. - Record the cutover in gnexus-book and update the service page with backup and restore instructions. diff --git a/30-runbooks/decommission-file-backend.md b/30-runbooks/decommission-file-backend.md index eadefe2..80fbc6f 100644 --- a/30-runbooks/decommission-file-backend.md +++ b/30-runbooks/decommission-file-backend.md @@ -1,7 +1,7 @@ --- owner: gmikcon status: draft -last_reviewed: 2026-11-19 +last_reviewed: 2026-11-20 review_interval: 90d confidence: high source_of_truth: migration-runbook @@ -10,8 +10,9 @@ # Decommission the file backend Remove the file write path and Git adapter after the production cutover is accepted. -**Not executed yet.** The file backend remains available for rollback and for tests -until the prerequisites below are met. +The file write path is already **frozen** on gnbook +(`GNEXUS_BOOK_FILE_BACKEND_FROZEN=true`) and the legacy pending-change JSON was +archived; the remaining code removal is still pending owner sign-off. ## Prerequisites @@ -19,7 +20,9 @@ window with no unresolved data incidents. - The pre-cutover dump and a fresh post-cutover dump have both passed restore drills. - `validate_repository` and `validate_database` are clean. -- The parity suite reports zero differences. +- The cutover parity report has been recorded; parity is no longer a permanent + invariant after database writes begin. +- Legacy pending-change JSON has been archived off-host with a manifest. - The owner has signed off the decommission in writing. ## Steps @@ -28,18 +31,22 @@ - create a `git bundle` of all refs and a worktree archive; - copy both off-host and verify SHA-256 and a restore. 2. Keep the last pre-decommission PostgreSQL dump off-host with the agreed retention. -3. Update defaults so tests and development no longer depend on the file backend. -4. Remove the file write path: +3. Keep `GNEXUS_BOOK_FILE_BACKEND_FROZEN=true` so file writes fail even if the backend + selection is changed by mistake. +4. Archive any remaining file-specific pending changes under + `90-maintenance/pending-changes/`; the 2026-11-20 archive is the precedent. +5. Update defaults so tests and development no longer depend on the file backend. +6. Remove the file write path: - `DocsRepository`, `InventoryRepository` write paths where no longer needed; - `GitAdapter` commit path and `/commit` routing; - file-specific pending changes (`90-maintenance/pending-changes/*.json`). -5. Retarget the test suite to the database backend and remove file-parity fixtures +7. Retarget the test suite to the database backend and remove file-parity fixtures that no longer have a reference implementation. -6. Remove unused configuration (`GNEXUS_BOOK_STORAGE_BACKEND=file` branches) and +8. Remove unused configuration (`GNEXUS_BOOK_STORAGE_BACKEND=file` branches) and dependencies. -7. Update the service page, README, CLAUDE.md and this runbook. -8. Run the full test suite, validation, parity checks that still make sense, and a - restore drill. +9. Update the service page, README, CLAUDE.md and this runbook. +10. Run the full test suite, validation, parity checks that still make sense, and a + restore drill. ## Rollback @@ -47,11 +54,15 @@ - restore the service from the last dump if the database is damaged; - restore the file backend from the Git archive if the database path must be - abandoned entirely. + abandoned entirely; +- to use the file backend during rollback, explicitly set + `GNEXUS_BOOK_FILE_BACKEND_FROZEN=false` and record the break-glass action. After both artifacts are retired, rollback is no longer possible. ## Status -Blocked on the production cutover and owner sign-off. No file-backend code has been -removed. +Partially executed on 2026-11-20: file writes are frozen, legacy pending changes were +archived and removed, and the database is canonical. The file-backend code has not +been removed; full decommission remains blocked on the production stability window and +owner sign-off. diff --git a/30-runbooks/postgres-operations.md b/30-runbooks/postgres-operations.md index 848fa52..3be11e1 100644 --- a/30-runbooks/postgres-operations.md +++ b/30-runbooks/postgres-operations.md @@ -1,7 +1,7 @@ --- owner: gmikcon status: active -last_reviewed: 2026-11-19 +last_reviewed: 2026-11-20 review_interval: 90d confidence: high source_of_truth: repository @@ -22,7 +22,7 @@ - keeps `GNEXUS_BOOK_BACKUP_KEEP` dumps (default 14); - refuses to run if the off-host mount is unavailable and no explicit directory is configured; - - on failure, sends a Synapse alert when `SYNAPSE_URL` and `SYNAPSE_API_KEY` are + - on failure, sends a Synapse alert when `SYNAPSE_URL` and `SYNAPSE_API_KEY` are configured. - Manual run: @@ -33,6 +33,11 @@ A backup that has never been restored does not count. Run the restore drill below. +The backup timer was forced on 2026-11-20 and produced +`/mnt/NetTera8/service/backups/gnexus-book/db/target-gnbook/gnexus_book_2026-11-20_151745.dump` +with a valid `pg_restore --list` and SHA-256 file. The daily timer next runs at +00:00 UTC. + ## Restore drill ```bash @@ -45,19 +50,15 @@ and count checks, prints the result and drops the temporary database. It requires a database role with `CREATEDB`. -`gnexus-book-restore-drill.timer` is installed but not enabled by default. Enable it -after the first successful manual drill: - -```bash -systemctl --user enable --now gnexus-book-restore-drill.timer -``` - -The monthly timer uses the same script and alerts through Synapse on failure. +`gnexus-book-restore-drill.timer` is enabled and runs monthly. A manual drill against +the 2026-11-20 dump passed: 76 documents, 120 inventory items, validation `ok`. The +monthly timer uses the same script and alerts through Synapse on failure. ## Health and monitoring - `GET /health` is public, cheap and returns `status`, `service`, `version`, `storage`, `timestamp` and `checks.db`. It exposes no users, secrets or topology. +- `gnexus-book-healthcheck.timer` runs the local probe every five minutes. - Monitor URL for hard-panel: `GNEXUS_BOOK_HEALTH_URL` (default `http://127.0.0.1:8000/health`). - Local probe: @@ -67,24 +68,31 @@ ``` It fails on a non-`ok` status or a failed `checks.db`, and sends a Synapse alert when - configured. + configured. It also checks `GNEXUS_BOOK_DISK_PATH`: + - warning at `GNEXUS_BOOK_DISK_WARN_PERCENT` (default 90%); + - failure at `GNEXUS_BOOK_DISK_MAX_PERCENT` (default 98%); + - NetTera8 is currently about 97% used, so the probe logs a warning. - Register the probe in hard-panel and create the alert route in Synapse. The book service does not own notification channels; Synapse routing decides recipients. +- `SYNAPSE_URL`/`SYNAPSE_API_KEY` are not configured on gnbook yet, so failure paths + currently log without delivering an alert. ## Data ownership -Imported documents and inventory can be assigned to the first admin user: +Current rows are assigned to the bootstrap administrator. After the real owner signs in +through production gnexus-auth, record the real `sub` and transfer ownership: ```bash set -a; . server/.env; set +a cd server -.venv/bin/python -m app.storage.cli assign-owner --user-json /path/to/owner.json +.venv/bin/python -m app.storage.cli assign-owner --user-json "$HOME/.config/gnexus-book/owner.json" .venv/bin/python -m app.storage.cli ownership ``` -The owner JSON contains `sub`, `email`, `system_role`, `status` and `profile` -(display name, locale, timezone, avatar URL). The command creates or updates the local -user mirror, assigns only rows with no owner by default, and writes an +Keep `owner.json` outside the repository (`~/.config/gnexus-book/owner.json`, +`chmod 600`). The owner JSON contains `sub`, `email`, `system_role`, `status` and +`profile` (display name, locale, timezone, avatar URL). The command creates or updates +the local user mirror, assigns only rows with no owner by default, and writes an `ownership.assigned` audit record. `--all` transfers every document and inventory item to the new owner. @@ -98,6 +106,11 @@ `GNEXUS_BOOK_STORAGE_BACKEND=db`, it runs `alembic upgrade head` before restarting the backend and MCP services. It also refreshes the systemd user units. +The main checkout can `git pull` from origin over HTTPS. The sibling +`~/gnexus-ui-kit` checkout is private; when it is bundle-managed and has no GitBucket +credentials, run `GNEXUS_BOOK_SKIP_KIT_PULL=1 ./scripts/deploy.sh` and keep the local +kit build current through the bundle path. + ## Secrets - Runtime values live in `server/.env` (`chmod 600`, gitignored) and in gnexus-creds. @@ -110,6 +123,7 @@ systemctl --user status gnexus-book-backend.service gnexus-book-mcp.service systemctl --user list-timers 'gnexus-book-*' ./scripts/healthcheck.sh -psql -h 127.0.0.1 -p 5433 -U gmikcon -d gnexus_book -c \ +set -a; . server/.env; set +a +psql "${GNEXUS_BOOK_DATABASE_URL/postgresql+psycopg/postgresql}" -c \ "select count(*) from documents;" ``` diff --git a/CLAUDE.md b/CLAUDE.md index f313263..e900682 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ ## What this repository is -Gnexus Book is a Git-backed personal infrastructure knowledge base plus the tooling that operates on it: a FastAPI backend, an MCP server for AI agents, and a Vue UI. The repository root **is** the data store — Markdown docs (numbered directories), YAML inventory in `40-inventory/`, JSON Schemas in `schemas/`, and an audit/pending-change area in `90-maintenance/pending-changes/`. +Gnexus Book is a personal infrastructure knowledge base plus the tooling that operates on it: a FastAPI backend, an MCP server for AI agents, and a Vue UI. The repository root remains the file-backend data store and the test fixture — Markdown docs (numbered directories), YAML inventory in `40-inventory/`, JSON Schemas in `schemas/`, and the legacy `90-maintenance/pending-changes/` area. Production on gnbook uses PostgreSQL as the canonical store; the file backend is frozen for writes there and is kept for rollback. Two consumers must keep working: @@ -18,7 +18,7 @@ Notable for this repository: - Commit messages follow `10-platform/git.md`; it overrides Claude Code's default attribution (no co-authorship lines). -- This file-backed prototype predates several handbook conventions (SSO, per-user MCP keys, streamable-HTTP MCP, off-host verified backups). `50-decisions/ADR-0002-postgres-storage-and-versioning.md` tracks the gaps and the planned move to PostgreSQL. +- The file-backed prototype predates several handbook conventions (SSO, per-user MCP keys, streamable-HTTP MCP, off-host verified backups); the PostgreSQL migration and gnbook deployment now implement them. `50-decisions/ADR-0002-postgres-storage-and-versioning.md` records the design. Production file writes are frozen with `GNEXUS_BOOK_FILE_BACKEND_FROZEN=true`; database changesets are the write path. ## Common commands @@ -90,8 +90,11 @@ secret and internal key secret; systemd loads it through `EnvironmentFile`. Local SSO details are in `30-runbooks/local-auth-testing.md`. -`GNEXUS_BOOK_STORAGE_BACKEND` defaults to `file`. Dumps go to the off-host NFS via +`GNEXUS_BOOK_STORAGE_BACKEND` defaults to `file`; gnbook sets `db` and +`GNEXUS_BOOK_FILE_BACKEND_FROZEN=true`. Dumps go to the off-host NFS via `scripts/backup-db.sh`; `scripts/restore-db.sh` requires `GNEXUS_BOOK_RESTORE_YES=1`. +The healthcheck timer runs every five minutes and checks the database plus backup-disk +usage; the backup and restore-drill timers are enabled on gnbook. ### UI @@ -109,6 +112,7 @@ ```bash ./scripts/install.sh # uv + Python 3.11, nvm/Node, clone/build ui-kit, venv, UI build, systemd user units ./scripts/deploy.sh # git pull, rebuild kit + UI, sync UI dist to /var/www/gnexus-book, restart backend, reload nginx +GNEXUS_BOOK_SKIP_KIT_PULL=1 ./scripts/deploy.sh # bundle-managed kit without GitBucket credentials ``` `systemd/*.service` hardcodes `/home/ubuntu/gnexus-book` paths — adjust them if the deployment user differs. Nginx (`nginx/gnexus-book.conf`) serves `ui/dist` on port 80, proxies `/api/` to the backend on 8000 and `/mcp/` to the MCP server on 8001. @@ -124,7 +128,7 @@ - **`relationships.py`** — builds a graph whose node ids are `/` and whose edges come from known cross-record fields (`host`, `hypervisor_host`, `runs_services`, `points_to`, `destination`, `related_*`, etc.). References to unknown ids are returned in `unresolved_references` rather than failing the request. - **`freshness.py`** — checks required frontmatter fields and staleness (`last_reviewed` + `review_interval`, e.g. `90d`), and reports inventory `docs:` targets that do not exist. - **`validation.py`** — the full-repo gate used before apply/commit: schemas parse as Draft 2020-12, every inventory file validates against its schema (`SCHEMA_BY_INVENTORY`), Markdown has required frontmatter, ids are unique per inventory file, and a regex scan detects raw secret assignments/private-key blocks. The separate inventory `docs`-link validator (`_validate_inventory_doc_links`) is intentionally disabled; freshness still reports those missing targets. -- **`pending_changes.py`** — the write path. A proposal is a JSON file in `90-maintenance/pending-changes/`; `apply()` writes a Markdown doc or patches/creates an inventory item, runs whole-repo validation, and restores the previous file content if validation fails. Only `doc` and `inventory-item` kinds can be applied; full-file inventory replacement is not implemented. +- **`pending_changes.py`** — the file-backend write path, frozen in production after the PostgreSQL cutover. A proposal is a JSON file in `90-maintenance/pending-changes/`; `apply()` writes a Markdown doc or patches/creates an inventory item, runs whole-repo validation, and restores the previous file content if validation fails. Only `doc` and `inventory-item` kinds can be applied; full-file inventory replacement is not implemented. - **`git_adapter.py`** — status/diff/commit. Commit requires an explicit file list, rejects absolute/traversal/denied paths, runs validation first, stages only the named files, and creates a local commit only (never pushes). - **`auth/`** — gnexus-auth integration: OAuth 2.0 PKCE login/callback, hashed browser sessions, user mirror, HMAC webhook handling, a pure-ASGI session guard, personal MCP key management (`mcp_keys.py`, `mcp_routes.py`), the MCP bearer guard (`mcp_guard.py`), and the actor context used by writes. Authentication is disabled unless `GNEXUS_BOOK_AUTH_CLIENT_ID`, `..._CLIENT_SECRET`, `..._BASE_URL`, and `..._REDIRECT_URI` are set; disabled mode is intentional for local development. The guard exempts `/health`, `/me`, `/auth/*`, and `/webhooks/gnexus-auth*`. The `gnexus-gauth` client library is a pinned git dependency. - **`storage/`** — the PostgreSQL layer introduced for the migration. `models.py` defines the schema (documents/versions/blobs, inventory items/versions, changesets, users, audit), `db_repositories.py` implements the read interfaces, `pending_changes_db.py` implements draft/apply changesets transactionally, `documents.py` provides history/version/diff/restore, `validation.py` validates the database, `importer.py` copies the repository into PostgreSQL, `parity.py` compares both backends, and `cli.py` exposes `import`, `parity`, and `counts`. `factory.py` selects docs/inventory/pending repositories from `GNEXUS_BOOK_STORAGE_BACKEND`. Alembic lives in `server/alembic/`. In `db` mode all knowledge writes go through changesets; `commit_changes` is a no-op. Validation, freshness, and relationships use the selected backend. diff --git a/server/README.md b/server/README.md index 6614069..4b274a4 100644 --- a/server/README.md +++ b/server/README.md @@ -83,16 +83,23 @@ retention and alerts through Synapse on failure when `SYNAPSE_URL` / `SYNAPSE_API_KEY` are configured. - `gnexus-book-backup.timer` runs the backup daily; the monthly - `gnexus-book-restore-drill.timer` is installed but disabled until a manual drill - succeeds. + `gnexus-book-restore-drill.timer` is enabled after a successful manual drill. - `scripts/restore-drill.sh [dump]` restores into a temporary database, validates it and drops it. - `scripts/healthcheck.sh` probes `GNEXUS_BOOK_HEALTH_URL` (default - `http://127.0.0.1:8000/health`) and checks `status` and `checks.db`. + `http://127.0.0.1:8000/health`), checks `status` and `checks.db`, and checks + `GNEXUS_BOOK_DISK_PATH` against the warning and critical percentage thresholds. +- `gnexus-book-healthcheck.timer` runs the probe every five minutes. - `scripts/notify-synapse.sh` sends a Synapse event envelope; it is used by the backup, restore-drill and healthcheck failure paths. - `deploy.sh` sources `server/.env`, runs `alembic upgrade head` when the `db` backend - is active, refreshes systemd units and restarts backend, MCP and frontend. + is active, refreshes systemd units and restarts backend, MCP and frontend. Set + `GNEXUS_BOOK_SKIP_KIT_PULL=1` when the sibling UI kit is bundle-managed and has no + GitBucket credentials. + +`GNEXUS_BOOK_FILE_BACKEND_FROZEN=true` freezes file-backend writes after a database +cutover; create/apply/delete and Git commit then fail with a clear error while reads +remain available for rollback. Full procedure: `../30-runbooks/postgres-operations.md`. @@ -165,9 +172,11 @@ GNEXUS_BOOK_MCP_HOST=0.0.0.0 GNEXUS_BOOK_MCP_PORT=8001 .venv/bin/python -m app.mcp_http ``` -`python -m app.mcp_server` still runs stdio for local development and tests; SSE is a -legacy fallback only. `GNEXUS_BOOK_MCP_TRANSPORT=streamable-http` delegates to the same -guarded HTTP app. +`python -m app.mcp_server` still runs stdio for local development and tests. SSE is not +served by the production MCP process; production clients use streamable HTTP only. +`GNEXUS_BOOK_MCP_TRANSPORT=streamable-http` delegates to the same guarded HTTP app. +`GNEXUS_BOOK_MCP_TOKEN` is an optional static break-glass token; normal access uses a +personal `mcp_*` key. Environment: @@ -292,6 +301,8 @@ ## Current Limitations - `POST /changes` creates pending change records in the file backend or changesets in the database backend. +- After the production cutover, the file backend is frozen for writes and its legacy + pending-change JSON was archived; database changesets are the active proposal path. - `POST /changes/{id}/apply` applies `kind=doc` and `kind=inventory-item` changes transactionally after validation. - Database mode publishes on apply; `POST /commit` is only available with the file backend. - Authentication is gnexus-auth SSO when configured; without client credentials the service runs open for local development.