Environment variables

This reference lists the environment variables used to configure Reporter, the service that generates regulatory, compliance, and accounting reports from configurable templates. Reporter ships as a single binary, and RUN_MODE selects its active surfaces: the API manager, the report worker, or both. You set these at deploy time, through Helm values, Docker Compose, or your orchestrator’s environment. Variables marked as required cause the server to fail on startup if not set. For the configuration blocks that every Lerian product shares (TLS posture, OpenTelemetry, Access Manager authentication, service discovery, and event streaming), see the BYOC configuration reference. This page focuses on what is distinctive to Reporter.

Run mode and ports

RUN_MODE decides which surfaces the process serves. Run the API and worker as one process (all) for small deployments, or split them into separate deployables (api and worker) to scale report generation independently. See the health and readiness reference for the probe contract.

Variable	Description	Default	Required
`RUN_MODE`	Surfaces to run: `api`, `worker`, or `all`	`all`	No
`SERVER_PORT` / `SERVER_ADDRESS`	API bind address (`RUN_MODE=api`/`all`), read from `SERVER_ADDRESS`; `SERVER_PORT` is the convention used to build it (`:4005`). Serves `/health`, `/readyz`, `/version`.	—	Yes (`api`/`all`)
`HEALTH_PORT`	Worker health port (`RUN_MODE=worker`). Serves `/health`, `/readyz`.	`4006`	No

Deployment and TLS

Variable	Description	Default	Required
`DEPLOYMENT_MODE`	Deployment flavor: `local`, `byoc`, or `saas`. In `saas`, TLS is mandatory for every dependency connection and the server refuses to start without it. In `byoc`, TLS is recommended and warned-on rather than enforced. Also tags the `/readyz` response.	`local`	No
`ALLOW_INSECURE_TLS`	Bypass per-connection TLS enforcement on infrastructure DSNs. Leave unset or `false` in production.	`false`	No
`ENV_NAME`	Environment name. With `production`, the Manager requires telemetry, Access Manager authentication, explicit HTTPS CORS origins, and real passwords at startup. It also requires TLS to Redis, RabbitMQ, and object storage unless `ALLOW_INSECURE_TLS` is `true`. With `local`, Reporter reads a `.env` file.	`local`	No

CORS and proxies

Variable	Description	Default	Required
`CORS_ALLOWED_ORIGINS`	Allowed CORS origins (CSV, or `*`). Lock to explicit origins in production.	`*`	No
`CORS_ALLOWED_METHODS`	Allowed CORS methods	varies	No
`CORS_ALLOWED_HEADERS`	Allowed CORS headers	varies	No
`TRUSTED_PROXIES`	Trusted proxy CIDRs for `X-Forwarded-For` parsing. Set when running behind a load balancer.	—	No
`SWAGGER_ENABLED`	Serve the OpenAPI/Swagger UI	`false`	No

API pagination

Variable	Description	Default	Required
`MAX_PAGINATION_LIMIT`	Largest `limit` a list operation accepts. A request above the ceiling is rejected with a pagination error rather than clamped.	`100`	No

Template uploads

Variable	Description	Default	Required
`MAX_TEMPLATE_FILE_BYTES`	Largest template file, in bytes, that an upload accepts. A larger file is rejected with `RPT-0078`. The server refuses any request body over 4 MiB, whatever this value.	`1048576` (1 MiB)	No

Template previews

Variable	Description	Default	Required
`PREVIEW_MAX_CONCURRENT`	Maximum synchronous template previews the API manager renders at once. When all slots are in use, Reporter rejects a new preview immediately with HTTP `429` and `RPT-0108`; it does not queue it. This is a concurrent-render limit, not a request-rate limit. Values below `1` use the default.	`4`	No

Report calendar

Variable	Description	Default	Required
`REPORT_TIMEZONE`	IANA time zone that measures the start and end of every day in report date filters. Set the zone your books close in, such as `America/Sao_Paulo`. Manager and worker must carry the same value. An unknown name stops the startup. The value applies to every tenant of the deployment.	`UTC`	No

Database (MongoDB)

Stores report metadata, templates, and run history.

