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

owner: gmikcon status: active last_reviewed: 2026-10-09 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.

Deployment

  • 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 in gnexus-creds, secret gnauth-gnbook-ssh).
  • Repository path: /home/ubuntu/gnexus-book (branch master).
  • Source of truth: Markdown, YAML inventory, JSON Schema, and Git history.

Runtime Components

  • Backend: FastAPI under server/.
  • Agent interface: MCP server under server/app/mcp_server.py.
  • UI: Vue/Vite under ui/.
  • UI dependency: gnexus-ui-kit.

Endpoints

  • REST API: http://192.168.1.170:8000/ (uvicorn, openapi at /openapi.json).
  • MCP (SSE): http://192.168.1.170:8001/sse.
  • UI (LAN): http://192.168.1.170:80/ (nginx serves the built SPA).
  • Services run as user-level systemd units under user@1000.service: gnexus-book-backend.service (uvicorn :8000) and gnexus-book-mcp.service (MCP server).

Backups (set up 2026-10-09 by rei, owner-requested)

  • Script: /home/ubuntu/gnexus-book-backup.sh (700, owner ubuntu) on gnbook.
  • What: full snapshot of the whole repo directory /home/ubuntu/gnexus-book as tar.gz (includes .git history, modified 40-inventory/*.yml, and all untracked 90-maintenance/pending-changes/*.json — 271 pending files are NOT in git, so a git-only backup would lose them) + git bundle create --all as a restorable history insurance.
  • Schedule: ubuntu crontab, daily 03:10 UTC (06:10 Europe/Kyiv), log: /opt/backups/gnexus-book/backup.log + cron.log.
  • Retention: 10 days (find -mtime +10 -delete for both gnexus-book-*.tar.gz and gnexus-book-*.bundle).
  • Sanity checks: tar must be non-empty and listable (contains README.md); bundle must pass git bundle verify (complete history). Any failure → exit 1, logged.
  • Typical size: tar.gz ~34.5 MB, bundle ~615 KB. Disk on gnbook: 15G total, 2.2G free — retention is mandatory, do not raise without checking disk.
  • Verified: manual run 2026-10-09 09:45 UTC, EXIT=0, gnexus-book-20261009-094532.tar.gz 34564532 bytes + bundle 614785 bytes, bundle verify OK ("complete history").
  • Restore sketch: tar xzf gnexus-book-<TS>.tar.gz -C /home/ubuntu restores the full repo including pending changes; or git clone gnexus-book-<TS>.bundle restored for history-only restore (working-tree modifications and untracked pending JSONs are NOT in the bundle — use the tar.gz for full restore).
  • Caveat: master is ahead of origin/master by 185 commits (origin is stale) — local backups are currently the only copy of recent history. Consider pushing to GitBucket (git.gnexus.space) as an off-host copy.

Maintenance Model

Agents should prefer structured inventory changes, validation, pending changes, and local commits through the maintenance API.

Pending-change queue lives in 90-maintenance/pending-changes/ (untracked JSON files; 11 older ones are git-tracked). Repository-wide validation scans every pending JSON, so a single invalid pending file blocks all applies and commits.

Poisoned-pending protection (since 2026-09-24, commit c77bcb1):

  • Create (propose_doc_change, propose_inventory_item_change, update_doc): payloads with secret patterns or unsafe doc targets (outside repo root) are rejected BEFORE any file is written — a rejected request leaves no pending file behind.
  • Apply: on validation failure the target file is rolled back AND the change's own pending JSON is removed (full rollback, both doc and inventory-item paths).
  • delete_pending_change (MCP) / DELETE /changes/{id} (REST): deletes pending or corrupt records; applied records are refused (409).
  • list_pending_changes tolerates corrupt JSON files and reports them with status corrupt; corrupt records can be deleted but not applied.
  • update_doc cleans up its own pending JSON automatically if apply or commit fails.

For agent-facing MCP usage rules, see ../../90-maintenance/agent-mcp-usage.md.

No raw credentials are documented here.