Environment variables reference

Rootprint reads its configuration from environment variables at startup. For Docker deployments, set these under the environment key of the rootprint service. See Docker Compose for a full file.

Required

Variable	Description
`DATABASE_URL`	PostgreSQL connection string, for example `postgres://rootprint:rootprint@db:5432/rootprint`.
`ORIGIN`	Canonical public URL of this Rootprint instance, for example `https://logs.example.com`. Used for sign-in callbacks, invite links, the CORS allow-list, and cookies.
`QUICKWIT_URL`	Quickwit REST endpoint, for example `http://quickwit:7280`. Must point at Quickwit `0.9.0`; earlier releases are not supported.

Rootprint refuses to start if any required variable is missing or empty, or if ORIGIN or QUICKWIT_URL is not an http:// or https:// URL.

Optional

Variable	Default	Description
`BETTER_AUTH_SECRET`	Auto-generated	Signs session tokens and encrypts stored OAuth access and refresh tokens. If set, it must be at least 32 characters or startup fails. If unset, Rootprint generates one on first boot and stores it in the database, next to the tokens it protects. Set it yourself so a database compromise does not also expose the key.
`FRONTEND_URL`	Same as `ORIGIN`	Additional allowed CORS origin, for split deployments where the SPA is hosted on a different origin than the API. Sign-in callbacks, invite links, and cookies still use `ORIGIN`.
`PORT`	`8282`	HTTP listen port. Remap the port with the compose `ports:` block instead of changing this.
`TRACE_INDEX_ID`	`otel-traces-v0_9`	The span store: the one Quickwit index holding OTLP spans. See the warning below.
`LOG_LEVEL`	`info`	API log level: `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.
`SEARCH_AUDIT_RETENTION_DAYS`	`30`	Days of search activity audit rows to keep. Older rows are pruned hourly. Minimum `30`; a lower value fails startup.
`OIDC_DISCOVERY_TIMEOUT_MS`	`5000`	How long an OpenID Connect discovery fetch may take before the issuer is treated as unreachable.
`OIDC_RETRY_MS`	`60000`	How long to wait before retrying OpenID Connect discovery after it fails at boot. The provider stays hidden from the sign-in page until discovery succeeds.
`INGEST_PROXY_TIMEOUT_MS`	`120000`	How long an ingest request (`/api/ingest/ndjson`, `/v1/logs`, `/v1/traces`) may wait on Quickwit before Rootprint answers `503`. Set it below your shipper’s request timeout so the shipper gets a retryable `503` instead of timing out. Minimum `1000`.

A wrong TRACE_INDEX_ID fails silently. Rootprint treats a missing span store as an empty trace, so a typo looks like “no spans” rather than a misconfiguration.

Rate limiting

Both limiters are per process, so a horizontally scaled deployment multiplies the effective limit by the replica count. Put the authoritative limit at your reverse proxy if you need a cluster-wide one.

Variable	Default	Description
`RATE_LIMIT_WINDOW_MS`	`60000`	Window length in milliseconds, shared by both limiters. A `429` sends the window in seconds, rounded up, as `Retry-After` (`60` by default).
`PUBLIC_AUTH_RATE_LIMIT`	`30`	Requests per client IP per window on unauthenticated auth routes (first-admin setup, and invite and password-reset links).
`READ_RATE_LIMIT`	`300`	Requests per signed-in user per window on search, histogram, field values, trace and service health reads, MCP tool calls, and share resolution.
`TRUST_PROXY_HOPS`	`0`	Number of trusted reverse proxies in front of Rootprint that append to `X-Forwarded-For`. `0` uses the TCP peer address.

Set TRUST_PROXY_HOPS to your real proxy count — 1 for a single nginx or Caddy, 2 for a CDN in front of a load balancer. Setting it higher than the actual number lets a client prepend X-Forwarded-For entries and pick which IP the auth limiter counts against, defeating it.

Rootprint does not rate-limit the ingest endpoints (/api/ingest/ndjson, /v1/logs, /v1/traces). A 429 from them comes from Quickwit.

Get Started

Send Logs

Traces

Search Logs

Manage Rootprint

Environment variables reference

Required

Optional

Rate limiting

​Required

​Optional

​Rate limiting

Required

Optional

Rate limiting