Marble Environment Variables

This table documents all environment variables expected by the Marble application, indicating which containers use them and which require them.

See our Github page for more details on the parts of the Marble application.

Container Legend

Marble consists of 4 main elements, described below, plus external dependencies for webhooks sending and (sanction and other) screening.

The "api", "worker" and "migrations" containers mentioned below are actually the same docker image, respectively executed with the arguments --server, --worker and --migrations. They are generally run separately.

api - Main API server (api container)
worker - Background job processor (cron container)
migrations - DB migration job
frontend - Frontend application (app container)

Environment Variables

Variable Name	Format & Details	Default Value	Used In Containers	Required In Containers
AUTHENTICATION_JWT_SIGNING_KEY	RSA private key in PEM format for signing auth tokens. Line breaks as `\n`. Generate with `openssl genrsa -out key.pem 4096`. Recommended alternative: use `AUTHENTICATION_JWT_SIGNING_KEY_FILE`	A new one is generated on the fly at container start time if not present, but this may lead to random disconnections on auto-scaling infrastructure.	api	-
AUTHENTICATION_JWT_SIGNING_KEY_FILE	Path to a RSA private key in PEM format for signing auth tokens. Generate with `openssl genrsa -out key.pem 4096`.	A new one is generated on the fly at container start time if not present, but this may lead to random disconnections on auto-scaling infrastructure.	api	-
CASE_MANAGER_BUCKET_URL	Blob storage URL for case manager documents. See format in the section below.	-	api, worker	api, worker
CONVOY_API_KEY	Convoy API key from project settings → Secrets	-	api, worker	-
CONVOY_API_URL	Convoy API URL for webhooks. Format: `{scheme}://{host}:{port}/api`. Must include `/api` and must be reachable from the api and worker containers.	-	api, worker	-
CONVOY_PROJECT_ID	Convoy project ID from project settings → Secrets	-	api, worker	-
CREATE_ORG_ADMIN_EMAIL	Initial admin user email for bootstrap. Must match Firebase account. Can be empty after initial setup.	-	api	-
CREATE_ORG_NAME	Initial organization name for bootstrap. Firebase user is created at login time for the first user. Can be empty after initial setup.	-	api	-
DISABLE_SEGMENT	Boolean (`true`/`false`). Disables basic product usage analytics.	`false`	api, frontend	-
DISABLE_TELEMETRY	Boolean (`true`/`false`). Disables product telemetry.	`false`	worker	-
ENV	Environment name (e.g., `production`, `staging`). Used for logging and telemetry. Do not set to `development` in production.	`"production"`	api, worker, frontend	-
FIREBASE_API_KEY	Firebase API key from Firebase project settings. Register new app to retrieve	-	api	api
FIREBASE_AUTH_DOMAIN	Firebase auth domain for federated authentication. From Firebase settings → General	Computed from the Google cloud project or Firebase project ID.	api	-
FIREBASE_PROJECT_ID	Firebase project ID from Firebase project settings	Uses the same value as GOOGLE_CLOUD_PROJECT by default (which is sufficient in the majority of cases).	api	api
GOOGLE_APPLICATION_CREDENTIALS	Path to GCP service account JSON key file (e.g., `/shared/service_account_key.json`)	-	api, worker	Required on those containers if running with Firebase authentication, outside of a GCP environment.
GOOGLE_CLOUD_PROJECT	GCP Project ID for Firebase, GCS and tracing	Automatically retrieved from Metadata server if running on GCP infrastructure.	api, worker	Required on those containers if running with Firebase authentication, outside of a GCP environment.
INGESTION_BUCKET_URL	Blob storage URL for data ingestion. See format in the section below.	-	api, worker	api, worker
LICENSE_KEY	Marble license key for premium features	-	api, worker	Required on api and worker to access premium features.
LOGGING_FORMAT	Log format (e.g., `"json"`, `"text"`). Use `"json"` to enable structured logging.	`"text"`	api, worker	-
MARBLE_API_URL	URL frontend uses to reach API. Must include scheme (e.g., `http://api:8080` for docker-compose). May be an internal URL but must be reachable from the frontend container.	-	frontend	frontend
MARBLE_APP_URL	URL users access Marble frontend from browser. Must include scheme (e.g., `http://localhost:3000`). Must be reachable from the browser of the people who will be using the Marble app.	-	api	api
METABASE_GLOBAL_DASHBOARD_ID	Dashboard ID from Metabase static embedding	-	api	-
METABASE_JWT_SIGNING_KEY	JWT signing key from Metabase admin panel → Settings → Embedding → Static embedding	-	api	-
METABASE_SITE_URL	Metabase instance URL for embedded analytics	-	api	-
OFFLOADING_BATCH_SIZE	Number of records to offload per batch.	`10000`	worker	-
OFFLOADING_BEFORE	Offload rules older than this duration (e.g., `168h` for 7 days). Go duration format .	`168h`	worker	-
OFFLOADING_BUCKET_URL	Blob storage URL for offloading. See format in the section below.	-	api, worker	Required on worker if `OFFLOADING_ENABLED=true`
OFFLOADING_ENABLED	Boolean (`true`/`false`). Enables offloading decision rules to blob storage.	`false`	worker	-
OFFLOADING_JOB_INTERVAL	Interval between offloading jobs (e.g., `30m`, `1h`). Minimum interval is `30m`. Go duration format.	`30m`	worker	-
OFFLOADING_SAVE_POINTS	Save progress every N records.	`1000`	worker	-
OFFLOADING_WRITES_PER_SEC	Rate limit for offloading writes per second.	`200`	worker	-
OPENSANCTIONS_API_HOST	Open Sanctions API host. Must include scheme and must be reachable from the api and worker containers.	-	api, worker	-
OPENSANCTIONS_API_KEY	API key for Open Sanctions SaaS or auth credentials	-	api, worker	-
OPENSANCTIONS_AUTH_METHOD	Authentication method: `bearer` or `basic`. For basic: provide credentials as `user:password`	-	api, worker	-
PG_CONNECTION_STRING	PostgreSQL DSN. Format: `postgres://user:pass@host:port/dbname?sslmode=prefer`. Alternative to individual PG_* variables and takes precedence over them if present. Key-value format `"user=..."` is not allowed.	-	api, worker, migrations	api, worker (if not using individual PG_* variables)
PG_HOSTNAME	PostgreSQL hostname (e.g., `db`, `localhost`)	-	api, worker, migrations	api, worker, migrations
PG_DATABASE	PostgreSQL database name	`marble`	api, worker, migrations
PG_PASSWORD	PostgreSQL password. May be omitted in some cases, for example if IAM authentication is used.	-	api, worker, migrations	api, worker, migrations (if not using PG_CONNECTION_STRING, and unless working with IAM-based DB authentication)
PG_PORT	PostgreSQL port.	`5432`	api, worker, migrations	-
PG_SSL_MODE	PostgreSQL SSL mode (`disable`, `prefer`, `require`). Should be `require` for production	`prefer`	api, worker, migrations	-
PG_USER	PostgreSQL username	-	api, worker, migrations	api, worker, migrations (if not using PG_CONNECTION_STRING)
PG_MAX_POOL_SIZE	Maximum connection pool size	40	api, worker
PORT	Port number the container listens on.	`8080` on api, `3000` on frontend	api, frontend	-
SENTRY_DSN	Sentry DSN for error tracking (e.g., `https://[email protected]/...`)	-	api, worker, frontend	-
SESSION_MAX_AGE	Frontend cookie session max age in seconds.	`43200` (12 hours)	frontend	-
SESSION_SECRET	Random string for session encryption. Generate with `openssl rand -base64 128 \| tr -d "\n"`	-	frontend	frontend

