Self-hosting Configuration

Critical Secret#

PROVON_AUTH_SECRET is required in production. On Node, PROVON_AUTH_SECRET is an equivalent fallback read only when PROVON_AUTH_SECRET is unset; Cloudflare Workers bind PROVON_AUTH_SECRET directly, so set it on every Worker that reads sessions or encrypted credentials.

This value signs authentication state and sessions and derives the key material that encrypts stored OAuth tokens, provider credentials, and Connector secrets. It must be identical across runtimes that read the same metadata store.

Generate at least 32 random bytes:

openssl rand -base64 32

Public Origin And HTTP#

Same-origin Node example:

PROVON_AUTH_ORIGIN=https://provon.example.com
PROVON_WORKBENCH_ORIGINS=https://provon.example.com
PROVON_TRUST_PROXY_HEADERS=true
PROVON_AUTH_TRUST_HOST=true

Split Cloudflare origins:

PROVON_AUTH_ORIGIN=https://api.provon.example
PROVON_WORKBENCH_ORIGINS=https://app.provon.example
PROVON_AUTH_COOKIE_DOMAIN=.provon.example
PROVON_AUTH_TRUST_HOST=true

Only trust forwarded hosts when the ingress removes client-supplied forwarding headers and writes its own values. Forwarded origins that do not exactly match PROVON_AUTH_ORIGIN are ignored.

Node Storage#

Metadata, usage events, jobs, and Gateway state must use distinct database URLs; sharing one file between them reunites the writers each database exists to separate. The directory holding PROVON_BLOBS_DIR also holds persistent Node runtime state: mount and back up the parent data directory, not only the visible blob files.

Cloudflare Telemetry#

Default read-model variables in the checked-in templates:

PROVON_TELEMETRY_QUERY_SOURCE = "summaries"
PROVON_TELEMETRY_PAYLOAD_RETENTION = "all"

• PROVON_TELEMETRY_QUERY_SOURCE: summaries (default) reads trace summaries; append-only-spans reads raw spans. summaries requires the PROVON_TELEMETRY_SUMMARY_QUEUE binding on writer deployments.
• PROVON_TELEMETRY_PAYLOAD_RETENTION: all (default) keeps raw payload fields; projected-only drops raw payload fields at the telemetry write boundary. Choose projected-only only when projected evidence is sufficient for investigation and diagnosis.

Use the checked-in wrangler.*.example.toml files as the binding contract; do not rename a binding without changing the corresponding runtime code.

OTLP And Background Work#

Defaults suit development and moderate workloads. Tune only from measured body sizes, queue lag, write latency, and dependency limits.

Additional Node background controls:

Gateway usage reservation reconciliation runs only on the Node loop:

Setting an interval to 0 disables a loop only where the implementation accepts a non-negative interval. Disabling a loop is an architecture change: assign its responsibility to another runtime before doing so.

Data Retention#

Project retention policy selects what expires. Runtime variables control the Node maintenance job:

On Cloudflare, retention runs inside the Maintenance Worker cron (0 */6 * * *) alongside metadata maintenance and work-item sync. R2 lifecycle rules, snapshot expiration, and compaction are separate platform controls configured with the telemetry-maintenance script; see Operations.

Sign-in Providers#

Email and password sign-in remains available when no social provider is configured. A social provider is enabled only when both its client ID and client secret are present.

Register:

https://<api-origin>/auth/callback/github
https://<api-origin>/auth/callback/google
https://<api-origin>/auth/callback/apple

Google and GitHub identities require verified provider email claims. Link another identity from an authenticated Account settings → Sign-in methods page; anonymous email-based account linking is not supported.

Enterprise OIDC#

Required:

• AUTH_OIDC_CLIENT_ID
• AUTH_OIDC_CLIENT_SECRET
• AUTH_OIDC_ISSUER or AUTH_OIDC_WELL_KNOWN

Optional controls include AUTH_OIDC_NAME, AUTH_OIDC_SCOPE, AUTH_OIDC_TOKEN_ENDPOINT_AUTH_METHOD, AUTH_OIDC_ALLOW_ACCOUNT_LINKING, and AUTH_OIDC_EMAIL_TRUST_POLICY. The default email trust policy requires email_verified=true; use trusted_provider only when the IdP contract guarantees email ownership. The callback provider ID is enterprise-oidc:

https://<api-origin>/auth/callback/enterprise-oidc

Connector OAuth#

Login OAuth and Connector OAuth are separate applications. Connector credentials use the *_INTEGRATION_* prefix.

Register:

https://<api-origin>/v1/integrations/github/callback
https://<api-origin>/v1/integrations/gitlab/callback
https://<api-origin>/v1/integrations/jira/callback
https://<api-origin>/v1/integrations/linear/callback

See Connectors for project setup and default scopes.

Configuration Review#