Skip to content

Configure

All configuration lives in a single .env file at the repository root. It is read by Docker Compose and passed into the core and web containers — neither container has any baked-in defaults for production secrets.

1. Copy the example

From the repository root:

cp .env.example .env

The example is committed; the resulting .env is gitignored. Never commit the populated file.

2. Generate secrets

ARIS needs two HS256 secrets, both at least 32 bytes:

  • ARIS_AUTH_TOKEN_SECRET — signs the 5-minute bridge token between web and core. Both containers must share the value.
  • NEXTAUTH_SECRET — signs the operator session cookie. Web only.

Generate fresh values:

openssl rand -hex 32

Run that twice (once per secret). Each call yields a 64-hex-character string, which is 32 bytes — exactly the minimum.

You also need a fresh deployment namespace ID:

uuidgen | tr '[:upper:]' '[:lower:]'

Save the value as ARIS_TENANT_ID. The env var name is legacy; in ARIS it is a per-deployment namespace for identity rows, not a multi-tenant customer boundary. Each customer instance should generate its own value.

Do not regenerate the deployment namespace ID after the first sync

Once you have docker compose up'd once and the directory sync has populated the identity tables, this ID is part of the identity link for every row. Changing it makes every existing user invisible to login.

3. Fill in .env

Open .env in an editor. Each variable is documented inline. Walking the file top to bottom:

Variable Value
POSTGRES_PASSWORD Any strong password. Used only inside the compose network — Postgres is not exposed to the host.
ARIS_TENANT_ID The per-deployment namespace UUID from uuidgen above.
ARIS_AUTH_TOKEN_SECRET First openssl rand -hex 32 output.
ARIS_GOOGLE_DOMAIN Your Workspace domain (e.g. acme.com).
ARIS_GOOGLE_DELEGATE_EMAIL The Super Admin email from Google Workspace setup §5.
ARIS_GOOGLE_SERVICE_ACCOUNT_KEY_FILE Absolute host path to the service-account JSON downloaded in §3. e.g. /home/you/.config/aris/sa.json.
ARIS_DIRECTORY_SYNC_INTERVAL Leave at 1h for now. See hardening for tuning.
NEXTAUTH_URL Where operators reach the web UI. Local: http://localhost:3001.
NEXTAUTH_SECRET Second openssl rand -hex 32 output.
GOOGLE_CLIENT_ID From the OAuth client in §2.
GOOGLE_CLIENT_SECRET From the OAuth client in §2.
SESSION_TTL How long an operator session lasts. 8h is a reasonable workday default.

4. Verify the file

A quick sanity check before the first run:

# All required vars are non-empty.
grep -E '^(POSTGRES_PASSWORD|ARIS_TENANT_ID|ARIS_AUTH_TOKEN_SECRET|ARIS_GOOGLE_DOMAIN|ARIS_GOOGLE_DELEGATE_EMAIL|ARIS_GOOGLE_SERVICE_ACCOUNT_KEY_FILE|NEXTAUTH_SECRET|GOOGLE_CLIENT_ID|GOOGLE_CLIENT_SECRET)=' .env \
  | grep -E '=$' \
  && echo "MISSING values above" || echo "all set"

# The service-account JSON exists and is readable.
test -r "$(grep -E '^ARIS_GOOGLE_SERVICE_ACCOUNT_KEY_FILE=' .env | cut -d= -f2)" \
  && echo "key file readable" || echo "key file missing or unreadable"

# Both secrets are 64 hex chars (32 bytes).
for v in ARIS_AUTH_TOKEN_SECRET NEXTAUTH_SECRET; do
  len=$(grep -E "^${v}=" .env | cut -d= -f2 | wc -c)
  echo "$v: $((len-1)) chars"
done

Each secret should print 64 chars (the trailing newline is subtracted).

Next: Run with Docker Compose →