Environment Variables

Tracearr uses environment variables for core configuration.

Required Variables

Variable	Description	Example
`DATABASE_URL`	PostgreSQL/TimescaleDB connection string	`postgres://user:pass@host:5432/tracearr`
`REDIS_URL`	Redis connection string	`redis://localhost:6379`
`JWT_SECRET`	Signing key for authentication tokens	64-character hex string
`COOKIE_SECRET`	Cookie signing key	64-character hex string

Optional Variables

Variable	Description	Default
`PORT`	HTTP server port	`3000`
`NODE_ENV`	Environment mode	`production`
`LOG_LEVEL`	Logging verbosity	`info`
`BETTER_AUTH_SECRET`	Session signing/encryption key	derived from `JWT_SECRET`
`TZ`	Timezone	`UTC`
`CORS_ORIGIN`	Allowed CORS origin for API requests	reflects the request origin
`TRUST_PROXY`	Trust `X-Forwarded-*` headers from a reverse proxy	`false`
`OIDC_ISSUER_URL`	OIDC issuer base URL	none
`OIDC_CLIENT_ID`	OIDC client ID	none
`OIDC_CLIENT_SECRET`	OIDC client secret	none
`OIDC_PROVIDER_NAME`	Label for the SSO login button	`SSO`
`REDIS_PREFIX`	Redis key prefix for namespacing	no prefix
`CLAIM_CODE`	Claim code for first time setup	none
`BASE_PATH`	Base path when served under a subpath	none
`DNS_CACHE_MAX_TTL`	DNS cache maximum TTL in seconds	disabled
`GZIP_ENABLED`	Enable server-side gzip compression	`false`
`BACKUP_DIR`	Directory for storing database backups	`/data/backup`

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 key prefixes must end with a delimiter (we recommend a colon ”:”) to ensure proper namespacing and avoid key collisions in shared Redis instances.


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.


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

Rotating JWT_SECRET also changes the derived BETTER_AUTH_SECRET when it is not set explicitly, which invalidates all web sessions and paired mobile devices. If you run multiple Tracearr instances against the same database, every instance must share the same BETTER_AUTH_SECRET, or the same JWT_SECRET when relying on derivation.

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.

Reverse proxies that rewrite the Host header must forward X-Forwarded-Host (or set CORS_ORIGIN to the public URL) for cookie login to work.

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

You only need to set this if Tracearr is accessed through a reverse proxy under a subpath (e.g. https://example.com/tracearr). If Tracearr is served at the root, this can be left unset.

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

Tracearr will respect the TTL provided by the DNS server, but will not cache entries longer than the value set in DNS_CACHE_MAX_TTL. Error responses (e.g. DNS resolution failures) are not cached to ensure that transient issues do not persist longer than necessary.

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

Most deployments sit behind a reverse proxy (e.g. Nginx, Caddy, Traefik) that already handles compression. Only enable this if Tracearr is serving traffic directly without a compressing proxy in front of it.
Enabling gzip will slightly increase CPU usage on the server.

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

When using Docker, the default /data/backup path is already configured as a volume. If you change this, ensure the directory exists and is writable, and mount it as a volume if needed.
See Backup & Restore for full documentation.