Environment Variables

Tracearr uses environment variables for core configuration.

Required Variables

Optional Variables

Database Configuration

Tracearr requires TimescaleDB (PostgreSQL with the TimescaleDB extension) for time-series data storage.

DATABASE_URL=postgres://tracearr:password@localhost:5432/tracearr

Redis Configuration

Redis is used for caching and background job queues.

REDIS_URL=redis://localhost:6379

For Redis with authentication:

REDIS_URL=redis://:password@localhost:6379

To enable Redis key prefixing:

REDIS_PREFIX=myprefix:

Authentication Secrets

Tracearr requires two secrets, each a long random string unique to your installation (generate with openssl rand -hex 32):

• JWT_SECRET signs authentication tokens, including tokens for mobile devices paired on older versions.
• COOKIE_SECRET signs cookies.

A third secret, BETTER_AUTH_SECRET, signs and encrypts web and mobile sessions. It is optional: when unset, Tracearr derives it from JWT_SECRET (HKDF-SHA256), so existing installs need no new configuration. Setting it explicitly is recommended. Tracearr fails to start only when neither BETTER_AUTH_SECRET nor JWT_SECRET is set.

A fourth, ENCRYPTION_KEY, is 64 hex characters and also optional. It protects the stored configuration of every notification destination, including SMTP passwords and webhook URLs, and it signs the unsubscribe and browser-view links in newsletter email. Each of the two uses gets its own key derived from this value, so neither can open the other. When ENCRYPTION_KEY is unset both derive from JWT_SECRET by HKDF-SHA256 instead, and existing installs need no new configuration. Set it when you want to rotate JWT_SECRET without re-entering every destination secret.

JWT_SECRET=<64-character hex string>
COOKIE_SECRET=<64-character hex string>
BETTER_AUTH_SECRET=<64-character hex string>  # optional, recommended
ENCRYPTION_KEY=<64-character hex string>      # optional

A malformed value stops the server on start:

ENCRYPTION_KEY is set but is not 64 hex characters; fix or unset it

Rotating JWT_SECRET while ENCRYPTION_KEY is unset leaves Tracearr unable to read the stored destination secrets. Each affected destination is flagged “Re-enter this destination’s secret” in the list, receives nothing until you do, and cannot be tested.

OIDC Single Sign-On

Tracearr supports login through an OIDC identity provider (Authentik, Authelia, Keycloak, and similar). OIDC login is enabled only when all three of OIDC_ISSUER_URL, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET are set. The endpoint for the redirect URI is at /api/v1/auth/oauth2/callback/oidc.

OIDC_ISSUER_URL=https://auth.example.com
OIDC_CLIENT_ID=tracearr
OIDC_CLIENT_SECRET=<from your identity provider>
OIDC_PROVIDER_NAME=Authentik  # optional, defaults to "SSO"

When configured, the login page shows an SSO button labeled with OIDC_PROVIDER_NAME.

Reverse Proxy

Behind an HTTPS reverse proxy, logins work as long as the proxy preserves the Host header, forwards X-Forwarded-Host, or CORS_ORIGIN is set to the public URL. Forward X-Forwarded-Proto so session cookies carry the Secure attribute over HTTPS.

CORS_ORIGIN=https://tracearr.example.com
TRUST_PROXY=true

When CORS_ORIGIN is unset, the API reflects the request origin. Set TRUST_PROXY=true so Tracearr resolves the real client IP from X-Forwarded-* headers; this makes sign-in rate limits count per client instead of per proxy.

Three API paths answer without a login by design, and an authenticating proxy such as Authelia, Authentik or a Cloudflare Access policy must let them through:

/api/v1/email/unsubscribe/*
/api/v1/newsletters/view/*
/api/v1/images/proxy

The first is the unsubscribe page every newsletter links to; the second is the browser view of a digest that was sent; the third serves hosted poster images to mail clients. Gating the first two shows members a login page instead of the page they asked for, and gating the third leaves hosted posters blank. The first two carry their own limit of 60 requests a minute.

Claim Code

The CLAIM_CODE environment variable is used to protect the initial setup page.
This is recommended when Tracearr is exposed to the public internet.

When set, the claim code will be printed to the log on startup.

Before you can access the setup page, you must enter the claim code.

Base Path

Set BASE_PATH when you want Tracearr to be served under a subpath.
This ensures all routes, assets, and links are prefixed correctly.

BASE_PATH=/tracearr

DNS Cache

Set DNS_CACHE_MAX_TTL to enable DNS caching for outgoing requests.
This can improve performance by reducing the number of DNS lookups for frequently accessed hosts.
DNS caching is disabled if DNS_CACHE_MAX_TTL is not set.

DNS_CACHE_MAX_TTL=3600

Gzip Compression

Set GZIP_ENABLED=true to enable server-side gzip compression for HTTP responses.
This compresses static assets and API responses, reducing bandwidth usage.

GZIP_ENABLED=true

Poster Cache

Tracearr keeps one 360×540 copy of every poster under data/image-cache and keeps it until the poster changes or its item leaves the library. Nothing is evicted to make room. When free disk on that volume would fall under IMAGE_CACHE_MIN_FREE_PERCENT the cache stops growing, the precache pass reports disk-limited in Settings → General, and posters that are not cached are fetched from the media server on request. A library of 100k posters needs about 2 GB.

Backup Directory

Set BACKUP_DIR to customize where Tracearr stores database backups. The default location is /data/backup inside the container.

BACKUP_DIR=/custom/path/to/backups