Configure Observe

The full environment variable reference lives in the repository README. These are the ones most installs touch.

Core

Variable	Default	Description
OBSERVE_ADDR	:3000	Listen address. Keep on localhost or tailnet when publishing ingest.
OBSERVE_INGEST_ADDR	(unset)	Optional second bind serving ONLY telemetry-write endpoints. This is the port to expose publicly; the dashboard does not listen on it.
OBSERVE_NUCLEUS_URL	postgres://localhost:5432/observe	Database engine connection.
OBSERVE_JWT_SECRET	(random)	Set in production to persist sessions across restarts.
OBSERVE_SECRET_KEY	(unset)	Master key for encrypting stored secrets at rest; required for LLM keys and S3/R2 credentials.
OBSERVE_ADMIN_PASSWORD	(unset)	Unset means no default — the /setup wizard creates the account on first visit.
OBSERVE_PUBLIC_URL	(unset)	External base URL used for SSO metadata and generated links. Set it whenever the instance is reachable by a name.
OBSERVE_RATE_LIMIT	1000	Default per-site events/sec; per-site overrides via API.
OBSERVE_TRUSTED_PROXIES	(unset)	CIDRs whose X-Forwarded-For are trusted. Empty trusts none, so clients can't spoof their IP to evade per-IP rate limiting.

Ingest durability

Variable	Default	Description
OBSERVE_WAL_MAX_TOTAL_BYTES	512 MB	Disk high-water across WAL segments. Durable mode refuses new events with a retryable 503 until the checkpoint advances; lossy mode deletes instead.
OBSERVE_WAL_GROUP_COMMIT_MAX_DELAY	25 ms	Bound of the group-commit window — ingest 200s share one fsync per window instead of one per event.
OBSERVE_WAL_LOSSY	(unset)	true opts into lossy mode: acknowledgments return without an fsync, with a declared loss budget. Default is durable mode.
OBSERVE_REQUIRE_WAL	(unset)	true refuses to start when WAL-backed durability is unavailable, instead of degrading to memory-only.

Retention

Raw events 30 days (OBSERVE_RAW_RETENTION_DAYS), hourly rollups 365, LLM traces 30, OTLP metric points 30, uptime results 90. Cleanup runs daily.

OTLP

HTTP ingest for traces, metrics and logs accepts both wire formats on the main listener. OTLP/gRPC is opt-in via OBSERVE_OTLP_GRPC_ADDR (e.g. 127.0.0.1:4317; plaintext unless TLS is configured, so keep it behind a proxy or tailnet).

Single sign-on (OIDC)

Optional. Set OBSERVE_OIDC_ISSUER and OBSERVE_OIDC_CLIENT_ID and the login page offers an SSO button (authorization-code flow with PKCE). Password login stays available as the break-glass path. Register https://<your-observe-host>/api/v1/auth/oidc/callback as the redirect URI with your provider.

Roles resolve from a teploy_role claim if present, otherwise from groups (OBSERVE_OIDC_ADMIN_GROUP, ..._EDITOR_GROUP, ..._VIEWER_GROUP), otherwise OBSERVE_OIDC_DEFAULT_ROLE (least privilege: viewer).

Forgejo works as the identity provider if you already run one — register an OAuth2 application, request the groups scope explicitly, and map roles by group. Group comparison is exact and case-sensitive, so copy names as Forgejo spells them.