Environment Variables

ATHELOS reads configuration from environment variables across three files. This page lists every variable and what it does.

The three env files

File	Used by
`.env`	Scripts and Drizzle Kit (from repo root)
`apps/web/.env.local`	The web application at runtime
`docker/.env`	Docker Compose services

Each has an .example template. Copy and fill in real values.

Root `.env`

Used by scripts that run outside the web app — database migrations, seeds, and maintenance tasks.

Variable	Required	Purpose
`DATABASE_URL`	Yes	Postgres connection string
`REDIS_URL`	Yes	Redis connection string
`MEILI_HOST`	Yes	Meilisearch HTTP endpoint
`MEILI_MASTER_KEY`	Yes	Meilisearch admin key
`AUTH_SECRET`	Yes	Session signing secret

Example:

DATABASE_URL=postgres://soc:password@localhost:5433/soc_solo
REDIS_URL=redis://:password@localhost:6379
MEILI_HOST=http://localhost:7700
MEILI_MASTER_KEY=<generate with openssl rand -base64 32>
AUTH_SECRET=<generate with openssl rand -base64 32>

`apps/web/.env.local`

The full runtime config for the web app.

Database

Variable	Required	Purpose
`DATABASE_URL`	Yes	Postgres connection string

Auth

Variable	Required	Purpose
`AUTH_SECRET`	Yes	Session signing key. Write-once.
`AUTH_TRUST_HOST`	Yes	Set to `true` for local dev behind a proxy
`NEXTAUTH_URL`	Yes	The public URL of the app (`http://localhost:3000`)

Redis

Variable	Required	Purpose
`REDIS_URL`	Yes	Redis connection string

Meilisearch

Variable	Required	Purpose
`MEILI_HOST`	Yes	HTTP endpoint
`MEILI_MASTER_KEY`	Yes	Admin key

MinIO

Variable	Required	Purpose
`MINIO_ENDPOINT`	Yes	Hostname (e.g. `localhost`)
`MINIO_PORT`	Yes	Port (`9000`)
`MINIO_USE_SSL`	Yes	`false` locally, `true` in production
`MINIO_ACCESS_KEY`	Yes	Access key ID
`MINIO_SECRET_KEY`	Yes	Secret access key
`MINIO_BUCKET`	Yes	Bucket for evidence files (`soc-evidence`)

Ollama

Variable	Required	Purpose
`OLLAMA_HOST`	No	Endpoint (default `http://localhost:11434`)
`OLLAMA_MODEL`	No	Chat model (default `llama3.2:3b`)
`OLLAMA_NUM_CTX`	No	Context window (default `2048`)
`OLLAMA_EMBED_MODEL`	No	Embedding model (default `nomic-embed-text`)

Optional. If Ollama isn't running, the AI features hide themselves.

TOTP encryption

Variable	Required	Purpose
`TOTP_ENCRYPTION_KEY`	Yes if TOTP enabled	AES-256-GCM key for encrypting TOTP secrets. Write-once.

Generate:

openssl rand -base64 32

WebAuthn

Variable	Required	Purpose
`WEBAUTHN_RP_ID`	Yes if WebAuthn enabled	Relying Party ID — the domain (`localhost` for dev)
`WEBAUTHN_RP_NAME`	Yes if WebAuthn enabled	Display name shown in the browser
`WEBAUTHN_ORIGIN`	Yes if WebAuthn enabled	The origin (`http://localhost:3000`)

SMTP (optional)

Variable	Required	Purpose
`SMTP_HOST`	No	Mail server
`SMTP_PORT`	No	Port (587 or 465)
`SMTP_USER`	No	Login
`SMTP_PASSWORD`	No	Password
`SMTP_FROM`	No	From address
`SMTP_TO`	No	Destination address
`SMTP_SECURE`	No	`true` for implicit TLS

Webhooks (optional)

Variable	Required	Purpose
`WEBHOOK_URL`	No	Endpoint to POST notifications to
`WEBHOOK_SECRET`	No	HMAC signing secret

Notification control

Variable	Required	Purpose
`EMAIL_NOTIFICATIONS`	No	`true` to enable email (default `false`)
`WEBHOOK_NOTIFICATIONS`	No	`true` to enable webhooks (default `false`)
`QUIET_HOURS_START`	No	e.g. `22:00`
`QUIET_HOURS_END`	No	e.g. `07:00`
`NOTIFY_DIGEST`	No	`true` for digest mode
`DIGEST_HOUR`	No	e.g. `08:00`

`docker/.env`

Used by Docker Compose to set service passwords.

Variable	Required	Purpose
`POSTGRES_PASSWORD`	Yes	Postgres password for the `soc` user
`REDIS_PASSWORD`	Yes	Redis AUTH password
`MINIO_ROOT_USER`	Yes	MinIO admin username
`MINIO_ROOT_PASSWORD`	Yes	MinIO admin password
`MEILI_MASTER_KEY`	Yes	Meilisearch admin key

Important: the values here must match the corresponding values in apps/web/.env.local — the app has to know the passwords to connect.

`backups/.env`

Used by restic.

Variable	Required	Purpose
`RESTIC_REPOSITORY`	Yes	e.g. `b2:bucket-name`
`RESTIC_PASSWORD`	Yes	Encryption passphrase. Write-once.
`B2_ACCOUNT_ID`	Yes	Backblaze key ID
`B2_ACCOUNT_KEY`	Yes	Backblaze application key

Write-once secrets

Three secrets must never change after first use:

Secret	Why
`AUTH_SECRET`	Rotating invalidates all active sessions
`TOTP_ENCRYPTION_KEY`	Rotating makes existing TOTP secrets undecryptable
`RESTIC_PASSWORD`	Rotating locks you out of existing backup snapshots

Back each one up to a password manager and on paper. Never commit them. Never email them. Never paste them into a chat.

Generating strong values

For passwords and secrets:

openssl rand -base64 32

For hex secrets:

openssl rand -hex 32

Use a different random value for each variable. Never reuse.

Where variables are read

Web app — apps/web/.env.local
Worker — reads from apps/web/.env.local (same config)
Scripts — root .env
Docker services — docker/.env
Restic — backups/.env

When scripts fail with "variable not set," check the correct file.

Reloading after changes

Env changes require a restart:

Web app — kill and restart pnpm dev or pnpm dev:site
Worker — kill and restart pnpm dev:worker
Docker services — docker compose up -d re-reads docker/.env

The web app doesn't hot-reload env changes.

Where to go next

Installation — setup steps
Security — threat model
Scheduled backups — restic config

Environment Variables

On this page