---
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](../../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](../../90-maintenance/agent-mcp-usage.md).

Deployment and cutover:

- [../../30-runbooks/cutover-postgres.md](../../30-runbooks/cutover-postgres.md)
- [../../30-runbooks/postgres-operations.md](../../30-runbooks/postgres-operations.md)
- [../../30-runbooks/decommission-file-backend.md](../../30-runbooks/decommission-file-backend.md)
- [../../30-runbooks/local-auth-testing.md](../../30-runbooks/local-auth-testing.md)
