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`

Optional Variables

Variable	Description	Default
`PORT`	HTTP server port	`3000`
`NODE_ENV`	Environment mode	`production`
`LOG_LEVEL`	Logging verbosity	`info`
`SESSION_SECRET`	Session encryption key	(generated)
`TZ`	Timezone	`UTC`
`CORS_ORIGIN`	Allowed CORS origin for API requests	`*`
`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

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:

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.