owner: gmikcon status: active last_reviewed: 2026-11-19 review_interval: 90d confidence: high
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; access mode: all_active_users.editor with docs.write and inventory.write.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 client is registered through the gnexus-auth admin UI (/admin/clients) or an equivalent local setup procedure. Production must use an owner-registered client, HTTPS redirect/webhook URLs, and a narrower access mode.
A dedicated local user exists for end-to-end tests:
gnexus-book-test@local.test.~/.config/gnexus-book/local-auth-test-user.txt (chmod 600, outside the repository).editor; permissions: docs.write, inventory.write.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 permissions: ["docs.write", "inventory.write"].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.specific_users or groups instead of all_active_users..env.