Configuration

Configure the Tindra server through environment variables. The defaults below are the binary's defaults; the installer, Docker Compose, or managed hosting may supply different values. SDK variables such as SENTRY_ENVIRONMENT belong in the application sending telemetry, not the Tindra server.

Applying changes#

For Docker Compose, add runtime variables to the tindra service's environment block and recreate the container with docker compose up -d. A value in Compose's .env file only reaches the container if the service references it or uses env_file.

For a directly run binary, set the process environment or a .env file in its working directory and restart the service. Existing process variables take precedence over .env at startup.

Use the literal strings true and false, quoted in YAML. Most boolean settings enable only for the exact value true; REQUIRE_MFA is enabled unless its value is exactly false. Numeric retention, rate, and row limits accept nonnegative integers; their documented 0 behavior is specific to each setting. Buffer sizes require positive integers and fall back to defaults for invalid or nonpositive values.

The advanced SIGHUP reload path only updates PROJECT_LIMIT, EVENT_LIMIT, and USER_LIMIT after reloading a local .env file. It does not reload SSO, retention, networking, or queue settings, and cannot change an existing container's environment. Recreate the container to apply Compose changes.

Required#

Server#

Limits#

Project, monthly event, user, log-row, and transaction-row caps are unlimited by default. Age retention and profile storage limits still apply.

Retention runs immediately at startup, then normally hourly. When a pass exhausts its deletion budget, the next catch-up pass runs after five minutes. Limits are cleanup policies, so stored rows or bytes can temporarily exceed a cap.

Row caps and profile policies run independently of RETENTION_DAYS, including when it is 0. Completed cron check-ins expire by completion time, with receipt time used for legacy records; running check-ins and monitor summaries are preserved. See Upgrades before changing retention on an existing instance.

Ingestion buffers#

These queues live in memory and retry eligible failed database writes within bounded attempts and deadlines. They do not survive a process crash. Events and transactions can be rejected when their queues are full; logs and profiles are best effort and can be dropped. A successful envelope response is not a guarantee that every item has reached storage.

Keep stop_grace_period: 75s in Compose to allow HTTP shutdown and bounded queue draining. Forced termination can lose pending data. Queue size is separate from database row/storage limits.

Profiles#

Profiles use their own retention window and compressed-storage budget. See Profiling.

To disable all profile cleanup, both profile limits must be 0. Increasing these limits does not restore previously deleted profiles.

Rate limiting#

Networking#

For a trusted immediate peer, Tindra walks X-Forwarded-For from right to left to the first untrusted address. A malformed supplied chain is not replaced with X-Real-IP; that fallback is considered only when no forwarded chain is supplied. Invalid entries in TRUSTED_PROXIES are skipped with a warning. See Reverse proxy.

Outbound address checks apply when connecting, including resolved addresses. Source-code enrichment always blocks internal destinations regardless of either opt-in. Uptime probes do not follow redirects; configure their expected status codes accordingly.

Security#

MFA enforcement restricts session-authenticated API access until enrollment. Project bearer tokens authenticate independently. See Authentication.

Internal#

/metrics exposes Prometheus ingestion counters and queue gauges using Authorization: Bearer <STATS_API_KEY>. It returns 404 when disabled and 401 for incorrect credentials. Its authentication does not need a database connection, so a database outage does not itself hide queue metrics. Counters reset when the process restarts.

The JSON status endpoint /api/instance/ingestion instead requires a user session with manage_projects; neither an operator metrics key nor a project API token grants that session permission.

Email#

Set EMAIL_PROVIDER to enable outbound email for alerts and invitations. Leave it unset to disable email entirely.

Common#

SMTP#

Postmark#

Brevo#

AhaSend#

Lettermint#

Cloudflare Email Routing#

OAuth / SSO#

All values below are unset by default. Configure the callback base and the complete settings for at least one provider before restarting. See Authentication for admission, verified-email linking, Microsoft setup, MFA, and recovery.

A nonempty callback base, client ID/secret, issuer URL, or Auth0 domain selects SSO-only authentication even if discovery fails. Local password login, password invitation acceptance, and reset redemption stay disabled until SSO configuration is intentionally removed and the server restarted. A provider name or Microsoft tenant alone is not a complete SSO configuration.

Docker Compose example#

This is a service fragment; see Self-Hosting for the full stack. Supply a URL-safe database password through Compose's .env file and keep it consistent with the Postgres service.

services:
  tindra:
    stop_grace_period: 75s
    environment:
      DATABASE_URL: "postgres://tindra:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}@postgres:5432/tindra?sslmode=disable"
      PUBLIC_URL: https://tindra.example.com
      BIND_ADDR: ":8080"
      DATA_DIR: /data
      COOKIE_SECURE: "true"
      RETENTION_DAYS: "90"
      PROFILE_RETENTION_DAYS: "7"
      PROFILE_STORAGE_LIMIT_MB: "2048"
      EMAIL_PROVIDER: smtp
      EMAIL_FROM: alerts@example.com
      SMTP_HOST: mail.example.com
      SMTP_PORT: "587"
      SMTP_USERNAME: alerts@example.com
      SMTP_PASSWORD: "${SMTP_PASSWORD:?Set SMTP_PASSWORD}"

POSTGRES_PASSWORD and PORT are inputs to the production Compose example, not Tindra binary settings. The password is required and has no built-in fallback; PORT defaults to 8080. Production Postgres is not published to the host, and the old POSTGRES_PORT mapping is no longer used. stop_grace_period is a Compose setting, not an environment variable.

Monitor ingestion health#

Use Ingestion Monitoring for authenticated Prometheus scrapes, queue and write metrics, and a recovery checklist when accepted data is not appearing. Pending in-memory data is not part of a database backup.