Naru

Install

Run Naru with Docker Compose, terminate TLS in front, and decide administrators and sign-in methods.

Install

bash
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_URL to 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 (SQLite naru.sqlite, pack bundles). DATABASE_URL selects 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 when OIDC_ISSUER is 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_URL and MAIL_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 says email_verified: true. For IdPs that don't send that claim (ADFS, Entra ID) you can set OIDC_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.

    bash
    docker 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 in ca), pinned (public key sha256//…) or insecure (development). mTLS and company proxies work too.

Next

Esc