Configuration reference
A self-hosted instance reads its settings from the .env file beside compose.yaml. .env holds only what differs between instances. The Compose file sets the rest.
The services check every setting when they start. An invalid value stops the service, with a message that names the setting. The messages never repeat a password.
After you change a setting, apply it:
docker compose up -dRequired settings
Section titled “Required settings”Compose stops before it starts anything when one of these is empty, with the message set … in .env.
| Setting | Meaning |
|---|---|
OTTERTRAIL_DOMAIN |
The instance’s domain, without https://, such as analytics.example.com. The instance’s address is https:// and this domain. |
POSTGRES_PASSWORD |
PostgreSQL’s password. Make it with openssl rand -hex 32. |
CLICKHOUSE_PASSWORD |
ClickHouse’s password. Make it with openssl rand -hex 32. |
AUTH_SECRET |
Signs the dashboard’s sign-in cookies. At least 32 characters. Make it with openssl rand -hex 32. If you change it, every user is signed out. |
PostgreSQL and ClickHouse keep the password they had when they first created their data. To change POSTGRES_PASSWORD later, first change the password in the database, then change .env:
docker compose exec postgres psql -U ottertrail -c "ALTER USER ottertrail PASSWORD 'new-password'"The release
Section titled “The release”| Setting | Default | Meaning |
|---|---|---|
OTTERTRAIL_VERSION |
The release of your compose.yaml |
The release to run, such as 0.2.0. Leave it unset to run the release that your compose.yaml comes from. See Update Ottertrail. |
LOG_LEVEL |
info |
fatal, error, warn, info, debug, trace, or silent. |
Object storage
Section titled “Object storage”For source maps and session replays. See Object storage.
| Setting | Default | Meaning |
|---|---|---|
COMPOSE_PROFILES |
object-store in example.env |
With object-store, Docker Compose also starts Garage, the object store on the same server. |
OBJECT_STORE_URL |
http://garage:3900 in example.env |
The S3-compatible endpoint. Without it, source maps and session replays are off. Do not put keys in the URL. |
OBJECT_STORE_REGION |
garage |
The region that requests are signed for. auto for Cloudflare R2. |
OBJECT_STORE_BUCKET |
ottertrail |
The bucket. It must exist. Garage creates it on its first start. |
OBJECT_STORE_ACCESS_KEY_ID |
none | The access key ID. Required with OBJECT_STORE_URL. For Garage, make it with printf 'GK%s\n' "$(openssl rand -hex 12)". |
OBJECT_STORE_SECRET_ACCESS_KEY |
none | The secret access key. Required with OBJECT_STORE_URL. |
GARAGE_RPC_SECRET |
none | Garage’s own secret: 64 hex digits, made with openssl rand -hex 32. Required with Garage. |
GARAGE_ADMIN_TOKEN |
none | Optional, with Garage only: Garage’s admin token, made with openssl rand -hex 32 (32 to 256 visible characters). With it, the Storage tab of the instance settings shows the bucket’s real size and Garage’s free disk space, and the worker keeps a quota on the bucket. The instance never logs or shows it. See Storage and warnings. |
SOURCE_MAP_STORAGE_BYTES |
1073741824 (1 GiB) |
Compressed source maps that the instance can keep, all projects together. From 1 MiB to 1 TiB. |
REPLAY_STORAGE_BYTES |
2147483648 (2 GiB) |
Compressed session replays that the instance can keep, all projects together. From 1 MiB to 1 TiB. |
The Storage tab of the instance settings shows how much of the disk these use, and warns before the budgets are full. See Storage and warnings.
Limits and retention
Section titled “Limits and retention”| Setting | Default | Meaning |
|---|---|---|
INSTANCE_EVENTS_PER_SECOND |
600 |
Events that the instance can store each second, all projects together, with bursts of ten seconds’ worth. A whole number from 5 to 1,000,000. Each project also has its own budget inside it. See Limits. |
TELEMETRY_RETENTION_DAYS |
30 |
Days that the instance keeps traces, logs, and metrics. From 1 to 365. The instance refuses records older than this. |
Uptime checks and webhooks
Section titled “Uptime checks and webhooks”Uptime checks and webhook deliveries never go to private addresses unless you allow them.
| Setting | Default | Meaning |
|---|---|---|
UPTIME_ALLOW_PRIVATE_ADDRESSES |
false |
true lets checks and webhooks reach loopback, private, unique-local, and shared (CGNAT) addresses, the stack’s own containers included. Set it only when every dashboard user may read those services. |
UPTIME_DENY_ADDRESSES |
none | IP addresses and CIDR ranges, separated by commas, that checks and webhooks may never reach, such as 203.0.113.10,2001:db8:1::/64. Put the server’s own public address here. An entry that is not an address or a range stops the API and the worker at start. |
Link-local addresses and the known cloud metadata services are refused in every case.
Alert email
Section titled “Alert email”Optional. Only alerts use email. Invitations and password reset links are links that you copy and send yourself. Webhooks need no setting.
| Setting | Default | Meaning |
|---|---|---|
SMTP_URL |
none (email off) | The SMTP server for alert email, with its user name and password. smtps://user:password@smtp.example.com:465 for TLS from the start, or smtp://user:password@smtp.example.com:587 for STARTTLS, which is then required. A relay without a password: smtp://relay.example.com:25. No path, query string, or fragment. Percent-encode @, :, /, ?, #, and % in the user name and password. The instance never logs it. |
EMAIL_FROM |
none | The sender: an address, or a name and an address, such as Ottertrail <alerts@example.com>. Required with SMTP_URL. Your email provider must allow this sender, with SPF and DKIM for its domain. |
Without SMTP_URL, you can add email channels, but nothing is sent to them. Their deliveries fail with a message that email is not set up.
Location data
Section titled “Location data”No setting in .env is needed. The worker downloads the location database and the data-center ranges, and keeps them current. The owner turns the automatic updates on or off in the instance settings, on the Location data tab. See Location data.
Values the Compose file sets
Section titled “Values the Compose file sets”Do not put these in .env. The Compose file sets them for the API, the worker, and migrate:
| Variable | Value |
|---|---|
NODE_ENV |
production |
PUBLIC_URL |
https:// and OTTERTRAIL_DOMAIN |
DATABASE_URL |
The stack’s PostgreSQL, with POSTGRES_PASSWORD |
CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_DATABASE |
The stack’s ClickHouse, as user ottertrail, database ottertrail |
TRUST_PROXY |
1: requests reach the API through Caddy, one proxy hop. See Behind a proxy or tunnel. |
Running the image without the Compose file
Section titled “Running the image without the Compose file”You can run the image, ghcr.io/ottertrail/ottertrail, on a platform that runs Docker images and gives it HTTPS. This setup is not tested. Then you set these variables yourself, beside the settings above that you use:
| Variable | Default | Meaning |
|---|---|---|
NODE_ENV |
production in the image |
In production, the required settings below have no defaults. |
HOST |
0.0.0.0 in the image |
The interface to listen on. |
PORT |
3000 |
The port, 1 to 65535. |
PUBLIC_URL |
none | The instance’s address: an https:// origin without a path. Required. Sign-in accepts requests from this origin only. |
DATABASE_URL |
none | The PostgreSQL connection URL, postgres://…. Required. |
CLICKHOUSE_URL |
none | ClickHouse’s HTTP interface, without a user or password in it. Required. |
CLICKHOUSE_USER |
ottertrail |
The ClickHouse user. |
CLICKHOUSE_PASSWORD |
none | The ClickHouse password. Required. |
CLICKHOUSE_DATABASE |
ottertrail |
The ClickHouse database: letters, digits, and underscores. |
AUTH_SECRET |
none | At least 32 characters. Required. |
TRUST_PROXY |
unset: trust no proxy | The number of proxy hops in front of the API (1 to 10), or a comma-separated list of proxy IP addresses or CIDR ranges. Without a proxy, leave it unset. |
GEO_SOURCE |
database |
Where visitor locations come from: database (the downloaded file), cloudflare (Cloudflare’s location headers), or none. Use cloudflare only when every request passes through Cloudflare, because any client can send these headers. With cloudflare or none, the location database is not downloaded. |
GEO_DATABASE_PATH |
/app/data/geo/dbip-city-lite.mmdb in the image |
The location database file. |
DATA_CENTERS_PATH |
data/geo/data-centers.json |
The data center address ranges, relative to the working directory, /app. |
The worker downloads both location files into their folder, and the API loads them from it. The worker needs write access to that folder, and the API must read the same one.
Also run these, which the Compose file runs for you:
- Run the migrations before each release starts:
node dist/migrate.mjs. The API does not migrate when it starts. - Run the worker as a second process, with the same variables:
node dist/worker.mjs.