Skip to content

Configuration

FastProof is configured with environment variables. Secrets can be given as files (*_FILE variables), which is how the Helm chart passes them. A wrong or missing setting stops the server at start with an error that names the variable.

Listeners

Variable Default Meaning
FASTPROOF_LISTEN 0.0.0.0:8080 Main listener: UI at /, API at /api/v1, sign-in at /auth/*, OpenAPI at /api/openapi.json, Swagger UI at /api/docs, GET /healthz
FASTPROOF_OPS_LISTEN 0.0.0.0:9090 Operations listener: /metrics (Prometheus), /healthz (process alive), /readyz (database reachable, migrations at the expected version, blob store reachable)
FASTPROOF_PUBLIC_URL none External base URL, for example https://fastproof.example.com. Required with OIDC
FASTPROOF_TLS_CERT_FILE, FASTPROOF_TLS_KEY_FILE none Serve TLS on the main listener (PEM files)
FASTPROOF_TLS_CLIENT_CA_FILE none Require client certificates signed by this CA on the main listener
FASTPROOF_UI on Serve the embedded web UI (off leaves the API only)

Keep the operations port internal: it is unauthenticated by design. Expose only port 8080.

Database

Variable Default Meaning
FASTPROOF_DATABASE_URL required PostgreSQL URL, for example postgres://fastproof:secret@db.example.com:5432/fastproof?sslmode=verify-full
FASTPROOF_DATABASE_URL_FILE none File holding the URL, instead of FASTPROOF_DATABASE_URL
FASTPROOF_DATABASE_CA_FILE none CA bundle to verify the PostgreSQL server certificate
FASTPROOF_DATABASE_MAX_CONNECTIONS 20 Connection pool size per replica
FASTPROOF_MIGRATE auto auto applies migrations at start under an advisory lock; off expects them applied by fastproof migrate (the Helm chart runs it as a Job)

PostgreSQL 14 to 18 is supported; 18 is recommended. PostgreSQL 14 reached end of life in November 2026.

Attachment storage

Variable Default Meaning
FASTPROOF_BLOB_BACKEND fs fs (a directory) or s3
FASTPROOF_BLOB_DIR /var/lib/fastproof/blobs Directory for fs. Several replicas need a shared (ReadWriteMany) volume
FASTPROOF_S3_ENDPOINT none S3-compatible endpoint, for example https://s3.example.com
FASTPROOF_S3_REGION us-east-1 Signing region; must match the server's region (Garage defaults to garage)
FASTPROOF_S3_BUCKET none Bucket name
FASTPROOF_S3_ACCESS_KEY_FILE, FASTPROOF_S3_SECRET_KEY_FILE none Credentials from files
FASTPROOF_S3_ACCESS_KEY, FASTPROOF_S3_SECRET_KEY none Credentials inline, for local use
FASTPROOF_S3_CA_FILE none Custom CA for the S3 endpoint
FASTPROOF_S3_PATH_STYLE true Path-style addressing (https://s3.example.com/bucket/key)

Attachments are content-addressed by SHA-256 and stored once per project.

Ingest

Variable Default Meaning
FASTPROOF_SPOOL_DIR /tmp/fastproof Temporary files of uploads being received and processed (an emptyDir in Kubernetes)
FASTPROOF_MAX_UPLOAD_BYTES 1073741824 (1 GiB) Largest upload request
FASTPROOF_INGEST_WORKERS 2 Uploads processed at the same time per replica
FASTPROOF_RETAIN_UPLOADS false Keep the raw uploaded files in blob storage after processing (for re-parsing)
FASTPROOF_OUTBOX_RETENTION_DAYS 7 Days that ingest events stay in the PostgreSQL outbox for optional consumers

Give the spool directory room for FASTPROOF_INGEST_WORKERS uploads plus the ones being received. The other ingest limits are listed on Limits.

Access

Variable Default Meaning
FASTPROOF_ADMIN_TOKENS_FILE none Static tokens for bootstrap, one per line: name:role:sha256:<hex>
FASTPROOF_ACCESS_FILE none YAML file with custom roles and bindings of users, OIDC groups and tokens

At least static tokens or OIDC must be configured. See Security for roles, permissions and the access file.

OIDC sign-in

OIDC is off until FASTPROOF_OIDC_ISSUER is set; then the other variables apply.

Variable Default Meaning
FASTPROOF_OIDC_ISSUER off Issuer URL, compared with iss byte for byte
FASTPROOF_OIDC_CLIENT_ID required Client id; the audience of ID tokens
FASTPROOF_OIDC_CLIENT_SECRET_FILE File with the client secret (or FASTPROOF_OIDC_CLIENT_SECRET inline)
FASTPROOF_OIDC_REDIRECT_URL required <public URL>/auth/callback
FASTPROOF_OIDC_SCOPES openid profile email Requested scopes; must include openid
FASTPROOF_OIDC_USERNAME_CLAIM preferred_username Claim (or dotted path) with the user name
FASTPROOF_OIDC_GROUPS_CLAIM groups Claim (or dotted path such as realm_access.roles) with the groups
FASTPROOF_OIDC_ALLOWED_ALGS RS256,PS256,ES256,EdDSA Accepted signature algorithms
FASTPROOF_OIDC_API_AUDIENCE off Audience of bearer JWTs accepted on the API; must differ from the client id
FASTPROOF_OIDC_CA_FILE none Extra CA bundle for the provider
FASTPROOF_OIDC_SESSION_TTL 8h Absolute session lifetime (30m, 8h, 1d)
FASTPROOF_OIDC_SESSION_IDLE 1h Session idle timeout
FASTPROOF_OIDC_ALLOWED_HOSTS none Hosts besides the issuer's that discovery may point to
FASTPROOF_OIDC_COOKIE_NAME franshub Base name of the session cookies
FASTPROOF_OIDC_INSECURE_COOKIE false Cookies without Secure; only for a loopback redirect URL in development
FASTPROOF_OIDC_POST_LOGOUT_REDIRECT public URL Where the provider sends the browser after logout

Live updates

Variable Default Meaning
FASTPROOF_VALKEY_URL none Optional Valkey (or Redis 7.4) URL for live-update fan-out between replicas, for example redis://default:secret@valkey:6379/0. Without it PostgreSQL LISTEN/NOTIFY is used

Logs and telemetry

Variable Default Meaning
FASTPROOF_LOG_FORMAT json json or text
RUST_LOG info Log filter, for example info,fastproof=debug
OTEL_EXPORTER_OTLP_ENDPOINT none Send traces over OTLP; the standard OTEL_EXPORTER_OTLP_* and OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES variables apply

Secrets never appear in logs; tokens and passwords in URLs and headers are redacted.

CLI

The same binary is the CLI (fastproof upload, watch, launch start, launch finish, migrate, version). The CLI reads:

Variable Meaning
FASTPROOF_URL Server URL
FASTPROOF_TOKEN API token
FASTPROOF_PROJECT Project key
FASTPROOF_LAUNCH External launch id; uploads with the same id join one launch

fastproof migrate uses the database variables above and exits when the schema is up to date.