Configuration reference

auth (data plane) and central (control plane) each read one HOCON file at startup and a handful of environment variables. This page lists both, block by block, and says which blocks a production deployment needs. edge has its own block list; see Edge configuration.

You normally do not write these files by hand. versola configure (and the Helm chart) generate them with versola-tools for the release you deploy, with secrets as ${VAR} placeholders. They are regenerated on every configure, so on the vps target a hand edit is lost; there is no supported way yet to change an individual setting there. Treat this page as a reference for what the generated files contain.

How configuration is loaded

• The service reads the HOCON file at the path in CONFIG_PATH (container default /app/config/env.conf; the image passes it to the JVM as -Denv.path). As an alternative, the whole configuration can be passed inline in the ENV_CONFIG environment variable.
• Keys are written in kebab-case (maximum-pool-size). Durations are HOCON durations ("60 seconds", 5 minutes).
• Standard HOCON substitution applies, so ${VAR} and ${?VAR} take values from environment variables. The generated files use this for secrets: versola configure resolves each secret from OpenBao into a <service>.secrets.env file that Compose passes to the container as environment, and the configuration file only holds the placeholder. On Kubernetes the same keys come from a Secret (Kubernetes).
• A syntax error stops the service at startup. HOCON cannot read UTF-16: keep hand-edited files UTF-8.
• env must be set. The value prod marks production; any other value is treated as a test environment. Production is stricter in places noted below (for example, Postgres TLS).

Environment variables

The generated configuration also reads a few variables the chart or Compose file sets for you (for example the certificate issuer on Kubernetes). Anything else, including secrets, lives in the HOCON file and the secret store.

Blocks shared by every service

Top level

postgres

Every key except notifications-url, ssl-root-cert and pool-metrics-interval is required and has no default, so that the connection budget of all instances can be planned against Postgres max_connections. The values below are what versola-tools generates.

Postgres TLS

Every connection to Postgres is opened with sslmode=verify-full unless the URL sets its own sslmode: the certificate must chain to a trusted CA and match the host name. This applies to the pool and to the notifications-url connection.

• To trust a private CA, mount its bundle into the container and set ssl-root-cert; on the vps target pass --postgres-ca <file> to versola configure and the CLI does both. A sslrootcert already in the URL wins.
• A URL that does not verify (sslmode=disable, allow, prefer or require, or ssl=false) logs a warning at startup. With env = "prod" the service refuses to start.
• Hosts localhost, 127.0.0.1 and [::1] are exempt from both. versola-tools writes sslmode=disable for the bundled local Postgres and for a vps whose --postgres-host is loopback; a remote vps host keeps the verified default.
• An sslfactory in the URL that may skip validation is reported the same way.

Behind a connection pooler

central and edge hold a connection parked on LISTEN: that is how a configuration change reaches every replica and how a revoked token stops being accepted before it expires. A pooler in transaction mode cannot carry LISTEN. When url points at a pooler, set notifications-url to a direct Postgres URL:

postgres {
  url               = "jdbc:postgresql://pgbouncer:6432/auth?currentSchema=edge"
  notifications-url = "jdbc:postgresql://postgres:5432/auth?currentSchema=edge"
}

A service checks at startup that it can receive its own notification and refuses to start, naming this setting, if it cannot.

auth

Required in production: env, configuration-cache-refresh-interval, security, jwt, central, postgres. Optional: bootstrap, par, dpop, argon2, mutual-tls, otp-provider, smtp, cleanup. The generated file includes bootstrap, par, argon2, mutual-tls and cleanup.

security

Eleven secrets, all required. Each is a base64url value; the generated placeholders and the decoded length are:

Some of these protect stored data and must never be regenerated; see Secrets.

jwt

central

par

Optional. Pushed authorization requests (RFC 9126).

dpop

Optional. Defaults apply when the block is absent.

Whether a nonce is required is a per-tenant setting in the admin console, not configuration. See Sender-constrained tokens.

mutual-tls

Optional. Starts a second listener on MPORT that requires a client certificate and serves /token, /introspect, /revoke, /par and /userinfo, and makes discovery advertise mtls_endpoint_aliases (RFC 8705 §5). Without the block, a client certificate reaches auth only as a header forwarded by a tenant’s proxy.

The vps and Kubernetes targets generate this block and the certificates behind it (a step-ca based mtls-init service, or cert-manager). See Edge client certificates.

argon2

Optional. Argon2id password hashing.

otp-provider

Optional, commented out in the generated file. An HTTP endpoint that delivers OTP codes (SMS, for example).

smtp

Optional, commented out in the generated file. Used for e-mail OTP and password delivery.

Without SMTP or an OTP provider, a production deployment has no channel to deliver a temporary password; in prod a password can only be delivered, not shown on screen.

bootstrap

Optional. On a first start, creates the admin user.

cleanup

Periodic deletion of expired rows. The generated file lists these tables with their batch size and interval:

A failed batch no longer stops cleanup of that table until the next restart (fixed in 0.7.0). The service publishes cleanup_* metrics so you can see whether removal keeps up; see Observability.

central

Required in production: env, configuration-cache-refresh-interval, secret-key, client-secrets-secret, auth, user-outbox, postgres. Optional: bootstrap, client-certificates, client-certificate-authority.

bootstrap

Optional in the code; the generated file always includes it. It seeds central’s database once, on the first start against an empty database. Changing it later has no effect: edit the objects in the admin console instead.

client-certificates

