Configuration Reference
tripl is configured entirely through environment variables. The backend reads
them into a single Settings
object (Pydantic BaseSettings); values can come from the process environment
or from a .env file in the backend working directory
(model_config = {"env_file": ".env", "extra": "ignore", "env_ignore_empty": True}).
Unknown variables are ignored, so a single .env can hold backend, frontend,
and Docker Compose values side by side, and an empty value counts as unset, so
the default applies.
Under Docker Compose the containers do not read .env themselves: compose.yaml
has no env_file:, and only the variables its x-app-environment anchor names
reach the containers. Most are passed as VAR: ${VAR:-}, which is safe for a
variable you never set: Compose passes it as an empty string, and
env_ignore_empty turns that back into the default. A variable the anchor does
not name never arrives, whatever .env says. Four are left out on purpose:
DEBUG (the production stack relies on it being off), SERVE_FRONTEND and
FRONTEND_DIST_DIR (baked into the image) and PHOTO_LOCAL_DIR (it must be the
mounted /app/var/photos).
The canonical starting point is
.env.example.
Copy it to .env and fill in real values.
Every setting below is matched case-insensitively by its uppercased field name:
the database_url field is set with DATABASE_URL, rate_limit_login_per_minute
with RATE_LIMIT_LOGIN_PER_MINUTE, and so on. Defaults shown are the in-code
defaults from Settings; the production compose.yaml
overrides several of them, as noted.
How DEBUG changes everything
DEBUG is the master switch that decides whether tripl runs in a forgiving
development posture or a locked-down production one.
- Default:
false. - Accepted spellings (normalized before validation):
release,prod,productionare treated asfalse;dev,developmentare treated astrue. Any other value is parsed as a normal boolean. - When
DEBUG=false, the FastAPI lifespan callsSettings.assert_production_ready(), which refuses to start the process unless required secrets are set (see Production startup checks). DEBUGalso affects CORS resolution: in debug, an empty allow-list falls back to*.
assert_production_ready() runs from the FastAPI app lifespan. CLI tools and
the test suite that import Settings directly are not gated by it — only a
running API process enforces the checks.
Database & Broker
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
DATABASE_URL | postgresql+asyncpg://tripl:tripl@localhost:5432/tripl | Yes (must not keep dev creds) | Async SQLAlchemy URL used by the FastAPI app and Alembic migrations (asyncpg driver). |
SYNC_DATABASE_URL | postgresql+psycopg://tripl:tripl@localhost:5432/tripl | Yes (must not keep dev creds) | Sync SQLAlchemy URL used by the Celery worker (psycopg driver). |
RABBITMQ_URL | amqp://guest:guest@localhost:5672// | Yes (must not keep dev creds) | Celery broker AMQP URL. |
REDIS_URL | "" (empty) | No | Cache backend. Empty disables caching entirely — every read falls through to PostgreSQL. |
tripl maintains two PostgreSQL URLs pointing at the same database:
DATABASE_URL uses the async asyncpg driver for the web app, while
Alembic, while SYNC_DATABASE_URL uses the synchronous psycopg driver for
Celery. Keep host, port, database, and credentials identical between them; only
the +asyncpg / +psycopg driver suffix differs. Percent-encode reserved
characters in URL credentials (for example, @ as %40); Alembic preserves
the encoded URL when loading its configuration.
In the production compose.yaml
these are derived from compose-level secrets (the broker user is tripl, not
guest):
DATABASE_URL: postgresql+asyncpg://tripl:${POSTGRES_PASSWORD}@postgres:5432/tripl
SYNC_DATABASE_URL: postgresql+psycopg://tripl:${POSTGRES_PASSWORD}@postgres:5432/tripl
RABBITMQ_URL: amqp://tripl:${RABBITMQ_PASSWORD}@rabbitmq:5672//
REDIS_URL: redis://redis:6379/0
Your own PostgreSQL. Pointing tripl at an external or managed PostgreSQL,
let tripl's database role own its database. The migrations create the vector,
pg_trgm and unaccent extensions in the public schema when they are
missing (CREATE EXTENSION IF NOT EXISTS … WITH SCHEMA public), which needs a
role that may create extensions; if an administrator creates them first, the
migrations use them as they are. After a pgvector upgrade, the extension's
owner (or a superuser) runs ALTER EXTENSION vector UPDATE; until then the
migration logs a warning naming both versions instead of failing.
Identity & Secrets
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
ENCRYPTION_KEY | "" | Yes | Fernet key encrypting data-source and alert-destination secrets at rest. Must be a valid Fernet key. |
SECRET_KEY | "" | Yes | Application secret keying the HMAC over session tokens. Rotating it invalidates all existing sessions (users re-login once). |
APP_BASE_URL | "" | Effectively yes¹ | Public base URL of the deployment. Used to derive CORS origins when CORS_ALLOW_ORIGINS is empty, and to build the redirect URIs registered at an identity provider (Google's, and an Enterprise server's single sign-on). |
SESSION_COOKIE_NAME | tripl_session | No | Name of the session cookie. |
SESSION_TTL_HOURS | 168 (24×7) | No | Session lifetime in hours. |
SESSION_COOKIE_SECURE | false | Yes (must be true) | Marks the session cookie Secure so it is only sent over HTTPS. |
DEBUG | false | n/a | Master dev/prod switch — see above. |
¹ APP_BASE_URL is not checked by name, but if CORS_ALLOW_ORIGINS is empty
the production check fails unless APP_BASE_URL supplies an origin.
Generate the secrets:
# ENCRYPTION_KEY (Fernet)
python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
# SECRET_KEY (any long random value)
python -c 'import secrets; print(secrets.token_urlsafe(32))'
Edge & Hardening
CORS
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
CORS_ALLOW_ORIGINS | "" | Effectively yes¹ | Comma-separated explicit origin allow-list. |
Effective origins are resolved by Settings.cors_origins() in this order:
- If
CORS_ALLOW_ORIGINSis set, split on commas (whitespace trimmed). - Else if
DEBUG=true, fall back to["*"]. - Else if
APP_BASE_URLis set, use it (trailing slash stripped). - Else deny all (
[]).
Security headers
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
SECURITY_HEADERS_ENABLED | true | No | Toggles the security-headers middleware. |
HSTS_ENABLED | false | No | Adds Strict-Transport-Security. Only safe behind HTTPS with secure cookies. |
HSTS_MAX_AGE_SECONDS | 31536000 (1 year) | No | max-age for HSTS. |
CONTENT_SECURITY_POLICY | "" | No | Optional CSP. Left unset by default. When SERVE_FRONTEND is on and this is empty, a SPA-appropriate CSP is applied automatically. |
The production compose.yaml sets SECURITY_HEADERS_ENABLED=true and defaults
HSTS_ENABLED to true (overridable via the HSTS_ENABLED env). Enable HSTS
only once you serve over HTTPS exclusively.
Frontend serving
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
SERVE_FRONTEND | false | No | When true, the API also serves the built SPA from FRONTEND_DIST_DIR, so production runs a single container. |
FRONTEND_DIST_DIR | "" | No | Path to the built SPA assets served when SERVE_FRONTEND is on. |
In the published image, SERVE_FRONTEND / FRONTEND_DIST_DIR are baked in —
the single app container serves the JSON API and the SPA on port 8000. In
development the Vite dev server serves the SPA with HMR and proxies /api to
the backend, so these stay at their defaults.
Registration
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
REGISTRATION_MODE | open | Decide it | Who may create an account. open (the default) allows self-service signup — anyone who can reach the instance becomes a member of the default organization, who can read the member roster and create projects of their own. A member sees no existing project until the project's creator or an organization owner or admin adds them (Settings → Project → Access). Data source connection details (host, port, username) are for organization owners and admins only. disabled refuses POST /auth/register with 403 and hides the sign-up form. open is the default for historical reasons — it used to be the only way to onboard anyone. An owner can now invite people directly (Settings → Organization → Invitations → Invite a member), so disabled no longer blocks onboarding; set it once your team has accounts. With DEPLOYMENT_MODE=self_hosted the first registration on an empty instance is always allowed and becomes the default organization's owner and the platform admin. With hosted there is no such exception: disabled refuses every sign-up, the first one included, and each sign-up creates an organization of its own instead of joining the default one (see Hosted sign-up and email verification). Self-service sign-up never grants platform admin on a hosted instance, whatever PLATFORM_ADMIN_EMAILS lists; a listed address becomes a platform admin only when its account confirms the emailed verification link while signed in as itself. Overridable at runtime in Settings → Platform → Security & access, where it applies immediately. See Security & Hardening. |
Organizations
Every project, data source and API key belongs to an organization, and a user
can belong to several. An instance starts with one default organization;
access follows the organization role (owner, admin or
member) and the project role. These settings are environment-only — they
cannot be changed in Settings → Platform.
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
DEPLOYMENT_MODE | self_hosted | No | self_hosted is one team's instance. hosted is a multi-tenant service. hosted needs the Enterprise edition, whose package supplies the multi-tenant policy; a Community server with hosted refuses to start. It is read when the database is migrated to decide who becomes a platform admin (the operator of the whole instance). When the value is self_hosted, every owner of the default organization becomes a platform admin, and so does the first account of an empty instance. When the value is hosted, only existing accounts whose address is in PLATFORM_ADMIN_EMAILS do. It also decides which organization a request acts in when its URL does not name one (no /api/v1/orgs/{org}/ prefix): self_hosted always acts in the default organization; hosted acts in the user's only organization and answers 400 Organization required when the user belongs to none or to several (such a user names the organization in the URL). With hosted, sign-up creates a new organization, signing up needs the operator's SMTP, and an account must verify its email address before it can use anything beyond the /api/v1/auth/* routes; any signed-in user may create an organization. A new account made from an invitation on a hosted instance must verify its address too. With self_hosted none of that applies: every account is marked verified when it is created and nothing is ever gated. See Hosted sign-up and email verification. Any other value refuses to start. The platform-admin grant runs during the upgrades that add organizations (the organization schema, and again with organization roles). It only adds the flag and never revokes it. Changing the value between upgrades changes nothing until the next such upgrade. After that, platform admins are granted and revoked in the platform console or with tripl-admin. |
OUTBOUND_PUBLIC_HOSTS_ONLY | false | No | true makes every outbound request tripl makes on a user's behalf (warehouse connections, identity-provider discovery, key and token requests, webhook deliveries; search-embedding requests then refuse redirects) refuse a host that resolves to a private, loopback, link-local or otherwise internal address, and connect to the very address that was checked. Always on with DEPLOYMENT_MODE=hosted, whatever this says. Turn it on for a self-hosted instance whose users must not reach the network it runs in. See Security & Hardening. |
PLATFORM_ADMIN_EMAILS | empty | Only when hosted | Comma-separated account emails that become platform admins when DEPLOYMENT_MODE=hosted. Case and surrounding spaces are ignored. Only accounts that already exist when an organization upgrade runs are flagged, so create them first and set the list before upgrading. Signing up, accepting an invitation or completing a password reset with a listed address never grants it. Through the list, the only way is the emailed verification link: when an account with a listed address confirms that link while signed in as itself, it becomes a platform admin at that moment, so the grant follows proof of both the mailbox and the account. Removing an email revokes nothing; revoke in the platform console or with tripl-admin. An operator who cannot receive mail on a listed address can grant the flag with tripl-admin instead. |
ORG_SETTINGS_OPERATOR_FALLBACK | all | No | Covers an organization that has not set its own AI, SMTP or search-embedding settings. all means it uses the operator's; none means those features are off for it (the organization page shows Not shared by the platform) until it sets its own relay, AI endpoint or embedding endpoint and key. With none, an organization without its own embedding endpoint has semantic search off; lexical search still works. Non-secret values (row limits, AI timeout and token limits, prompts, the AI switch) fall back to the operator either way. Account mail (email verification, password reset, invitations) always uses the operator's SMTP. On a self_hosted instance the default organization's settings are the operator's, so this has no effect there; it matters for every other organization. |
GOOGLE_CLIENT_ID | empty | No | With GOOGLE_CLIENT_SECRET, turns on Continue with Google on the sign-in page: one Google OAuth client for the whole instance, unlike an organization's own single sign-on. The client's authorized redirect URI is <APP_BASE_URL>/api/v1/auth/google/callback. Google must have verified the address. An account with that address signs in; otherwise one is created where sign-up is open (REGISTRATION_MODE), joining the default organization when self_hosted and getting an organization of its own when hosted. |
GOOGLE_CLIENT_SECRET | empty | With GOOGLE_CLIENT_ID | The client's secret. Keep it out of the repository, like every other secret. |
GOOGLE_ALLOWED_DOMAINS | empty | No | Comma-separated email domains that may sign up with Google (gmail.com,example.com). Empty allows any. An existing account outside the list is refused too, unless it is a platform admin. |
OIDC_ISSUER | empty | No | The issuer of the instance's own OpenID Connect provider (https://…; tripl reads {issuer}/.well-known/openid-configuration). With OIDC_CLIENT_ID and OIDC_CLIENT_SECRET, turns on a sign-in button for it beside Google's. Register {APP_BASE_URL}/api/v1/auth/oidc/callback as the client's redirect URI. Not https: refuses to start. See Signing in through your identity provider. |
OIDC_CLIENT_ID | empty | With OIDC_ISSUER | The client id registered at the provider. |
OIDC_CLIENT_SECRET | empty | With OIDC_ISSUER | The client's secret. Keep it out of the repository. |
OIDC_SCOPES | openid email profile | No | Scopes asked for, space-separated. Must include openid and email, or the server refuses to start. |
OIDC_BUTTON_LABEL | Sign in with OpenID Connect | No | The button's text, for example Sign in with Okta. |
OIDC_ALLOWED_DOMAINS | empty | No | Comma-separated email domains that may sign in through the provider at all — existing accounts and platform admins included (unlike GOOGLE_ALLOWED_DOMAINS). Empty allows any address the provider verified. |
OIDC_AUTO_CREATE_USERS | true | No | Whether a first sign-in creates the account (where sign-up is open, REGISTRATION_MODE). false signs in existing accounts only. |
TELEMETRY_ENABLED | unset: on in Community, off in Enterprise | No | Anonymous usage telemetry: one small ping a day — instance id, version, edition, warehouse engines, bucketed counts — and never names, emails, hosts, queries or data. false turns it off. A public demo never sends. See Telemetry. |
TELEMETRY_ENDPOINT | https://telemetry.tripl.io/v1/ping | No | Where the ping goes. Empty or unset means the default; it does not turn the ping off — TELEMETRY_ENABLED=false or DO_NOT_TRACK=1 does. |
DO_NOT_TRACK | empty | No | The cross-tool opt-out: any true value (1, true) turns usage telemetry off, whatever TELEMETRY_ENABLED says. |
LICENSE_KEY | empty | Enterprise | Enterprise edition: its license key (tripl1.…), signed by tripl and checked offline. Set, it wins over a key saved in Settings → Platform → License, which then shows it read-only. Without a valid key (none, expired, not signed by tripl, or more accounts than its seats) Enterprise keeps running and warns platform admins. See License key. Community ignores it. |
KMS_PROVIDER, KMS_KEY_ID, KMS_* | empty | Enterprise | Enterprise edition: keep stored secrets under a key in your own key management service (AWS KMS, Google Cloud KMS, Azure Key Vault, HashiCorp Vault). compose.yaml forwards every KMS_* setting except KMS_LOCAL_KEY, which works only with DEBUG=true. See Key management. Community ignores them. |
PUBLIC_DEMO | false | No | Enterprise edition: read by its package, ignored by Community. A public demo instance: password sign-up is refused (Google only), and so is everything that would reach outside the instance — new warehouse connections, blank projects, further organizations, invitation email, outbound webhooks, tracker integrations, SSO and SCIM, organization AI/SMTP settings — and AI is off whatever the settings say. Owners and admins may create member-only invitation links, within the public demo limits; recipients sign in with Google before accepting. Demo projects keep working. See Running a public demo. |
PUBLIC_DEMO_SEARCH_EMBEDDINGS | false | No | With PUBLIC_DEMO, keeps the search embeddings that a public demo otherwise drops with every other AI credential. Still needs SEARCH_EMBEDDINGS_ENABLED and a key; visitors' queries and demo text then reach the provider on that key, so cap its budget there. Generative AI stays off. |
IDLE_ORG_RETENTION_DAYS | 0 | No | Enterprise edition: read by its package, ignored by Community. hosted only. Every night, organizations created more than this many days ago, with no member signed in and no demo project opened in that time, are deleted as an owner's delete would, and so are accounts left in no organization that have not signed in in that time (never a platform admin). 0 deletes none. The default organization is never deleted. |
Single sign-on per organization (OpenID Connect or SAML 2.0) is part of the Enterprise edition and has no environment variables.
The operator's shell tool: tripl-admin
tripl-admin is a console command installed with the backend (it is on the
PATH of the tripl image). It works on the database directly, over the same
SYNC_DATABASE_URL the Celery workers use, so it needs no running app, no
session and no mail. It is how the operator of a hosted instance makes the
first platform admin, and the way back in when every platform admin has lost
access; after that, the platform console
does the same from the browser. It also prints a password reset link for any
account: the way back in when the instance cannot send email and nobody who
could hand over a link can sign in (the first owner of a fresh install, say).
# In a compose deployment, from the directory holding compose.yaml and .env:
docker compose exec app tripl-admin grant-platform-admin ops@example.com
docker compose exec app tripl-admin list-platform-admins
docker compose exec app tripl-admin revoke-platform-admin former-ops@example.com
docker compose exec app tripl-admin password-reset-link ada@example.com
| Command | What it does |
|---|---|
grant-platform-admin EMAIL | Makes the account with that address a platform admin, and marks its address verified if it was not (recorded as marked_verified: true in the audit entry). Granting an existing admin changes nothing. |
revoke-platform-admin EMAIL | Takes the flag away. Refuses to revoke the last platform admin, so the instance always keeps one. |
list-platform-admins | Prints the address of every platform admin. |
password-reset-link EMAIL | Prints a single-use password reset link for the account, on APP_BASE_URL (or its Settings → Platform → Runtime override; when both are blank it prints the path and says so). It is the emailed reset's own token: it expires after an hour, works once and replaces any earlier link. The password keeps working until the link is used, and using it signs the account out everywhere and revokes its API keys. The operator vouches for the address, as for a grant. Audited at platform scope as user.password_reset_link with via: "tripl-admin". Exits 1 for an unknown address. |
The address is matched without regard to case and must belong to an existing
account: create it first (sign up, or accept an invitation). An unknown address
or a refused revocation prints the reason and exits non-zero, so a provisioning
script can stop on it. The command does not look at DEPLOYMENT_MODE or
PLATFORM_ADMIN_EMAILS and does not require the address to be verified:
whoever can run it on the server already controls the instance, so a grant
marks an unverified address verified instead.
Operator and organization settings
Every setting editable in the UI is either the operator's (tripl's own infrastructure, one value for the whole instance) or an organization's (each organization may set its own value). An organization resolves each of its fields as its own value → the operator's value → the environment variable → the built-in default, subject to three rules:
- A secret travels with its endpoint. The AI endpoint, key and model form
one group; the SMTP host, port, security, username, password and From:
address form another; the search-embedding base URL, provider, model and key
form a third; the photo storage backend, GCS bucket, service-account JSON,
public-URL switch and signed-URL lifetime a fourth. An organization that sets any field of a group owns the
whole group: fields it left empty take the built-in default (a secret is
empty), never the operator's. Pointing
ai_base_url,smtp_hostorsearch_embedding_base_urlat your own server therefore never sends the operator's key or password there, and an organization's own bucket is never written with the server's GCS credentials. - Operator ceilings. An organization's
scan_row_limit_default,metrics_row_limit_default,ai_timeout_seconds,ai_max_output_tokensandphoto_max_size_mbmay lower the operator's value, never raise it: a higher value is refused on save (422) and clamped at use if the operator later lowers theirs. Likewise an organization'sphoto_allowed_mimemay only narrow the operator's allow-list: a content type the operator does not allow (SVG, HTML) is refused on save and dropped at use. - Public hosts only, for organizations. An organization's
ai_base_url,search_embedding_base_urlandsmtp_hostmust not be (or resolve to) a private, loopback or link-local address, in either deployment mode. The check runs on save (422) and again right before each request, so a name re-pointed at an internal address later is refused too (the feature is off for that call). An AI or embedding endpoint that answers with a redirect is refused rather than followed (on ahostedinstance the operator's embedding endpoint too). The operator's own values — which on aself_hostedinstance are also the default organization's — may point at private hosts such as a local model server or relay.
If an organization's settings cannot be read, background jobs (alerts, digests, notification email, AI explanations, search embedding) run with AI, email and embeddings off for that organization; a request fails rather than falling back to the operator's keys.
Search embeddings per organization. Each organization has its own vector
space. Vectors are stamped with the organization's provenance — its endpoint,
provider, model and the dimensions — and a query only compares with rows
stamped with the provenance of the organization it runs in. An organization
that inherits the operator's endpoint has exactly the operator's provenance, so
introducing organizations re-embeds nothing. SEARCH_EMBEDDING_DIMENSIONS
stays the operator's (the column is vector(1536) for everyone): when an
organization saves its own endpoint or model with embeddings on, tripl embeds
one short test text with it and refuses the save (422) unless the answer is a
1536-value vector. A save that changes an organization's embedding identity
(on/off, endpoint, provider or model) queues a reindex of that organization's
projects only; unchanged rows keep their vectors. A change to the operator's
values reaches the organizations that inherit them through the regular stale
sweep. The operator's own base URL stays env-only (SEARCH_EMBEDDING_BASE_URL):
on a self_hosted instance the default organization cannot change it in
settings (422).
Photo storage per organization. An organization's owners and admins can
give it storage of its own under Settings → Organization → Photos: a GCS
bucket with the organization's own service-account JSON key (pasted in the
page, encrypted at rest, never returned: the response only says whether one is
configured). On a self_hosted instance an organization other than the default
one may pick the local backend instead (the operator's PHOTO_LOCAL_DIR); on
a hosted instance it may not (422). The server paths PHOTO_LOCAL_DIR and
GCS_PHOTO_CREDENTIALS_PATH are the operator's alone. An organization without
storage of its own uses the operator's, whatever
ORG_SETTINGS_OPERATOR_FALLBACK says. The save is refused (422) for a GCS
bucket without a key of its own, a key that is not a loadable service-account
JSON, a key whose token_uri is not https://oauth2.googleapis.com/token or
whose universe_domain is not googleapis.com (the server would otherwise
send its token requests wherever the key says), or an invalid bucket name. Changes apply to the next upload: every photo
row records the organization and the storage version it was written with
(a photo_storage_configs row per distinct bucket/key/flags), and each photo is
read and deleted through that version, so moving to another bucket or rotating
the key keeps older photos working as long as the old bucket and key still
grant access. New uploads are keyed orgs/{organization id}/events/... on
whichever store they land in. Everyone in the organization can read its upload
limits at GET /api/v1/orgs/{org}/settings/photo-limits. Deleting an
organization deletes its photos through its own storage. The
Content-Security-Policy admits https://storage.googleapis.com images for the
pages of an instance where the operator or any organization stores photos in
GCS, and per organization for API responses; a policy set with
CONTENT_SECURITY_POLICY is used as given.
Tracker defaults per organization. An organization's owners and admins can
set Jira and Linear defaults under Settings → Organization → Trackers: the
Jira site, account email, API token and default project key, and a Linear API
key and default team. A project's own tracker config overrides each field; a
project still has to switch the automation on itself. The Jira site, account
and token are one unit: a project that sets any of the three uses none of the
organization's. Tokens are encrypted at rest and never returned; the Jira site
must be https and public (checked on save and before every call).
| Setting | Scope | Where it is edited |
|---|---|---|
Public URL (APP_BASE_URL) | Operator | Settings → Platform |
Security & access (CORS, cookies, headers, rate limits, REGISTRATION_MODE) | Operator | Settings → Platform |
| Observability (request id, logging, metrics, tracing) | Operator | Settings → Platform |
PHOTO_LOCAL_DIR, GCS_PHOTO_CREDENTIALS_PATH (server paths) | Operator | Settings → Platform |
| Photo storage: backend, GCS bucket, public URLs, URL lifetime, service-account JSON (organization only) | Organization (inherits the operator's store when unset) | Settings → Organization → Photos |
PHOTO_MAX_SIZE_MB, PHOTO_ALLOWED_MIME | Organization (capped by / a subset of the operator's) | Settings → Organization → Photos |
| Search embeddings: switch, provider, model, key, base URL | Organization (the operator's base URL is env-only) | Settings → Organization → Semantic search |
SEARCH_EMBEDDING_DIMENSIONS | Operator, env-only (1536) | read-only |
| Jira / Linear tracker defaults (site, account, token, project; key, team) | Organization (no operator layer; projects override) | Settings → Organization → Trackers |
Database, broker, Redis, ENCRYPTION_KEY, SECRET_KEY (the "system" block) | Operator, env-only | read-only in Settings → Platform |
| Email / SMTP (6 fields) | Organization | Settings → Organization → Email |
| AI chat: switch, base URL, model, key, timeout, output tokens, the three prompts | Organization | Settings → Organization → AI |
SCAN_ROW_LIMIT_DEFAULT, METRICS_ROW_LIMIT_DEFAULT | Organization (capped by the operator) | Settings → Organization → Limits |
The operator's values of the organization fields are the defaults every
organization inherits (with ORG_SETTINGS_OPERATOR_FALLBACK=all), and the
operator's SMTP is the relay account mail always uses; the platform admin sets
them under Settings → Platform. On a self_hosted instance the default
organization is the operator scope: what its owners and admins set under
Settings → Organization is the instance's value. Its limits, timeouts and
prompts are theirs to change; its SMTP relay and AI endpoint (the whole group,
key and password included) take a platform admin (403 Platform admin required), because password-reset and invitation mail go through that relay
and, with ORG_SETTINGS_OPERATOR_FALLBACK=all, every other organization
inherits both. The same applies to the embedding key, provider, model and
switch, and to the storage fields: the operator's bucket holds every inheriting
organization's photos, and its size cap and content types are every
organization's ceiling. The operator's storage values take effect when the
server restarts; an organization's own apply to its next upload. The API is GET/PATCH/PUT /api/v1/orgs/{org}/settings (with
POST .../ai/test and .../email/test, and GET/PATCH .../trackers for the
tracker defaults) for an organization's owners and admins, plus
GET .../photo-limits for every member,
and GET/PATCH /api/v1/platform/settings (with the same two probes) for a
platform admin. The older /api/v1/settings (GET/PATCH/PUT, with /ai,
/ai/test and /email/test) is deprecated: clients should use
/api/v1/platform/settings and /api/v1/orgs/{org}/settings. It still answers
with the combined view: operator fields as the operator has them and
organization fields as the caller's organization runs with them. For anyone but
a platform admin its security, storage, observability and system blocks
are null and the embedding base URL is blank unless it is the organization's
own.
Rate limiting
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
RATE_LIMIT_ENABLED | true | No | Master toggle for auth-endpoint rate limiting. |
RATE_LIMIT_LOGIN_PER_MINUTE | 5 | No | Login attempts per (ip, route) per minute. 0 disables this limit. |
RATE_LIMIT_REGISTER_PER_HOUR | 3 | No | Registrations per (ip, route) per hour. 0 disables this limit. |
RATE_LIMIT_SSO_PER_MINUTE | 100 | No | Google and OIDC sign-in requests (start and callback share the bucket) per client per minute. Kept high because many visitors can sign in from one NAT address (conference Wi-Fi, an office). 0 disables this limit. |
RATE_LIMIT_TRUST_FORWARDED_FOR | false | No | Derive client IP from X-Real-IP (or RATE_LIMIT_CLIENT_IP_HEADER), else the rightmost X-Forwarded-For entry (the one the nearest proxy appended), instead of the socket peer. |
RATE_LIMIT_CLIENT_IP_HEADER | empty | No | A header that carries the client address, read before X-Real-IP, e.g. CF-Connecting-IP behind Cloudflare. Read only when RATE_LIMIT_TRUST_FORWARDED_FOR=true; the proxy must overwrite it on every request. |
APP_BIND_ADDRESS | 127.0.0.1 | No | compose.yaml only, not an app setting: the host address the app container's port 8000 is published on. Loopback is reachable only from processes on the host (or containers with network_mode: host); a containerized proxy joins the stack's network and targets http://app:8000, or uses the docker bridge gateway (e.g. 172.17.0.1) here; 0.0.0.0 publishes it on every interface. See Running behind a proxy. |
With REDIS_URL set the buckets live in Redis and every worker shares one
quota per client; without Redis each worker keeps its own. Leave
RATE_LIMIT_TRUST_FORWARDED_FOR=false (the default) whenever clients reach the
API directly. Enable it only when every request reaches the API through a
trusted proxy/LB that overwrites X-Real-IP (or the header named in
RATE_LIMIT_CLIENT_IP_HEADER) or appends to X-Forwarded-For; on a directly
exposed API a caller sets any of these headers, rotates it per request and
bypasses the limit. Behind a proxy with it left false, every client shares
the proxy's one bucket.
Observability
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
REQUEST_ID_HEADER | X-Request-ID | No | Header used to read/emit a per-request correlation ID. |
LOG_LEVEL | INFO | No | Log level (uppercased and trimmed). |
LOG_JSON | false | No | Emit one-line JSON logs instead of plain text. Compose/k8s should enable this. |
PROMETHEUS_METRICS_ENABLED | false | No | Exposes the /metrics endpoint and Celery task instrumentation. |
PROMETHEUS_MULTIPROC_DIR | unset outside Compose | No | Shared writable directory for Prometheus metrics from all API and Celery worker processes. Compose sets /app/var/prometheus and mounts it in both services. |
OTEL_EXPORTER_OTLP_ENDPOINT | "" | No | Setting a non-empty value opts the API and worker into FastAPI/SQLAlchemy/Celery auto-instrumentation via an OTLP exporter. The production image includes the optional tracing dependencies; a blank endpoint disables export. |
OTEL_SERVICE_NAME | tripl | No | Service name reported by the OTLP exporter. |
compose.yaml defaults LOG_JSON to true (overridable); the API, Celery
worker, and beat use the configured log level and format. Expose /metrics
only on an internal-only ingress path or scrape via a sidecar. Compose shares
the Prometheus multiprocess directory between the API and worker and clears old
metric files before those processes start. When running without Compose, create
a writable shared directory and clear stale files before each deployment. Each
failed Celery task contributes one failure count to tripl_celery_tasks_total.
Demo project
These control the generated demo project and the demo warehouse every demo reads. All of them have working defaults, and none affects real projects.
| Variable | Default | Required in prod? | Purpose |
|---|---|---|---|
DEMO_ENABLED | true | No | Master kill switch for demo provisioning. When false, POST /projects/demo and demo reset are refused with 403 Demo provisioning is disabled. |
DEMO_RUNTIME_ENABLED | true | No | Whether demos advance. When false, a demo's scheduled collection is never dispatched: it keeps exactly what provisioning built, and Run now and Replay still work. The warehouse writer is not affected. |
DEMO_HISTORY_DAYS | 23 | No | Days of warehouse history a new demo replays (2–30). 23 is three weekly cycles, which the hour-of-week baseline needs, plus two days to score. A shorter history still makes a complete demo, faster, with a baseline blind to the weekly pattern. At most DEMO_WAREHOUSE_RETENTION_DAYS: the server refuses to start with more, since a build would replay days the warehouse no longer holds. |
DEMO_WAREHOUSE_MODE | auto | No | Which engine serves demos: auto uses the PostgreSQL warehouse when it is ready and the in-memory engine otherwise; postgres always uses the warehouse (a failure is the scan's error); memory always uses the in-memory engine and leaves the writer idle. On a public demo, auto never uses a warehouse on tripl's own server: visitors' SQL runs there, so it needs DEMO_WAREHOUSE_URL on a server of its own. |
DEMO_WAREHOUSE_URL | (empty) | No | The warehouse writer's DSN, for a database provisioned by hand. Empty derives it from SYNC_DATABASE_URL, with the database name <name>_demo (tripl_demo in compose), which migrate creates. A public demo needs it to name a PostgreSQL server of its own, with a memory limit. |
DEMO_WAREHOUSE_READER_PASSWORD | (empty) | No | The password of the reader role, <warehouse database>_reader (tripl_demo_reader in compose), provisioned by hand. Empty derives one from SECRET_KEY (never stored; rotating the key rotates it on the next migrate) and lets migrate manage the role. |
DEMO_WAREHOUSE_RETENTION_DAYS | 30 | No | Days of rows the warehouse keeps (23–365); older day partitions are dropped. A demo project's own observed rows are pruned to the same horizon every day. |
DEMO_WAREHOUSE_MAX_MB | 1024 | No | Size cap of the warehouse database, in MB (at least 64). Over it, the oldest days beyond the 23 a demo replays are dropped and an error is logged: a backstop, not the plan. |
DEMO_POOL_SIZE | 0 | No | Enterprise edition: read by its package, ignored by Community. How many demos to keep seeded ahead of time (0–50). Above 0, the refill-demo-pool beat task keeps that many ready in a service organization, and Generate demo project hands one out at once instead of queueing a seed; with the pool empty it seeds as usual. The pool only refills after a claim, so an idle instance seeds nothing more. 0 turns it off. |
DEMO_POOL_MAX_AGE_HOURS | 20 | No | Enterprise edition: read by its package, ignored by Community. A pooled demo older than this (1–23 hours) is discarded and seeded again, so its seeded incident is still open when a visitor gets it. |
The worker's write-demo-warehouse beat task writes the warehouse every five
minutes (its first run backfills the whole retention window in under a minute),
and a demo is advanced by its scan's ordinary scheduled collection reading it.
A demo collects at most every six hours rather than hourly, because most of
a collection's cost is detection over dozens of series and every demo on a
deployment would pay it every hour. A demo nobody has opened for six hours
pauses and resumes on the next visit; the first collection after a pause catches
up from the warehouse's rows, starting no further back than the warehouse still
holds. The daily prune-demo-history task deletes demo projects' observed rows
older than DEMO_WAREHOUSE_RETENTION_DAYS, so tripl's own database stays
bounded however many demos a public instance creates. Real projects are
unaffected and keep their configured interval.
A reset re-seeds a demo from scratch, so DEMO_ENABLED=false blocks Create
and Reset alike. Deleting a demo stays available in every state of these
switches, so a workspace can never be stuck with a demo it cannot remove. Real
project create / scan / delete, and the real scan and metric schedulers, are
untouched by all of them.
Demo warehouse on managed PostgreSQL
By default python -m tripl.migrate creates the warehouse itself: the
<name>_demo database (it needs CREATEDB), the reader role named after it,
<warehouse database>_reader (it needs CREATEROLE), the warehouse schema and
the grants. Two steps need a superuser: the reader's temp_file_limit, and
taking from PUBLIC, in the demo database, pg_stat_activity and the functions
a role every visitor shares must not have (cancelling or terminating a backend,
reading other sessions, advisory locks, pg_sleep*, set_config, the
functions that run a query given as text, the large-object functions; the full
list is in The demo project).
Without one, migrate warns and goes on — a REVOKE without a superuser only
warns, so it checks afterwards what the reader can still use and names it —
and tripl's own SQL check still refuses those calls on a demo source. On a managed PostgreSQL where
tripl's role has neither CREATEDB nor CREATEROLE, migrate logs a warning
naming what is missing, still succeeds, and every demo runs on the in-memory
engine. To use the warehouse there, have an administrator run, as a role that
may:
-- 1. The database, owned by tripl's role (the writer). C collation, so text
-- sorts by code point.
CREATE DATABASE tripl_demo OWNER tripl
TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C';
-- 2. The reader, named after the database: logs in, owns nothing, read-only
-- by default, at most 10 connections of the server's shared max_connections.
CREATE ROLE tripl_demo_reader WITH LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE
NOREPLICATION NOINHERIT CONNECTION LIMIT 10 PASSWORD '<a long random password>';
ALTER ROLE tripl_demo_reader SET default_transaction_read_only = on;
ALTER ROLE tripl_demo_reader SET statement_timeout = '15s';
ALTER ROLE tripl_demo_reader SET idle_in_transaction_session_timeout = '30s';
ALTER ROLE tripl_demo_reader SET work_mem = '16MB';
ALTER ROLE tripl_demo_reader SET hash_mem_multiplier = 1;
ALTER ROLE tripl_demo_reader SET max_parallel_workers_per_gather = 0;
ALTER ROLE tripl_demo_reader SET search_path = warehouse;
-- Superuser only; skip it where none is available.
ALTER ROLE tripl_demo_reader SET temp_file_limit = '256MB';
-- 3. Connected to tripl_demo. PostgreSQL 14 and older let PUBLIC create in the
-- public schema, and tripl's role cannot take that back: the schema is not
-- its own.
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
-- 4. Still connected to tripl_demo, and only a superuser may: what the shared
-- reader must not use. Function privileges are per database, so tripl's own
-- database is untouched.
REVOKE SELECT ON pg_catalog.pg_stat_activity FROM PUBLIC;
DO $$
DECLARE f regprocedure;
BEGIN
FOR f IN
SELECT p.oid::regprocedure FROM pg_proc p
JOIN pg_namespace n ON n.oid = p.pronamespace
WHERE n.nspname = 'pg_catalog' AND p.proname ~ ('^(set_config|pg_cancel_backend'
'|pg_terminate_backend|pg_stat_get_activity|pg_stat_get_backend_.*'
'|pg_(try_)?advisory_.*|pg_sleep.*|pg_notify'
'|(query|cursor|table|schema|database)_to_xml.*|ts_stat|ts_rewrite'
'|lo_.*|loread|lowrite)$')
LOOP
EXECUTE format('REVOKE EXECUTE ON FUNCTION %s FROM PUBLIC', f);
END LOOP;
END $$;
Then set the reader's password and run migrate again:
DEMO_WAREHOUSE_READER_PASSWORD=<the reader's password>
# Only when the database has another name than <name>_demo, or lives on
# another server:
DEMO_WAREHOUSE_URL=postgresql://tripl:<password>@<host>:5432/tripl_demo?sslmode=require
With the password set, migrate leaves the role alone, and it never creates a
database that already exists. As the database's owner it creates the schemas and
the tables, takes CONNECT, TEMPORARY and every schema privilege away from
PUBLIC, and grants the reader CONNECT, USAGE on warehouse and SELECT on its
two tables — nothing else. The reader connects with the writer's host, port and sslmode.
Whatever migrate cannot do is a warning in its log naming the statement an
administrator should run, and a reader limit it could not set is reported by
GET /api/v1/platform/settings under system.demo_warehouse.reader_limits_missing:
temp_file_limit where no superuser was available, then every function (by
signature, such as set_config(text,text,boolean)) or view
(pg_catalog.pg_stat_activity) the reader can still use. The reader then runs
without that limit, on the server tripl shares; step 4 above takes the rest. Settings → Instance → System shows the
warehouse's engine, how far it is written and its size; In-memory engine there
carries the reason when demos are not using it.
See The demo project for what a demo contains, where its data comes from, and the calendar of incidents the warehouse runs.
Optional features
These groups are off (or unconfigured) by default. Several enable sending plan content or photos to external providers, so they are explicitly opt-in.
Hybrid knowledge search (embeddings)
Lexical/fuzzy search runs locally against PostgreSQL with no extra config. Embeddings are opt-in because indexed text may include internal tracking-plan content sent to the configured provider.
| Variable | Default | Purpose |
|---|---|---|
SEARCH_EMBEDDINGS_ENABLED | false | Enables embedding-backed search. |
SEARCH_EMBEDDING_PROVIDER | openai | Embedding provider. |
SEARCH_EMBEDDING_MODEL | text-embedding-3-small | Embedding model. |
SEARCH_EMBEDDING_DIMENSIONS | 1536 | Vector dimensions. |
SEARCH_EMBEDDING_API_KEY | "" | Provider API key; falls back to OPENAI_API_KEY if empty. |
SEARCH_EMBEDDING_BASE_URL | https://api.openai.com/v1 | Base URL of an OpenAI-compatible embeddings endpoint; /embeddings is appended. Point it at a self-hosted provider to keep plan text inside your own infrastructure. Env-only for the operator (an organization may set its own under Settings → Organization → Semantic search), and changing it after indexing needs a re-index — see AI and search. The resolved value is visible read-only under Settings → Platform → AI & search, with a source badge, so a value that never reached the container can be noticed from a browser instead of by diffing the compose file. |
OPENAI_API_KEY | "" | Shared OpenAI key used as fallback for search embeddings and AI features. |
AI features (LLM descriptions, Q&A)
Disabled by default because plan content (event names, descriptions, field names) is sent to the configured provider when enabled.
These are the operator's values; each organization may set its own under Settings → Organization → AI (see Operator and organization settings).
| Variable | Default | Purpose |
|---|---|---|
AI_ENABLED | false | Master toggle for LLM-powered features. |
AI_BASE_URL | https://api.openai.com/v1 | OpenAI-compatible base URL. |
AI_MODEL | gpt-4o-mini | Chat/completion model. |
AI_API_KEY | "" | Provider API key; falls back to OPENAI_API_KEY if empty. |
AI_TIMEOUT_SECONDS | 30 | Per-request timeout. |
AI_MAX_OUTPUT_TOKENS | 700 | Output token cap. |
Email alerts (SMTP)
Leaving SMTP_HOST blank disables email destinations: creating them still
works, but sends fail with a friendly error pointing at this config. The worker
reads these at send time, so changes take effect without re-creating
destinations.
These are the operator's relay: account mail (sign-up, password reset, invitations) always uses it, and organizations inherit it unless they set their own under Settings → Organization → Email.
| Variable | Default | Purpose |
|---|---|---|
SMTP_HOST | "" | SMTP server host. Blank disables email delivery. |
SMTP_PORT | 587 | SMTP port. Has to agree with SMTP_SECURITY. |
SMTP_USERNAME | "" | SMTP auth username. |
SMTP_PASSWORD | "" | SMTP auth password. |
SMTP_SECURITY | derived | starttls, implicit_tls or none. See below. |
SMTP_USE_TLS | true | Deprecated. Only supplies SMTP_SECURITY's default when that is unset. |
SMTP_FROM_ADDRESS | "" | Default From: address; may carry a display name (Tripl Alerts <no-reply@example.com>). Required for password-reset mail. Invalid values fail startup or the Settings save, before an alert is sent. |
SMTP_SECURITY names the transport, and the transport has to match the port:
| Value | What happens on the wire | Usual port |
|---|---|---|
starttls | Connects in the clear, reads the server greeting, then upgrades in place. | 587, 2525 |
implicit_tls | Wraps the socket in TLS before sending anything, so the greeting itself is encrypted (SMTPS). | 465 |
none | Plaintext for the whole session. Only reasonable for a relay on localhost or a network path you already trust. | 25 |
Getting this pair wrong does not fail fast. Pointing starttls at an
implicit-TLS port leaves the client waiting for a plaintext greeting that will
never arrive, so the send stalls for ten seconds and then reports a dropped
connection — which reads like a network problem rather than a configuration one.
When SMTP_SECURITY is unset it is derived from the deprecated SMTP_USE_TLS
(true → starttls, false → none), so an existing deployment keeps the
behaviour it already had. Set SMTP_SECURITY instead; it wins.
Settings → Platform → Mail relay (and an organization's Settings → Organization → Email) has a Send test email card that sends one message with the saved settings and shows what the relay answered. It stays disabled until an SMTP host and a default From address are saved, and it uses the saved settings, so save your changes first. Use it after changing any of these — a failed password-reset send is deliberately invisible to the person who asked for the link, so this is the only place the failure surfaces.
Event photo storage
| Variable | Default | Purpose |
|---|---|---|
PHOTO_STORAGE_BACKEND | local | local (filesystem, served via authenticated API endpoint) or gcs (Google Cloud Storage). |
PHOTO_LOCAL_DIR | ./var/photos | Directory for the local backend. In the shipped image this resolves to /app/var/photos, which is writable by the image's app user and mounted as the photos volume by compose.yaml; compose.yaml does not forward this variable, so the containers always use that mount. Point it elsewhere only at another mounted, writable volume, or uploads are lost when the container is recreated. |
PHOTO_MAX_SIZE_MB | 10 | Max upload size in MB, and the ceiling of every organization's own cap. A request to the photo routes whose body is larger than this plus 1 MiB of multipart framing is refused with 413 without being read past that limit (before any organization is known). |
MAX_REQUEST_BODY_MB | 2 | App-wide JSON/body limit in MiB. The photo upload route uses PHOTO_MAX_SIZE_MB plus multipart framing instead. Oversized requests return 413 before parsing or authentication. |
PHOTO_ALLOWED_MIME | image/jpeg,image/png,image/gif,image/webp | Allowed MIME types (comma-separated). An organization's own list may only narrow it. |
GCS_PHOTO_BUCKET | "" | GCS bucket for the gcs backend. |
GCS_PHOTO_CREDENTIALS_PATH | "" | Service-account JSON path. It names a file inside the container, so under Compose it needs a volume in a compose.override.yaml. Empty falls back to Application Default Credentials. Credentials that cannot sign URLs (Application Default Credentials on Compute Engine or workload identity, gcloud user credentials) make photos fall back to the authenticated /file endpoint instead of signed URLs. |
GCS_PHOTO_PUBLIC | false | Return public URLs instead of time-limited signed URLs. |
GCS_PHOTO_SIGNED_URL_TTL_SECONDS | 3600 | Signed-URL lifetime when not public. |
PHOTO_ORPHAN_SWEEP_GRACE_HOURS | 24 | Minimum age, in hours, of a photo file the daily orphan sweep may delete. See below. |
Orphan photo sweep. Deleting an event, an event type, a project or a plan
branch removes the photo rows attached to it but not their files. Every day at
05:30 UTC a Celery task deletes photo files that no photo row references any
more and that are older than PHOTO_ORPHAN_SWEEP_GRACE_HOURS. Newer files are
never touched, because an upload writes its file before it saves the row. When
no photo row at all references a backend, the sweep skips that backend and logs
a warning instead of deleting: that is what an empty or half-restored database
looks like, not a directory of orphans. Only the prefixes tripl writes are
listed — events/ (uploads before per-organization storage) and
orgs/{organization id}/events/ for each organization that exists — so other
files in the directory or bucket are left alone. The sweep covers the local
backend and, when GCS_PHOTO_BUCKET is set, the gcs backend, including rows
written before a backend switch; and each organization's own bucket, with the
organization's own key and under its own prefix only. A file any photo row
names is kept, in any store. It
runs on celery-worker, which therefore mounts the same photos volume as
app. A worker without that mount sees an empty directory and deletes nothing.
Switching PHOTO_STORAGE_BACKEND does not move anything. Every photo row
records the backend its file was written to, and that is the backend it is read
and deleted through from then on — so photos taken before a switch keep working,
as long as the old backend stays configured. Leave PHOTO_LOCAL_DIR pointing at
the same volume when moving to gcs, and leave GCS_PHOTO_BUCKET set when
moving back to local; new uploads follow the new setting either way. Take the
old backend away and only its photos are affected: they answer 409 naming it,
the rest of the page loads, and nothing is deleted. There is no migration
command — copy the objects across yourself before retiring a backend.
Warehouse query row caps
| Variable | Default | Purpose |
|---|---|---|
SCAN_ROW_LIMIT_DEFAULT | 50000 | Default row cap for scan/replay when no scan-config override is set. |
METRICS_ROW_LIMIT_DEFAULT | 100000 | Default row cap for metrics queries when no override is set. |
An organization may lower either cap for its own scans under Settings → Organization → Limits; these values are its ceiling.
Operational history retention
The daily maintenance task prunes old completed scan jobs and distribution
drift records in every project. Scan-job age starts at completed_at, so a
long-running job retains its full configured history after it finishes. Active
scan jobs remain available. Distribution drift in the stable or minor band
has a shorter horizon than significant drift; set the shorter horizon no higher
than the general one.
The same task deletes scan previews and dry runs, the answers the scan form
asks the worker for and reads once (a preview, a JSON key discovery, a dry
run, and the same jobs started through the API). They go after
SCAN_PREVIEW_RETENTION_DAYS, measured from completion. A preview or dry run
still unfinished after that long is one whose worker died, and it goes too.
| Variable | Default | Purpose |
|---|---|---|
SCAN_JOB_RETENTION_DAYS | 90 | Age limit for completed scan jobs, measured from completed_at. |
DISTRIBUTION_DRIFT_RETENTION_DAYS | 90 | Age limit for significant distribution drift. |
DISTRIBUTION_DRIFT_MINOR_RETENTION_DAYS | 30 | Age limit for stable and minor distribution drift. |
SCAN_PREVIEW_RETENTION_DAYS | 7 | Age limit for scan previews and dry runs, measured from completed_at. |
Production startup checks (assert_production_ready)
When DEBUG=false, the FastAPI lifespan refuses to start and raises a
RuntimeError listing every problem if any of the following hold:
ENCRYPTION_KEYis empty — data-source and alert-destination secrets would be stored as plaintext.ENCRYPTION_KEYis not a valid Fernet key — it is validated by constructingFernet(key).SESSION_COOKIE_SECUREis false — session cookies would be sent over plain HTTP.SECRET_KEYis empty — session-token hashes would be unkeyed and guessable.- Resolved CORS origins are empty — no browser could call the API. Set
CORS_ALLOW_ORIGINSorAPP_BASE_URL. - Resolved CORS origins are exactly
["*"]— browsers reject credentialed (cookie) requests against a wildcard origin, breaking session auth. Set an explicit origin. DATABASE_URL,SYNC_DATABASE_URL, orRABBITMQ_URLstill contain dev-default credentials — any of the markerstripl:triplorguest:guestsurviving into a non-debug deploy fails the check.
These checks are pure secret/edge hygiene. Optional-feature variables (AI, search, SMTP, photo storage, OTEL, Prometheus) are not validated here — they fail gracefully or stay disabled when unconfigured.
Compose / deployment variables
These are consumed by Docker Compose and the image, not by the backend
Settings object. They appear in
.env.example so
one .env covers the whole stack.
| Variable | Default | Used by | Purpose |
|---|---|---|---|
POSTGRES_PASSWORD | — (required) | Compose | Builds the DB URLs. The prod stack requires a non-default value. |
RABBITMQ_PASSWORD | — (required) | Compose | Builds RABBITMQ_URL; broker user is tripl. |
TRIPL_IMAGE | ghcr.io/tripl-io/tripl | Compose | Published image to run. |
TRIPL_VERSION | latest | Compose | Image tag — pin to a released tag in production. |
Both stacks name the database user and the database tripl; neither is a
setting.
In compose.yaml, POSTGRES_PASSWORD, RABBITMQ_PASSWORD, ENCRYPTION_KEY,
SECRET_KEY, and APP_BASE_URL use the ${VAR:?...} form, so docker compose
fails fast with a clear message if any is unset — before the app even runs its
own assert_production_ready() checks.
See also
- Deployment — bringing the stack up with the production compose file.
- Release process — building and publishing the image with
bin/release.sh. - Administration — day-2 operations.
- Troubleshooting — diagnosing common failures.
- Source of truth:
config.py,.env.example,compose.yaml.