Naru
Install
Run Naru with Docker Compose, terminate TLS in front, and decide administrators and sign-in methods.
Install
cp .env.example .env # PUBLIC_URL, SECRETS_KEY (openssl rand -base64 32), administrators, OIDC
docker compose -f deploy/compose.yaml up -d --build
- Terminate TLS in front (a company L7, nginx, Caddy) and set
PUBLIC_URLto that https address. MCP clients and OAuth use it as is. No trailing/. - The image has Node 24 and JRE 21 (for the sidecar). The container can run with a read-only root and
cap_drop: ALL. - Data lives in
/data(SQLitenaru.sqlite, pack bundles).DATABASE_URLselects PostgreSQL; packs and files still stay in/data. Run a single app instance.
Administrators and sign-in
-
Administrators: people in
ADMIN_EMAILS(comma-separated) become administrators at start. Empty: the log prints a/setup?token=…address to choose the first one. -
Sign-in methods (
LOGIN_METHODS):email(email codes only),oidc(company accounts only),email,oidc. Empty: email codes, plus company accounts whenOIDC_ISSUERis set. -
Email codes: a six-digit code (10 minutes, single use, void after five wrong tries) or the link in the same mail. Without
SMTP_URLandMAIL_FROM, codes are written to the server log. -
Company accounts (OIDC):
OIDC_ISSUER,OIDC_CLIENT_ID,OIDC_CLIENT_SECRET. An account is linked or created only when the IdP saysemail_verified: true. For IdPs that don't send that claim (ADFS, Entra ID) you can setOIDC_ASSUME_EMAIL_VERIFIED=1, but only when people can't change their own email attribute. -
When no administrator can sign in: print a link usable once within an hour.
bashdocker compose -f deploy/compose.yaml exec naru naru-recover you@example.com
Health
| Address | Checks |
|---|---|
/healthz, /healthz/live |
That the process is alive |
/healthz/ready |
That the database answers too (503 if not). Use it for load balancers and readiness |
Network
- Register Naru's outgoing address (the container host's IP) in the legacy systems' allowlists and firewalls.
- Private ranges are reachable. Link-local, cloud metadata and multicast are always blocked; loopback only with
NARU_ALLOW_LOOPBACK=1(development). - System TLS is
verify(public CAs; a company CA as PEM inca),pinned(public keysha256//…) orinsecure(development). mTLS and company proxies work too.
Next
- Systems and authentication
- Operations: naru-admin, key rotation, JDBC and Kerberos, audit, database
how to install · installation · deploy