Variable	Description	Default	Required
`MONGO_URI`	Connection scheme: `mongodb` or `mongodb+srv`	—	Yes
`MONGO_HOST`	MongoDB host	—	Yes
`MONGO_PORT`	MongoDB port	—	Yes
`MONGO_USER`	Database user	—	Yes
`MONGO_PASSWORD`	Database password. Sensitive.	—	Yes
`MONGO_NAME`	Database name	—	Yes
`MONGO_PARAMETERS`	Extra MongoDB URI options, such as `authSource=admin`	—	No
`MONGO_MAX_POOL_SIZE`	Maximum connection pool size	`100`	No
`MONGO_TLS_CA_CERT`	Base64-encoded PEM CA certificate for TLS (for example AWS DocumentDB)	—	No

Message broker (RabbitMQ)

Carries the generate-report command queue between the API and the worker.

Variable	Description	Default	Required
`RABBITMQ_HOST`	Broker host	—	Yes
`RABBITMQ_PORT_AMQP`	AMQP port	—	Yes
`RABBITMQ_PORT_HOST`	Management/HTTP port	—	No
`RABBITMQ_URI`	Connection scheme: `amqp` or `amqps`. Use `amqps` in production.	—	Yes
`RABBITMQ_DEFAULT_USER`	Broker user	—	Yes
`RABBITMQ_DEFAULT_PASS`	Broker password. Sensitive.	—	Yes
`RABBITMQ_EXCHANGE`	Exchange where the API publishes report-generation commands	—	Yes (`api`/`all`)
`RABBITMQ_GENERATE_REPORT_QUEUE`	Queue that carries report-generation commands from the API to the worker	—	Yes (`api`/`worker`/`all`)
`RABBITMQ_GENERATE_REPORT_KEY`	Routing key the API uses for report-generation commands	—	Yes (`api`/`all`)
`RABBITMQ_NUMBERS_OF_WORKERS`	Worker consumer concurrency	`5`	No

Object storage (S3-compatible)

Where rendered reports are stored. Works with any S3-compatible endpoint.

Variable	Description	Default	Required
`OBJECT_STORAGE_ENDPOINT`	S3-compatible endpoint URL. Leave empty for AWS S3.	—	No
`OBJECT_STORAGE_REGION`	Storage region	`us-east-1`	No
`OBJECT_STORAGE_BUCKET`	Bucket for rendered reports	`reporter-storage`	No
`OBJECT_STORAGE_ACCESS_KEY_ID`	Access key ID. Leave it and the secret key empty to use the AWS default credential chain. Sensitive.	—	No
`OBJECT_STORAGE_SECRET_KEY`	Secret access key. Sensitive.	—	No
`OBJECT_STORAGE_USE_PATH_STYLE`	Use path-style addressing (needed by some S3-compatible stores)	`false`	No
`OBJECT_STORAGE_DISABLE_SSL`	Disable TLS to the storage endpoint. Leave `false` in production.	`false`	No

Cache (Redis / Valkey)

Variable	Description	Default	Required
`REDIS_HOST`	Redis/Valkey host and port	—	Yes
`REDIS_PASSWORD`	Authentication password. Sensitive.	—	No
`REDIS_DB`	Logical database index	`0`	No
`REDIS_PROTOCOL`	RESP protocol version	`3`	No
`REDIS_TLS`	Enable TLS for the connection	`false`	No
`REDIS_CA_CERT`	Base64-encoded PEM CA certificate for TLS	—	No
`REDIS_MASTER_NAME`	Sentinel master name (Sentinel deployments)	—	No
`REDIS_USE_GCP_IAM`	Authenticate to GCP Memorystore with IAM instead of a password	`false`	No

PDF rendering (worker)

Variable	Description	Default	Required
`PDF_POOL_WORKERS`	Concurrent PDF render workers	`2`	No
`PDF_TIMEOUT_SECONDS`	Per-report PDF render timeout (seconds)	`90`	No
`PDF_PAPER_SIZE`	Page size: `A4` or `Letter`	`A4`	No
`PDF_DISPLAY_HEADER_FOOTER`	Print a header and a footer on each PDF page	`true`	No

