Configuration

Peperossa is configured by environment variables only; nothing secret is built into the image. With the Compose file, set them in .env (install). A value that can’t be read (a tier list that isn’t JSON, a worker tier that isn’t configured) stops the service at start, saying why.

Every service

The api, worker and editor services.

Variable	Default	Meaning
PORT	4179 for api, 4180 for worker, 4178 for editor	The port to listen on
PEPEROSSA_BIND	0.0.0.0 in the image	The address to listen on
PEPEROSSA_HOSTS	none: localhost and 127.0.0.1 only	More host names to answer to, comma-separated: name:port on that port only, or a name alone, answered on the service’s port and with no port, as an HTTPS proxy on the standard port sends it
PEPEROSSA_LOG	all	all, errors or off (troubleshooting)

API and workers

Variable	Default	Meaning
PEPEROSSA_DATABASE_URL	none	PostgreSQL, as postgres://user:password@host:5432/database (storage)
PEPEROSSA_STORAGE	disk	Where files are kept: disk is the only kind for now
PEPEROSSA_STORAGE_DIR	/data in the image	The folder files are kept in, shared by the API and every worker
PEPEROSSA_WORKERS	1 (2 in the Compose file)	The API’s render threads for synchronous renders, and how many jobs a worker renders at once unless PEPEROSSA_WORKER_CONCURRENCY says
PEPEROSSA_SIGNING_KEYS	none: signed links off	Keys for signed download links, comma-separated: the first signs, every one verifies
PEPEROSSA_TIERS	one tier, standard, no limits	The service tiers, as JSON (scheduler)
PEPEROSSA_WEBHOOK_ALLOW_PRIVATE	false	true lets webhooks reach private addresses and plain http:// (security)
PEPEROSSA_METERING	on	on or off (metering)

API

Variable	Default	Meaning
PEPEROSSA_ADMIN_TOKEN	none: admin API off	The admin API’s tokens, comma-separated (tenants)
PEPEROSSA_SYNC_TIMEOUT_MS	30000	How long a synchronous render may take before it is answered 504

Workers

Variable	Default	Meaning
PEPEROSSA_WORKER_CONCURRENCY	PEPEROSSA_WORKERS	How many jobs one worker renders at once
PEPEROSSA_WORKER_TIERS	none: every tier	The tiers whose work this worker claims, comma-separated (reserved capacity)
PEPEROSSA_JOB_TIMEOUT_MS	600000 (10 minutes)	How long one job may render
PEPEROSSA_JOB_LEASE_MS	60000 (a minute)	How long a worker holds a job between renewals: a job whose worker stopped is taken up again after this

Limits

Variable	Default	Meaning
PEPEROSSA_MAX_PACKAGE_MB	100	The largest template package
PEPEROSSA_MAX_EXPANDED_MB	250	The largest template package, unpacked
PEPEROSSA_MAX_IMAGE_MEGAPIXELS	40	The largest image, in millions of pixels
PEPEROSSA_MAX_QUEUED_JOBS	1000	The most jobs one tenant may have queued or running
PEPEROSSA_MAX_BATCH_RECORDS	10000	The most records in one batch
PEPEROSSA_MAX_OPEN_BATCHES	10	The most batches one tenant may have unfinished
PEPEROSSA_MAX_MERGED_RECORDS	1000	The most records merged into one PDF
PEPEROSSA_MAX_COMBINED_MB	1000	The largest combined output of a batch

Retention

Variable	Default	Meaning
PEPEROSSA_OUTPUT_RETENTION_HOURS	24	How long rendered files are kept
PEPEROSSA_JOB_RETENTION_DAYS	7	How long finished jobs, batches and webhook deliveries are kept
PEPEROSSA_USAGE_KEEP_DAYS	400	How long usage events and storage measures are kept

Editor

Variable	Default	Meaning
PEPEROSSA_API	http://127.0.0.1:4179	The API the editor forwards /v1 requests to
PEPEROSSA_EDITOR_KEY	none	The API key the editor forwards with
PEPEROSSA_EDITOR_KEY_FILE	none	A file holding that key, read when PEPEROSSA_EDITOR_KEY isn’t set (the Compose file’s way)

Authoring MCP

The authoring MCP server reads two, to publish what it makes:

Variable	Default	Meaning
PEPEROSSA_URL	none	The API’s address
PEPEROSSA_KEY	none	An API key with the render and publish scopes

The Compose file

Read by compose.yaml itself, in .env:

Variable	Default	Meaning
PEPEROSSA_IMAGE	peperossa:local	The Peperossa image every service runs
POSTGRES_USER	none	The database’s user, made when the db volume is first created
POSTGRES_PASSWORD	none	Its password
POSTGRES_DB	none	The database’s name
PEPEROSSA_API_PORT	4179	The port on this machine the API is published on
PEPEROSSA_EDITOR_PORT	4178	The port on this machine the editor is published on
PEPEROSSA_EDITOR_HOSTS	none	More host names the editor answers to, comma-separated
PEPEROSSA_API_HOSTS	none	More host names the API answers to, comma-separated

Development

Variable	Default	Meaning
PEPEROSSA_PGLITE_DIR	apps/server/data/db	Without PEPEROSSA_DATABASE_URL, the server keeps its database in this folder with an embedded PostgreSQL (memory://: in memory). Not for production