Configuration

Environment variables only, documented line by line in .env.example.

Database pool sizeCopy Anchor Link

Each process opens one Postgres pool. The compose file sets pool_max_conns=20 (all roles in one process). Set it in the URL form of OHS_DATABASE_URL (postgres://...?pool_max_conns=20): the keyword/value form (host=db pool_max_conns=20) is not supported for it, because the migrations and ohs doctor drop the pool_ parameters from the URL form only. Elsewhere, without a setting pgx sizes it to the number of CPUs (at least 4), which is too small once several roles share it: the ETL alone runs 4 jobs per tier on two tiers, and the uploads, pulls, deletion worker and background jobs each hold a connection while they work. Set the size with pool_max_conns in the URL:

OHS_DATABASE_URL=postgres://ohs:secret@db:5432/ohs?sslmode=disable&pool_max_conns=20

Keep the sum over all processes under Postgres max_connections (100 by default, 30 in the Pi overlay), with a few to spare for psql and migrations.

Provider keys in every roleCopy Anchor Link

The collect role pulls and subscribes; the etl role carries out user deletions, which revoke grants and unsubscribe notifications at the provider. Give the provider keys to every process that runs either role. A process without them cannot call that provider: it logs a warning, and a deletion it carries out still deletes the data but leaves the grant valid at the provider.

Put a reverse proxy with TLS in front of port 8080; the bearer secrets travel in headers. hardening.md is the full production checklist, and security-model.md the threat model behind it.

Rate limitsCopy Anchor Link

The provider-facing routes take no credential: POST and GET /inbound/{provider} (notifications and the URL check) and GET /oauth/{provider}/callback. Neither does POST /v1/setup (the first-run setup), which checks a token. Each notification may verify a signature, write rows and queue pulls, and each callback reads the database, so an in-memory token bucket bounds them, per api process. A request over a limit is answered 429 with Retry-After (seconds) before any work, and counted in /metrics as ohs_rate_limited_total{route_group="inbound"}, {route_group="oauth_callback"} or {route_group="setup"}. The authenticated API is not limited.

The values are rate/burst (30/120; the rate may be a decimal, 0.5/10), and 0 turns a bucket off. The defaults sit well above what a provider sends, batched notifications and a large backfill included; providers retry a 429. The per provider bucket keeps a flood from many spoofed addresses from queueing unlimited work. An IPv6 client is counted by its /64. Buckets idle for 10 minutes are dropped, and at most 100,000 addresses are tracked per route group: beyond that, new addresses share one bucket until idle ones are dropped.

The client address is the TCP peer. Behind a reverse proxy every request comes from the proxy, so list the proxy in OHS_TRUSTED_PROXIES: for a request from one of those addresses, the client is the rightmost X-Forwarded-For entry that is not itself a trusted proxy. The header is ignored from any other peer, so a client cannot pick its own address. With the bundled compose file and a proxy on the host in front of the published port 8080, requests reach the container from the Docker bridge gateway. Make sure the proxy appends the address it received the request from to X-Forwarded-For (most do by default), then trust the bridge networks:

# .env
OHS_TRUSTED_PROXIES=172.16.0.0/12

Name only addresses your proxies use: a trusted range that also holds clients lets them forge the header. Several api processes each keep their own buckets, so the limits add up across them.