Newer
Older
gnexus-book / 10-systems / applications / gnexus-book.md

owner: gmikcon status: active last_reviewed: 2026-11-20 review_interval: 30d confidence: high

source_of_truth: ssh-host-verified

Gnexus Book

Gnexus Book is the canonical infrastructure knowledge base and maintenance API for the personal digital and server infrastructure.

Access

  • UI and REST: gnexus-auth SSO when authentication is configured; otherwise the local-development installation runs open.
  • Agents: personal mcp_* keys over streamable HTTP at /mcp-protocol/.
  • 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.

Deployment target

  • Runs as KVM VM gnbook (192.168.1.170) on hypervisor 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.

Storage and ownership

  • PostgreSQL database gnexus_book is the target 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.

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.

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/.
  • 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.

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

PostgreSQL backup and recovery:

  • Daily off-host pg_dump through gnexus-book-backup.timer; retention is configured by GNEXUS_BOOK_BACKUP_KEEP.
  • Restore procedure and periodic drill: ../../30-runbooks/postgres-operations.md.
  • Backup failures and failed health probes alert through Gnexus Synapse when a syn_* source key is configured.
  • Keep the legacy file backup until the decommission is complete.

Legacy file pending-changes protection

The file backend has poisoned-pending protection (commit c77bcb1, 2026-09-24):

  • 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.

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.

Maintenance model

Agents should prefer structured inventory changes, validation, draft changesets and apply/publish through the maintenance API or MCP. For MCP rules see ../../90-maintenance/agent-mcp-usage.md.

Deployment and cutover: