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

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, 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 canonical store, with immutable document and inventory versions grouped into changesets.
  • 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; 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/ (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, 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 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.
  • 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.
  • 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 archive

After the cutover, the file pending-change records were treated as legacy:

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

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: