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-local (owner-provided local client); access mode: all_active_users.user; the test user 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 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 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.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.