Naru

Operations

naru-admin, environment variable names, key rotation, JDBC drivers and Kerberos, the database, and the limits of pack runner isolation.

naru-admin

naru-admin lives in packages/cli. It runs in two places.

  • Inside the image: the image has naru-admin (beside the recovery command naru-recover). docker compose exec -e NARU_URL=http://127.0.0.1:8080 -e NARU_TOKEN=… naru naru-admin --help
  • From a checkout on an admin machine: on a machine that reaches Naru, it runs on plain Node after pnpm install.
bash
pnpm install
alias naru-admin="node $PWD/packages/cli/bin/naru-admin.js"   # once, from the repository root
naru-admin login --url https://naru.corp.example --token <administrator naru_pat_…>   # or NARU_URL, NARU_TOKEN
Command Does
systems list | get | apply <yaml> | test <id> | delete <id> Register and update systems (by slug + env), check connections
systems secret <id> <name> A secret (standard input)
systems accounts <id> <csv> Person → legacy account table (key,accountId; key is accounts.key, email by default)
toolsets list | apply <yaml> | delete <slug> Toolsets
packs list | releases <pack> | deploy <pack> <dev|prod> <releaseId> Deploy and roll back
plugins list | approve <id> Approve code plugins
users list | add --email … --name … [--role developer] [--employee-no …] People
tokens list | issue --kind svc|dev|pat … | revoke <id> Tokens (--user takes a user id, usr_…)
trusts list | add | update | remove Mothership and Galpi trusts
audit [--since …] | --after <cursor> --jsonl Read the audit log, SIEM export

Environment variable names

Family name Naru's older name Meaning
PUBLIC_URL, PORT (default 8080), DATA_DIR same Address, port, data folder
SECRETS_KEY NARU_SECRETS_KEYS Seals secrets (comma-separated for rotation)
ADMIN_EMAILS NARU_ADMIN_EMAIL Administrators
SMTP_URL, MAIL_FROM same Mail
APP_LANG NARU_LANG Default language
LOGIN_METHODS (none) email, oidc, email,oidc
OIDC_* NARU_OIDC_* Company accounts (SSO)

Naru-only settings start with NARU_: NARU_DCR, NARU_FUNCTION_TIMEOUT_MS (60000), NARU_AUDIT_RETENTION_DAYS (730), NARU_DRIVERS_DIR, NARU_PLUGINS_DIR, NARU_KRB5_CONF, NARU_DEV, NARU_ALLOW_LOOPBACK.

Rotating keys

Put the new key first, as in SECRETS_KEY=new,old: new values are sealed with it and old ones still open. Save every value again, then remove the old key. Losing the key makes sealed values (legacy passwords, personal credentials, sign-in state) unreadable.

JDBC drivers and Kerberos

  • Get Tibero (tibero7-jdbc.jar), Altibase, CUBRID and DB2 drivers from their vendors and put them in NARU_DRIVERS_DIR (deploy/drivers in Compose). Naru doesn't ship them.
  • Oracle connects from Node in Thin mode (no Instant Client). SQL Server, PostgreSQL and MySQL are Node drivers too.
  • Kerberos takes krb5.conf from NARU_KRB5_CONF; the service account's keytab goes in as a secret: base64 -w0 svc.keytab | naru-admin systems secret <id> keytab.
  • The sidecar starts on the first JDBC or Kerberos call and restarts if it dies. It opens no port (standard I/O).
A JDBC system (Tibero, onbehalf)
slug: hr
env: prod
name: HR (Tibero)
driver: jdbc
endpoint:
  url: "jdbc:tibero:thin:@db.corp:8629:HR"
  driverClass: com.tmax.tibero.jdbc.TbDriver
  probe: "SELECT 1 FROM DUAL"
transport: { readOnly: true }
mode: onbehalf
serviceAccount: naru_ro
accounts: { from: employeeNo }
auth:
  - plugin: db-password
  - plugin: onbehalf
    config: { jdbcStatement: "BEGIN DBMS_SESSION.SET_IDENTIFIER(?); END;" }

Database

SQLite in DATA_DIR (naru.sqlite) by default. With DATABASE_URL, PostgreSQL (16, 17 and 18 supported; 18 recommended for new installs); pack bundles and files stay in /data. Either way run a single app instance. Moving between them and backups are in the repository's docs/database.md.

Limits of pack runner isolation

Pack code runs in a separate Node process per release and reaches systems only by asking the server over IPC. That is defence in depth for reviewed code, not an isolation boundary between people using the same pack (they share module state). Review pack code like any company code.

Esc