owner: gmikcon status: active last_reviewed: 2026-11-20 review_interval: 90d confidence: high
Local development only. This runbook describes the local gnexus-auth instance used for development. The gnbook deployment now uses the production instance at https://auth.gnexus.space; this local instance is not the production auth source. Do not assign book ownership to a local test identity.
How the local Gnexus Book instance is connected to the local gnexus-auth, which runs the same code as production.
http://gnexus-auth.local (nginx, MariaDB gnexus_auth).http://127.0.0.1:3005.http://127.0.0.1:3006.http://127.0.0.1:8001/mcp-protocol/.Runtime configuration lives in server/.env (chmod 600, gitignored). The systemd units load it through EnvironmentFile; the local scripts source it before starting the service. Do not commit it.
Required variables:
GNEXUS_BOOK_STORAGE_BACKEND=db GNEXUS_BOOK_DATABASE_URL=... GNEXUS_BOOK_AUTH_CLIENT_ID=... GNEXUS_BOOK_AUTH_CLIENT_SECRET=... GNEXUS_BOOK_AUTH_BASE_URL=http://gnexus-auth.local GNEXUS_BOOK_AUTH_REDIRECT_URI=http://127.0.0.1:3006/auth/callback GNEXUS_BOOK_AUTH_WEBHOOK_SECRET=... GNEXUS_BOOK_AUTH_COOKIE_SECURE=false GNEXUS_BOOK_INTERNAL_KEY_SECRET=...
Store the same secrets in gnexus-creds for any shared or production deployment.
gnexus-book-local (owner-provided local client); access mode: all_active_users.user; the local test identity is explicitly assigned the editor client role.editor, user, docs.write and inventory.write, but no client permissions. Gnexus Book mirrors the roles snapshot and does not depend on client permissions for authorization yet.http://127.0.0.1:3006/auth/callback and http://localhost:3006/auth/callback.http://127.0.0.1:3005/webhooks/gnexus-auth; insecure HTTP and private network access are explicitly enabled for local testing.The earlier gnexus-book test client is disabled and its secrets are revoked. The active local client is the owner-provided gnexus-book-local. Production must use an owner-registered client, HTTPS redirect/webhook URLs, a narrower access mode and properly defined permissions.
A local test identity exists for end-to-end tests. Its login, credentials and helper files stay outside the repository (~/.config/gnexus-book/, chmod 600). It is not the production owner and must not own production data.
editor on the gnexus-book-local client; client permissions are currently empty, so /me reports roles: ["editor"] and permissions: [].No real user account is used for automated checks.
# Backend with database storage and SSO (loads server/.env) ./scripts/dev-server.sh # MCP streamable HTTP (loads server/.env) ./scripts/dev-mcp.sh # UI cd ui && npm run dev
Open http://127.0.0.1:3006/ and use Sign in. The browser goes through gnexus-auth and returns to /auth/callback; Vite proxies /auth and /webhooks to the backend.
GET /health reports storage: db and checks.db.status: ok.GET /me returns auth_enabled: true and user: null.GET /me returns the test user with roles: ["editor"] and the client's current permissions (empty until permissions are defined).401 without a session./mcp-keys is available with a session.webhook.test delivery reaches POST /webhooks/gnexus-auth with 200 OK and appears in webhook_events.POST /auth/logout clears the session and /me returns user: null.sub are still pending; the local client and local test identity are not production credentials.specific_users or groups instead of all_active_users..env.GNEXUS_BOOK_MCP_ALLOWED_HOSTS to the public MCP hostname and GNEXUS_BOOK_MCP_ALLOWED_ORIGINS to its HTTPS origin, otherwise FastMCP rejects public requests with 421 Invalid Host header.