Notes

Database Configuration: You must provide either PG_CONNECTION_STRING OR the individual PG_* variables (PG_HOSTNAME, PG_PORT, PG_USER, PG_PASSWORD, PG_SSL_MODE). PG_CONNECTION_STRING takes precedence if present. Only DSN format is accepted and special characters must be url-encoded.
JWT Signing Key: You can use either AUTHENTICATION_JWT_SIGNING_KEY (inline key with \n line breaks) OR point to a file with AUTHENTICATION_JWT_SIGNING_KEY_FILE. The file approach is recommended because character escaping can be an issue with multiline environment variables.
Blob Storage: Supports multiple providers:

Local file system: file://{path}?create_dir=true (limited functionality, do not use for production)
Google Cloud Storage: gs://{bucket} (requires GOOGLE_APPLICATION_CREDENTIALS)
AWS S3: s3://{bucket} (requires AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)
Azure Blob: azblob://{bucket} (requires AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY)
Minio: s3://bucket?awssdk=v1&endpoint=https://minio.local&s3ForcePathStyle=true. When testing Marble, you can add the 'requireSSL=false' query parameter to connect in cleartext.

Requires explicit authentication variables passed, or uses automatic credentials discovery if running on GCP/AWS/Azure infrastructure.

See https://gocloud.dev/howto/blob/ for more details.

Bootstrap Variables: CREATE_ORG_NAME and CREATE_ORG_ADMIN_EMAIL are only needed for initial setup of a new organization and can be removed after the it is created.
Production Settings:

Set PG_SSL_MODE=require
Generate strong AUTHENTICATION_JWT_SIGNING_KEY (4096-bit RSA)
Generate random SESSION_SECRET (128+ bytes)
Do NOT set ENV=development
Use production-grade database (not docker-compose postgres)
Use production-grade Elasticsearch (not docker-compose ES)
Configure offloading of decision details with OFFLOADING_ENABLED