Extraction limits (worker)

Variable	Description	Default	Required
`ENGINE_MAX_DATASOURCES`	Data sources one report can read	`10`	No
`ENGINE_MAX_TABLES_PER_DATASOURCE`	Tables or collections per data source	`20`	No
`ENGINE_MAX_FIELDS_PER_TABLE`	Fields per table	`50`	No
`ENGINE_MAX_CONCURRENCY`	Data sources extracted in parallel	`4`	No
`ENGINE_TIMEOUT_SEC`	Timeout of one extraction (seconds)	`300`	No
`ENGINE_MAX_RESULT_BYTES`	Largest extraction result. A larger result fails the extraction.	256 MiB	No
`DATASOURCE_DEFAULT_ROW_CEILING`	Rows one table can return, for a data source without its own ceiling. A table that exceeds it fails with `RPT-0161`.	`150000`	No
`DATASOURCE_DEFAULT_QUERY_TIMEOUT_SEC`	Timeout of one query (seconds), for a data source without its own value. A query that exceeds it fails with `RPT-0162`.	`300`	No
`ENGINE_MAX_DYNAMIC_POOLS`	Data-source connection pools the worker keeps open, across every tenant	`500`	No
`ENGINE_POOL_IDLE_TIMEOUT_SEC`	Idle time before a data-source pool closes (seconds)	`7200`	No

Stale-report reaper

A worker stamps a heartbeat on each report it generates. The Manager moves a Processing report whose heartbeat is stale to Error with RPT-0160. Manager and worker must carry the same heartbeat values.

Variable	Description	Default	Required
`REPORT_REAPER_ENABLED`	Run the reaper on the Manager	`true`	No
`REPORT_REAPER_INTERVAL_SEC`	Seconds between reaper passes	`60`	No
`REPORT_REAPER_BATCH`	Reports one tenant pass ends	`200`	No
`WORKER_HEARTBEAT_INTERVAL_SEC`	Seconds between worker heartbeats	`30`	No
`WORKER_HEARTBEAT_STALE_SEC`	Age after which a heartbeat is stale (seconds)	`180`	No

Deadline trigger (Manager)

Variable	Description	Default	Required
`DEADLINE_TRIGGER_ENABLED`	Run the sweep that publishes `deadline.due` when a deadline’s day arrives	`false`	No
`DEADLINE_TRIGGER_INTERVAL_SEC`	Seconds between sweeps	`300`	No
`DEADLINE_TRIGGER_GENERATE_CATEGORIES`	Comma-separated template categories for which the sweep also generates the report. Empty generates none.	—	No
`DEADLINE_TRIGGER_GENERATION_TIMEOUT_SEC`	Timeout of one scheduled generation (seconds)	`20`	No
`DEADLINE_TRIGGER_MAX_CATCH_UP_OCCURRENCES`	Missed occurrences of one deadline that one sweep generates	`7`	No

Regulatory catalog

Without a catalog source, the deployment carries no regulatory documents.

Variable	Description	Default	Required
`REGULATORY_CATALOG_DIR`	Directory where the curated catalog is mounted. Reporter reads it at startup, and a catalog that does not load stops the startup.	—	No
`REGULATORY_CATALOG_GITHUB_REPO`	`owner/repo` that publishes the catalog releases. When set, subscriptions fetch from it instead of the directory.	—	No
`REGULATORY_CATALOG_GITHUB_TOKEN`	Token for a private catalog repository. Sensitive.	—	No
`REGULATORY_CATALOG_GITHUB_URL`	Alternative API root, such as a proxy	—	No

Report datasources

Reports read from PostgreSQL and MongoDB datasources in the persisted registry. Create and manage ordinary entries through the data-source API. The environment block below is an optional bootstrap path. DATASOURCE_{NAME}_CONFIG_NAME makes an environment seed block exist. Reporter scans for keys that match DATASOURCE_*_CONFIG_NAME. The prefix counts as much as the suffix, so a key that only ends in _CONFIG_NAME declares nothing. At Manager startup, a complete block seeds its configName only when no registry entry, including a soft-deleted one, already uses that name. The value is the name your templates use to address the source. Within a block, the variables marked required are the ones Reporter needs before it reads the block.

Variable	Description	Default	Required
`DATASOURCE_{NAME}_CONFIG_NAME`	Name that templates use to address this datasource. Declares the block.	—	Yes
`DATASOURCE_{NAME}_TYPE`	Datasource engine: `postgresql` or `mongodb`	—	Yes
`DATASOURCE_{NAME}_HOST`	Datasource host	—	Yes
`DATASOURCE_{NAME}_PORT`	Datasource port	—	Yes
`DATASOURCE_{NAME}_DATABASE`	Database name	—	Yes
`DATASOURCE_{NAME}_USER`	Datasource user	—	No
`DATASOURCE_{NAME}_PASSWORD`	Datasource password. Sensitive.	—	No
`DATASOURCE_CRED_ENC_KEY`	Persistent hex-encoded AES key shared by Manager and worker to encrypt and decrypt registry credentials. Keep it unchanged across restarts and deployments; changing it prevents them from decrypting credentials already stored in the registry. Generate it with `openssl rand -hex 32`.	—	Yes
`DATASOURCE_{CONFIG_NAME}_SCHEMAS`	Schemas to expose from the datasource (CSV). This key uses the uppercased `CONFIG_NAME` value, unlike the other keys in the block.	`public`	No
`DATASOURCE_{NAME}_SSLMODE`	SSL mode for a PostgreSQL connection	—	No
`DATASOURCE_{NAME}_SSLROOTCERT`	Path to the PostgreSQL SSL root certificate	—	No
`DATASOURCE_{NAME}_SSL`	Enable TLS on a MongoDB connection	—	No
`DATASOURCE_{NAME}_SSLCA`	Path to the MongoDB CA certificate file	—	No
`DATASOURCE_{NAME}_SSLCA_BASE64`	Standard Base64 of a PEM CA bundle, on one line. An alternative to the certificate file path. For PostgreSQL, set `SSLMODE` to `verify-ca` or `verify-full`, or leave it empty for `verify-full`.	—	No
`DATASOURCE_{NAME}_OPTIONS`	Extra MongoDB URI options	—	No
`DATASOURCE_{NAME}_ROW_CEILING`	Rows one table of this data source can return	`DATASOURCE_DEFAULT_ROW_CEILING`	No
`DATASOURCE_{NAME}_QUERY_TIMEOUT_SEC`	Timeout of one query on this data source (seconds)	`DATASOURCE_DEFAULT_QUERY_TIMEOUT_SEC`	No
`DATASOURCE_CRM_MIDAZ_ORGANIZATION_ID`	Midaz organization ID that scopes the reserved CRM datasource. Required when `DATASOURCE_CRM_CONFIG_NAME=plugin_crm`.	—	No
`CRYPTO_HASH_SECRET_KEY_CRM`	Existing CRM hashing key used to read CRM datasource PII. Sensitive; required when CRM fields are read.	—	No
`CRYPTO_ENCRYPT_SECRET_KEY_CRM`	Existing CRM encryption key used to read CRM datasource PII. Sensitive; required when CRM fields are read.	—	No

A complete per-datasource seed block follows. Set the global DATASOURCE_CRED_ENC_KEY separately as described above. We recommend using the same name for CONFIG_NAME and {NAME}, with the environment-variable segment uppercased (for example, ONBOARDING for CONFIG_NAME=onboarding). That keeps the schema key intuitive, because SCHEMAS uses the CONFIG_NAME value as its key while every other field uses {NAME}:

DATASOURCE_ONBOARDING_CONFIG_NAME=onboarding
DATASOURCE_ONBOARDING_TYPE=postgresql
DATASOURCE_ONBOARDING_HOST=midaz-postgres-replica
DATASOURCE_ONBOARDING_PORT=5702
DATASOURCE_ONBOARDING_DATABASE=onboarding
DATASOURCE_ONBOARDING_USER=reporter
DATASOURCE_ONBOARDING_PASSWORD=<secret>
DATASOURCE_ONBOARDING_SCHEMAS=public

A template then addresses that source by its config name, as in {{ onboarding.accounts }}. Use the API to add or update an ordinary datasource. An environment block only seeds a previously absent entry. It never overwrites an API-managed entry or restores a soft-deleted one.

Reserved CRM datasource

plugin_crm is the reserved, environment-managed CRM datasource. Do not create it or PATCH it through the ordinary data-source API: Reporter rejects that path with RPT-0073. A CRM template must use the exact config name plugin_crm and a complete MongoDB block:

DATASOURCE_CRM_CONFIG_NAME=plugin_crm
DATASOURCE_CRM_TYPE=mongodb
DATASOURCE_CRM_HOST=<crm-mongodb-host>
DATASOURCE_CRM_PORT=<crm-mongodb-port>
DATASOURCE_CRM_DATABASE=<crm-database>
DATASOURCE_CRM_USER=<crm-readonly-user>
DATASOURCE_CRM_PASSWORD=<secret>
DATASOURCE_CRM_MIDAZ_ORGANIZATION_ID=<midaz-organization-id>

Put DATASOURCE_CRM_PASSWORD, CRYPTO_HASH_SECRET_KEY_CRM, and CRYPTO_ENCRYPT_SECRET_KEY_CRM in your secret store. The CRM crypto values must be the same keys already used by CRM. Do not generate replacement keys for Reporter. Keep DATASOURCE_CRED_ENC_KEY stable as well: changing it prevents Reporter from decrypting stored datasource credentials. Manager uses this block at startup to seed plugin_crm and to fill an absent or empty metadata.midazOrganizationId. A non-empty persisted organization ID wins and is not overwritten by the environment. If it is wrong, stop and use the supported engineering recovery path. Do not use the ordinary API to change it. To set these variables with the Reporter chart, see the Reporter chart README. For templates that use plugin_crm, validate the full path: import or save the template, generate a report, confirm CRM fields decrypt, and confirm its records are scoped to the intended Midaz organization.

Shared configuration backbone

The following blocks are identical across Lerian products. The BYOC configuration reference documents them in full. They default off.

Access Manager authentication: PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS. Enable in production.
Service discovery: SD_* (Consul, and Reporter also accepts the legacy SD_ADVERTISE_* / CONSUL_ADDR aliases). Off by default.
Event streaming: STREAMING_ENABLED, STREAMING_BROKERS, STREAMING_CLOUDEVENTS_SOURCE, plus RABBITMQ_REPORT_EVENTS_EXCHANGE for the events exchange and STREAMING_KAFKA_BROKERS for the optional Kafka copy of report.finished and report.partial. Off by default.
OpenTelemetry: ENABLE_TELEMETRY, OTEL_*, OTEL_INSECURE_EXPORTER. Telemetry is OTLP push.

Overview

Concepts

Guides

Integration

Console

Operations

Environment variables

Run mode and ports

Deployment and TLS

CORS and proxies

Template uploads

Template previews

Report calendar

Database (MongoDB)

Message broker (RabbitMQ)

Object storage (S3-compatible)

Cache (Redis / Valkey)

PDF rendering (worker)

Extraction limits (worker)

Stale-report reaper

Deadline trigger (Manager)

Regulatory catalog

Report datasources

Reserved CRM datasource

Shared configuration backbone

​Run mode and ports

​Deployment and TLS

​CORS and proxies

​API pagination

​Template uploads

​Template previews

​Report calendar

​Database (MongoDB)

​Message broker (RabbitMQ)

​Object storage (S3-compatible)

​Cache (Redis / Valkey)

​PDF rendering (worker)

​Extraction limits (worker)

​Stale-report reaper

​Deadline trigger (Manager)

​Regulatory catalog

​Report datasources

​Reserved CRM datasource

​Shared configuration backbone

Run mode and ports

Deployment and TLS

CORS and proxies

API pagination

Template uploads

Template previews

Report calendar

Database (MongoDB)

Message broker (RabbitMQ)

Object storage (S3-compatible)

Cache (Redis / Valkey)

PDF rendering (worker)

Extraction limits (worker)

Stale-report reaper

Deadline trigger (Manager)

Regulatory catalog

Report datasources

Reserved CRM datasource

Shared configuration backbone