Skip to content

Environment variables

Every variable the install reads, in the layer that reads it. For each row, "Read by" is the container that consumes the value. Compose passes the full .env to both containers; only the rows below are actually read.

Web (web/)

Variable Required Default What it does
NEXTAUTH_URL yes — Public URL of the web UI. Must exactly match the redirect URI on your Google OAuth client. An https:// value also flips state cookies to the __Secure- prefix.
NEXTAUTH_SECRET yes — Signs the operator session JWT. 32 bytes minimum. Rotating it invalidates every existing session.
GOOGLE_CLIENT_ID yes — OAuth 2.0 client ID for Google OIDC. Created in Google Cloud Console.
GOOGLE_CLIENT_SECRET yes — OAuth 2.0 client secret. Server-side only — never exposed to the browser.
ARIS_AUTH_TOKEN_SECRET yes — HS256 secret. Web signs the bridge token, core verifies. Must be identical in both containers. 32 bytes minimum.
ARIS_API_URL yes — Base URL of core (set to http://core:8080/v1 by compose.yml).
ARIS_DATABASE_URL yes — Postgres DSN. Web reads authentication_identity + person directly during the OIDC signIn callback.
ARIS_TENANT_ID yes — Per-deployment namespace UUID. Must match core's value. The name is legacy; ARIS is not a multi-tenant SaaS system.
SESSION_TTL no 30m Session cookie lifetime. Format: <int><s\|m\|h\|d> (e.g. 8h, 1d).
ARIS_LOG_LEVEL no unset When debug, NextAuth runs in verbose mode.
ARIS_INFERENCE_PROVIDER yes for chat unset, treated as mock LLM provider type. One of openai, openai-compatible, litellm, anthropic, mock. For Bedrock/Vertex, run a gateway and set this to litellm or openai-compatible. See Inference.
ARIS_INFERENCE_API_KEY yes for chat — API key for the configured provider. Server-side only.
ARIS_INFERENCE_BASE_URL provider-dependent OpenAI/Anthropic defaults applied; required for openai-compatible and litellm Provider API base URL. Set to your gateway URL when fronting Bedrock, Vertex, or other managed-service providers.

Core (aris-server)

Variable Required Default What it does
PORT no 8080 TCP port the HTTP server binds to.
ARIS_DATABASE_URL yes — Postgres DSN. Core runs migrations against this DSN at boot, then opens the request-time pool from it.
ARIS_TENANT_ID yes — Per-deployment namespace UUID stamped onto every authentication_identity row by sync, and matched by login lookups. Two customer instances must not share a value.
ARIS_AUTH_TOKEN_SECRET yes — HS256 secret used to verify the web→core bridge token. Must match web's value. 32 bytes minimum.
ARIS_GOOGLE_DOMAIN yes — Workspace customer domain (e.g. acme.com). Used both as the OIDC tenancy gate and as the prefix for role group names (aris-admin@<domain>).
ARIS_GOOGLE_DELEGATE_EMAIL yes — Workspace Super Admin email impersonated by the service account for the Admin Directory API.
ARIS_GOOGLE_SERVICE_ACCOUNT_KEY_FILE yes — Container-internal path to the service-account JSON. Compose mounts the host file at /run/secrets/google-sa.json.
ARIS_DIRECTORY_SYNC_INTERVAL no 1h How often core re-pulls the Workspace directory. The single freshness knob — tighten to reduce role-staleness, loosen to save API quota.
ARIS_INGEST_GRPC_ADDR no unset Enables the collector ingest gRPC listener when set, for example 0.0.0.0:8443. Leave unset if you are not deploying collectors.
ARIS_INGEST_SERVER_CERT_FILE when ingest enabled — Server certificate core presents to collectors. The certificate SAN must match each collector's forwarder.mtls.server_name.
ARIS_INGEST_SERVER_KEY_FILE when ingest enabled — Private key for the ingest server certificate. Must not be group/world readable.
ARIS_INGEST_CLIENT_CA_FILE when ingest enabled — CA bundle core uses to verify collector client certificates.
ARIS_INGEST_MAX_FRAME_BYTES no 4194304 Maximum encoded collector frame size. Only read when ingest is enabled.
ARIS_INGEST_MAX_PAYLOAD_BYTES no 4194304 Maximum raw envelope payload size. Only read when ingest is enabled.
ARIS_INGEST_MAX_HOST_ID_BYTES no 253 Maximum collector host identity length. Only read when ingest is enabled.
ARIS_INGEST_SAFE_RAW_DISCARD_OTEL_SPAN_NAMES no unset Comma-separated exact OTel span names to discard before safe-raw persistence. Whitespace around names is trimmed; empty entries, including leading/trailing commas, fail startup. Only applies to otel_span envelopes, and only when every span in the envelope matches the configured list. Discarded records still count as WAL-consumed records and are also counted by core_ingest_safe_raw_discarded_total; keep the list short to avoid unnecessary metrics cardinality.
ARIS_INGEST_REQUIRE_ENROLLMENT no false When true, ingest requires active ARIS enrollment certificate and identity rows in addition to mTLS chain/SAN validation. Leave false for manual mTLS evaluation deployments.
ARIS_ENROLLMENT_SIGNER_MODE no inferred Collector certificate signer mode. Supported values are local-ca and external-command. If unset, core infers local-ca when CA cert/key files are set, or external-command when ARIS_ENROLLMENT_SIGNER_COMMAND is set.
ARIS_ENROLLMENT_SIGNER_COMMAND for external-command unset Absolute path to a customer-provided signer executable. Core sends a strict JSON signing request on stdin and expects {"certificate_pem":"..."} on stdout. The command must return a URI-SAN client-auth certificate matching the requested profile and chaining to ARIS_ENROLLMENT_CA_CERT_FILE.
ARIS_ENROLLMENT_CA_CERT_FILE for signer modes unset PEM CA certificate for the local CA signer, or trust bundle used to verify external-command signer output.
ARIS_ENROLLMENT_CA_KEY_FILE for local-ca unset PEM private key for the local CA signer. Must not be group/world readable. Do not set this for external-command.
ARIS_ENROLLMENT_CLIENT_CERT_HEADER no unset Trusted reverse-proxy header containing the URL-escaped PEM client certificate for POST /v1/collector/renew, POST /v1/collector/heartbeat, and POST /v1/collector/config/desired. Only set behind a proxy that strips inbound copies and verifies management mTLS; these requests also require proof signed by the collector private key.
ARIS_INFERENCE_CHAT_MODEL yes for Chat — Chat-completion model identifier read by the chat agent. When unset, the chat handler is not mounted. Reuses the ARIS_INFERENCE_PROVIDER/_BASE_URL/_API_KEY listed in the Web table — those are read by both containers. See Configure Chat.
ARIS_CHAT_RECEIPT_SIGNING_KEY_PATH yes for production Chat — Path to a PKCS#8 PEM ed25519 private key used to sign per-conversation receipt chains. If unset, an ephemeral keypair is generated at boot and a warning is logged; receipts won't verify across restarts.
ARIS_CHAT_RECEIPT_SIGNING_KEY_ID when _PATH is set auto-minted in dev Stable identifier for the signing key, written into every receipt. Required whenever ARIS_CHAT_RECEIPT_SIGNING_KEY_PATH is set.
ARIS_CHAT_ENABLED no true When false, all /v1/chat/* endpoints return 503 service_disabled and the web UI hides the chat panel. Read at startup; toggling requires a restart.
ARIS_CHAT_SQL_TOOL_ENABLED no true When false, the chat agent's query_sql/list_tables/describe_table tools are removed from the per-turn allowlist.

Compose-only (compose.yml)

These exist in .env solely so compose.yml can substitute them; neither container reads them directly.

Variable Required Default What it does
POSTGRES_PASSWORD yes — Password for the Postgres aris user. Used in the assembled ARIS_DATABASE_URL passed into core and web.

Collector (aris-collector)

Collectors do not read .env. They read a YAML file passed with --config; see Collector configuration.

File-vs-env precedence

For any variable named <NAME>_FILE, ARIS reads the file's contents and uses them in place of <NAME>. The file form is preferred for secret managers (Kubernetes Secret projection, Docker secrets, etc.). When both are set, the file wins.

Generating secrets

# 32 bytes for ARIS_AUTH_TOKEN_SECRET and NEXTAUTH_SECRET
openssl rand -hex 32

# UUID for ARIS_TENANT_ID
uuidgen | tr '[:upper:]' '[:lower:]'