Optional. How central issues and renews certificates for edge-fronted clients. central holds no CA key in this mode. Exactly one backend is configured; the block is read as absent unless a backend is named.

client-certificate-authority

Optional, local development only: central holds the CA key itself. certificate and private-key are PEM paths (key unencrypted PKCS#8); validity-days optionally caps the lifetime. Without it, a registration that asks central to issue a certificate is refused. Prefer client-certificates anywhere else.

Startup order

auth and edge sync their configuration from central while they start. If central is not listening yet, they wait up to two minutes. The wait recovers by itself only with HTTP_CLIENT_POOL_KIND=dynamic. With the default fixed pool the first request opens all of the pool’s connections, central refuses them, and the pool keeps a failed connection per slot (128 by default), so each retry consumes one and the wait cannot succeed even after central is up. The service exits with code 1 after the two minutes and relies on the restart policy (restart: unless-stopped in the Compose bundles, restartPolicy: Always in Kubernetes); the restarted process builds a fresh pool and starts normally. Expect one restart on a cold install where central is not first. versola up starts central first, so it avoids this. While waiting, /liveness answers 200 and /readiness answers 503. A central that answers and rejects the request (wrong URL, wrong key) fails startup within seconds.

Outbound HTTP client pool

auth, central and edge share one outbound HTTP client: calls between the services and edge’s calls to the backends it proxies. Its pool is kept per target (scheme, host and port), so each backend gets its own pool of the configured size. The resolved pool is logged once at startup (outbound HTTP client pool: ...).

An HTTP/1.1 connection serves one request at a time, so a pool caps a pod’s throughput towards one backend at roughly size / backend latency. Neither kind fails when exhausted: a request waits for a free connection with no timeout of its own, so a pool that is too small shows up as latency, never as errors. http_client_active_requests counts outbound requests in flight, queued ones included, and rises first. Size the pool for peak requests per second per pod times the backend’s p99 latency, with headroom. A fixed pool of 128 opens 128 connections to every backend a pod touches; with many backends dynamic with a low MIN uses fewer sockets, at the cost of a connection set-up when a burst arrives.

Login state tables are UNLOGGED

This is one of Versola’s deliberate trade-offs; see Compromises for the full list of UNLOGGED tables, what a crash costs and how to turn logging back on.

Since 0.7.0, the auth_conversations, authorization_codes and pushed_authorization_requests tables are UNLOGGED: they are not written to the write-ahead log. They hold only minutes-old login state, and logging them made the database wait on WAL commits. The trade-off:

• A clean Postgres restart keeps their rows.
• A Postgres crash (kill -9, host failure, power loss) empties them. A standby never receives them, so after a failover they are empty, and a restore from a backup brings them back empty.
• What is lost is in-flight state only: users in the middle of a multi-step sign-in start over, and an authorization code or pushed request that was not yet used is rejected, so the client retries. Sessions, tokens, consents and users are unaffected.
• The migration runs ALTER TABLE ... SET UNLOGGED, which takes an exclusive lock and rewrites each table. The tables are small, but run versola migrate at low traffic: logins on a still-running older version wait while it runs.

Refresh token lifetime

The lifetime of a refresh token is fixed when it is issued and no longer slides with use (since 0.7.0). It is not a configuration-file setting: it is the refreshTokenTtl of each client, in seconds, set when the client is registered through the Central API or the admin console. When omitted, the default is 15552000 (180 days); releases before 0.7.0 used 90 days and extended it on every use.

Security headers

All application listeners of auth, central and edge (main, additional, mutual-TLS; not the diagnostics port) add these response headers unless the handler already set them:

There is no default-src Content-Security-Policy or form-action: they would break tenant logos and fonts and redirects to a client’s redirect_uri. Your own TLS-terminating proxy must forward X-Forwarded-Proto for HSTS to be emitted, and includeSubDomains assumes every host under the domain is https-only.

JVM defaults

The auth, central and edge images set JAVA_OPTS to a fixed-size profile on Temurin 25, so memory use does not depend on how much the host has:

-XX:+UseG1GC -Xms512m -Xmx512m -XX:MaxDirectMemorySize=64m -XX:MaxMetaspaceSize=128m
-XX:ReservedCodeCacheSize=64m -Xss512k -XX:NativeMemoryTracking=summary
-XX:+UseCompactObjectHeaders -XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/diagnostics/heap.hprof -XX:+ExitOnOutOfMemoryError
-Xlog:gc*:file=/diagnostics/gc.log:time,uptime,level,tags:filecount=5,filesize=20M
--enable-native-access=ALL-UNNAMED

edge sets MaxDirectMemorySize=96m; auth and central use 64m. The heap is 512 MiB, fixed (-Xms equals -Xmx). Budget about 850 MiB of resident memory per service, which is what the chart’s 1 GiB memory limit is sized from. On an OutOfMemoryError the JVM writes one heap dump (overwritten on each crash), exits so the supervisor restarts it, and leaves a rotated GC log in /diagnostics; both deployments mount a volume there. See Observability.

Setting JAVA_OPTS replaces the whole string, so repeat any flag you still want. The older -XX:MaxRAMPercentage=75.0 default is gone: on the vps target nothing limits container memory, so a percentage would be taken from the whole server for each of three JVMs.

Next steps

• Secrets: what each secret protects and how to rotate it.
• Observability: health endpoints, metrics, logs and diagnostics.
• Edge configuration: the same reference for edge.