Environment variables

Every variable below is read by the backend’s configuration (backend/src/main/resources/application.yml) or by docker-compose.yml. This page is verified against that source — if you find a variable documented elsewhere that isn’t listed here, trust this list.

Core

Variable	Default	Purpose
MONGODB_URI	mongodb://localhost:27017/forms_engine	MongoDB connection string. Indexes are auto-created at startup.
PORT	8080	HTTP listen port. Note: the Docker image always EXPOSEs 8080.
PHOTON_BASE_URL	https://photon.komoot.io	Base URL of the Photon geocoder for address autocomplete. See Geocoding.

File storage

Variable	Default	Purpose
STORAGE_MODE	filesystem (bare runs); the compose stack sets s3	filesystem or s3. Anything else fails startup loudly.
FS_STORAGE_PATH	./data/uploads	Filesystem mode: the storage root. Created if absent; startup fails if it can’t be created or isn’t writable.
S3_ENDPOINT	(empty)	S3 mode: endpoint override for MinIO/R2/B2/etc. Leave empty for real AWS (the SDK derives it from the region).
S3_BUCKET	forms-engine-uploads	Bucket name. Must already exist — the backend never creates it (the compose stack’s minio-init does).
S3_ACCESS_KEY / S3_SECRET_KEY	(empty)	Static credentials. Leave empty to use the AWS SDK default chain (env vars, profiles, instance roles).
S3_REGION	us-east-1	Region.
S3_PATH_STYLE	true	The classic silent-failure knob. true for MinIO and most S3-compatibles (path-style endpoint/bucket/key); false for real AWS (virtual-hosted bucket.endpoint/key). If uploads fail with cryptic DNS or 403 errors, check this first.

Upload caps & cleanup

Variable	Default	Purpose
MAX_FILE_SIZE_MB	50	System-wide per-file cap. Also bounds the per-question limit editors can set, and drives the HTTP multipart limits.
MAX_FILES_PER_RESPONSE	20	Maximum active uploaded files per response.
MAX_BYTES_PER_RESPONSE_MB	200	Maximum total active upload bytes per response, in MB.
FILE_CLEANUP_ENABLED	true	Master switch for the orphaned-file cleanup job.
FILE_CLEANUP_CRON	0 0 * * * * (hourly)	Cleanup schedule — a six-field Spring cron expression.
FILE_ORPHAN_GRACE_HOURS	24	Active files older than this that no response’s answers reference get deleted by the cleanup job.

Rate limiting

Rate limiting is per-IP, in-memory token buckets. See Reverse proxy & exposure for the important caveat about running behind a proxy.

Variable	Default	Purpose
FORMS_RATE_LIMIT_ENABLED	true	Master switch for all rate limiting.
UPLOAD_RATE_CAPACITY	30	Upload bucket burst capacity. With the default refill (1 token per 20 s) this yields ≈30 uploads / 10 min / IP.
REF_STATUS_RATE_CAPACITY	10	Burst capacity for the ref-status endpoint (deliberately strict — it reveals a per-reference completed/not boolean).
REF_STATUS_RATE_REFILL_PER_SECOND	1	Refill rate for the ref-status bucket.

Two more buckets exist with fixed defaults that have no dedicated variable: general mutating public requests (burst 20, refill 10/s) and geocoding (burst 10, refill 2/s). Because Spring Boot maps environment variables onto properties by relaxed binding, they can still be overridden — e.g. FORMS_RATELIMIT_CAPACITY for forms.rate-limit.capacity — but only the variables in the table above are first-class named knobs.

Compose-stack variables

These configure the docker-compose.yml stack itself rather than the backend process:

Variable	Default	Purpose
BACKEND_PORT / EDITOR_PORT / MONGO_PORT	8080 / 8081 / 27017	Host port mappings.
MINIO_PORT / MINIO_CONSOLE_PORT	9000 / 9001	MinIO API and web-console ports.
MINIO_ROOT_USER / MINIO_ROOT_PASSWORD	minioadmin / minioadmin	MinIO credentials, also passed to the backend as its S3 keys. Change for anything non-local.
FE_API_BASE	http://localhost:8080	The browser-facing backend URL. Written into the editor’s config.js at container start and used in the embed snippets the editor generates.

FE_API_BASE is runtime configuration, not baked in at build time — one editor image serves any backend URL; the container entrypoint regenerates config.js on every start.