Skip to content

Environment Variables

Frontend

NameDefaultSinceDepr ¹Description
ORIGINv0.26The base URL of the frontend as accessed by the browser.
BACKEND_BASE_URLv0.26The BASE_URL of the backend as reachable by the frontend.
AUTH_CLIENT_IDv0.26The client ID of the OAuth client used to communicate with the auth provider.
AUTH_CLIENT_SECRETv0.26The client ID of the OAuth client used to communicate with the auth provider.
AUTH_ISSUERv0.26The base URL of the auth provider. For Keycloak that is the realm base URL.
AUTH_SECRETv0.26A secret random string that is used to encrypt the session cookie. This should be a minimum of 32 characters, random string. On UNIX systems you can use openssl rand -hex 32 to generate one.
PROTOCOL_HEADERv0.26Set this to x-forwarded-proto if the frontend is deployed behind a reverse proxy.
HOST_HEADERv0.26Set this to x-forwarded-host if the frontend is deployed behind a reverse proxy.
NODE_EXTRA_CA_CERTSv0.26The name of a file with additional CA certificates needed to access especially the auth provider.

Backend

Blaze backend is configured solely through environment variables. There is a default for every variable. So all variables are optional.

A part of the environment variables depends on the storage variant chosen. The storage variant can be set through the STORAGE env var. The default is in-memory for the JAR and standalone for the Docker image. The third setting is distributed. The following tables list the database relevant environment variables by storage variant.

In-memory

NameDefaultSinceDepr ¹Description
DB_RESOURCE_INDEXER_THREADS4v0.8The number threads used for indexing resources. Try 8 or 16 depending on your hardware.
DB_RESOURCE_INDEXER_BATCH_SIZE1v0.8v0.11The number of resources which are indexed in a batch. (Deprecated)

¹ Deprecated

Standalone

The three database directories must not exist on the first start of Blaze and will be created by Blaze itself. It's possible to put this three directories on different disks in order to improve performance.

NameDefaultSinceDepr ¹Description
INDEX_DB_DIRindex ²v0.8The directory were the index database files are stored.
INDEX_DB_WAL_DIR<empty>v0.18The directory were the index database write ahead log (WAL) files are stored. Empty means same dir as database files.
TRANSACTION_DB_DIRtransaction ²v0.8The directory were the transaction log files are stored. This directory must not exist on the first start of Blaze and will be created by Blaze.
TRANSACTION_DB_WAL_DIR<empty>v0.18The directory were the transaction log write ahead log (WAL) files are stored. Empty means same dir as database files.
RESOURCE_DB_DIRresource ²v0.8The directory were the resource files are stored. This directory must not exist on the first start of Blaze and will be created by
RESOURCE_DB_WAL_DIR<empty>v0.18The directory were the resource write ahead log (WAL) files are stored. Empty means same dir as database files.
DB_BLOCK_CACHE_SIZE128v0.8The size of the block cache of the DB in MiB. This cache is outside of the JVM heap.
DB_RESOURCE_CACHE_SIZE100000v0.8The size of the resource cache of the DB in number of resources.
DB_MAX_BACKGROUND_JOBS4v0.8The maximum number of the background jobs used for DB compactions.
DB_RESOURCE_INDEXER_THREADS4v0.8The number threads used for indexing resources. Try 8 or 16 depending on your hardware.
DB_RESOURCE_INDEXER_BATCH_SIZE1v0.8v0.11The number of resources which are indexed in a batch. (Deprecated)
DB_RESOURCE_STORE_KV_THREADS4v0.17The number of threads used for reading and writing resources.

¹ Deprecated, ² In the JAR variant. The Docker image uses a directory below the /app/data directory.

Distributed

The distributed storage variant only uses the index database locally.

NameDefaultSinceDepr ¹Description
INDEX_DB_DIRindex ²v0.8The directory were the index database files are stored.
INDEX_DB_WAL_DIR<empty>v0.18The directory were the index database write ahead log (WAL) files are stored. Empty means same dir as database files.
DB_BLOCK_CACHE_SIZE128v0.8The size of the block cache of the DB in MiB. This cache is outside of the JVM heap.
DB_RESOURCE_CACHE_SIZE100000v0.8The size of the resource cache of the DB in number of resources.
DB_MAX_BACKGROUND_JOBS4v0.8The maximum number of the background jobs used for DB compactions.
DB_RESOURCE_INDEXER_THREADS4v0.8The number threads used for indexing resources. Try 8 or 16 depending on your hardware.
DB_RESOURCE_INDEXER_BATCH_SIZE1v0.8v0.11The number of resources which are indexed in a batch. (Deprecated)
DB_RESOURCE_STORE_KV_THREADS4v0.17The number threads used for reading and writing resources.
DB_KAFKA_BOOTSTRAP_SERVERSlocalhost:9092v0.8A comma separated list of bootstrap servers for the Kafka transaction log.
DB_KAFKA_MAX_REQUEST_SIZE1048576v0.8The maximum size of a encoded transaction able to send to the Kafka transaction log in bytes.
DB_KAFKA_COMPRESSION_TYPEsnappyv0.11The compression type for transaction data generated by the producer. Valid values are none, gzip, snappy, lz4, or zstd.
DB_KAFKA_SECURITY_PROTOCOLPLAINTEXTv0.11Protocol used to communicate with brokers. Valid values are: PLAINTEXT and SSL.
DB_KAFKA_SSL_TRUSTSTORE_LOCATIONv0.11The location of the trust store file.
DB_KAFKA_SSL_TRUSTSTORE_PASSWORDv0.11The password for the trust store file. If a password is not set, trust store file configured will still be used, but integrity checking is disabled.
DB_KAFKA_SSL_KEYSTORE_LOCATIONv0.11The location of the key store file. This is optional for client and can be used for two-way authentication for client.
DB_KAFKA_SSL_KEYSTORE_PASSWORDv0.11The store password for the key store file. This is optional for client and only needed if DB_KAFKA_SSL_KEYSTORE_LOCATION is configured.
DB_KAFKA_SSL_KEY_PASSWORDv0.11The password of the private key in the key store file. This is required for clients only if two-way authentication is configured.
DB_CASSANDRA_CONTACT_POINTSlocalhost:9042v0.8A comma separated list of contact points for the Cassandra resource store.
DB_CASSANDRA_USERNAMEcassandrav0.11The username for the Cassandra authentication.
DB_CASSANDRA_PASSWORDcassandrav0.11The password for the Cassandra authentication.
DB_CASSANDRA_KEY_SPACEblazev0.8The Cassandra key space were the resources table is located.
DB_CASSANDRA_PUT_CONSISTENCY_LEVELTWOv0.8Cassandra consistency level for resource put (insert) operations. Has to be set to ONE on a non-replicated keyspace.
DB_CASSANDRA_REQUEST_TIMEOUT2000v0.11Timeout in milliseconds for all requests to the Cassandra cluster.

¹ Deprecated, ² In the JAR variant. The Docker image uses a directory below the /app/data directory.

More information about distributed deployment are available here.

Other Environment Variables

NameDefaultSinceDepr ¹Description
PROXY_HOSTv0.6REMOVED: use -Dhttp.proxyHost
PROXY_PORTv0.6REMOVED: use -Dhttp.proxyPort
PROXY_USERv0.6.1REMOVED: try SOCKS Options
PROXY_PASSWORDv0.6.1REMOVED: try SOCKS Options
CONNECTION_TIMEOUT5 sv0.6.3connection timeout for outbound HTTP requests
REQUEST_TIMEOUT30 sv0.6.3REMOVED
TERM_SERVICE_URIhttp://tx.fhir.org/r4v0.6v0.11Base URI of the terminology service
BASE_URLhttp://localhost:8080The URL under which Blaze is accessible by clients.
CONTEXT_PATH/fhirv0.11Context path under which the FHIR RESTful API will be accessible.
SERVER_PORT8080The port of the main HTTP server
METRICS_SERVER_PORT8081v0.6The port of the Prometheus metrics server
LOG_LEVELinfov0.6one of trace, debug, info, warn or error
JAVA_TOOL_OPTIONSJVM options (Docker only)
FHIR_OPERATION_EVALUATE_MEASURE_THREADSnumber of CPUsv0.8The number threads used for $evaluate-measure executions.
FHIR_OPERATION_EVALUATE_MEASURE_TIMEOUT3600000 (1h)v0.19Timeout in milliseconds for synchronous $evaluate-measure executions.
OPENID_PROVIDER_URLv0.11OpenID Connect provider URL to enable authentication
OPENID_CLIENT_TRUST_STOREv0.26A PKCS #12 trust store containing CA certificates needed for the OpenID Connect provider.
OPENID_CLIENT_TRUST_STORE_PASSv0.26The password for the PKCS #12 trust store.
ENFORCE_REFERENTIAL_INTEGRITYtruev0.14Enforce referential integrity on resource create, update and delete.
DB_SYNC_TIMEOUT10000v0.15Timeout in milliseconds for all reading FHIR interactions acquiring the newest database state.
DB_SEARCH_PARAM_BUNDLEv0.21Name of a custom search parameter bundle file.
ENABLE_ADMIN_APIv0.26Set to true if the optional Admin API should be enabled. Needed by the frontend.
CQL_EXPR_CACHE_SIZEv0.28Size of the CQL expression cache in MiB. This cache is part of the JVM heap. Will be disabled if not given.
CQL_EXPR_CACHE_REFRESHPT24Hv0.28The duration after which a Bloom filter of the CQL expression cache will be refreshed.
CQL_EXPR_CACHE_THREADS4v0.28The maximum number of parallel Bloom filter calculations for the CQL expression cache.
ALLOW_MULTIPLE_DELETEfalsev0.30Allow deleting multiple resources using Conditional Delete.
ENABLE_INTERACTION_DELETE_HISTORY-v0.30.1Enable the Delete History interaction.
ENABLE_OPERATION_PATIENT_PURGE-v0.30.1Enable the Operation $purge on Patient.

¹ Deprecated

BASE_URL

The FHIR RESTful API will be accessible under BASE_URL/CONTEXT_PATH. Possible X-Forwarded-Host, X-Forwarded-Proto and Forwarded request headers will override this URL.

FHIR_OPERATION_EVALUATE_MEASURE_THREADS

The number threads used for $evaluate-measure executions. The default is the number of available processors (CPUs). For measures that do not load lots of resources from disk the default is the right choice. However, if some of the measures load lots of resources directly from disk, it can be beneficial to set the number of threads to 2x or 4x the number of available processors. Be sure to increase DB_RESOURCE_STORE_KV_THREADS accordingly to be able to use the increased I/O capabilities.

OPENID_CLIENT_TRUST_STORE

The PKCS #12 trust store has to be generated by the Java keytool. OpenSSL will not work.

sh
keytool -importcert -storetype PKCS12 -keystore "trust-store.p12" \
  -storepass "..." -alias ca -file "cert.pem" -noprompt

ENFORCE_REFERENTIAL_INTEGRITY

It's enabled by default but can be disabled on proxy/middleware/secondary systems were a primary system ensures referential integrity.

DB_SYNC_TIMEOUT

All reading FHIR interactions have to acquire the last database state known at the time the request arrived in order to ensure consistency. That database state might not be ready immediately because indexing might be still undergoing. In such a situation, the request has to wait for the database state becoming available. If the database state won't be available before the timeout expires, a 503 Service Unavailable response will be returned. Please increase this timeout if you experience such 503 responses, and you are not able to improve indexing performance or lower transaction load.

Common JAVA_TOOL_OPTIONS

NameDefaultSinceDescription
-Xmx4g-The maximum amount of heap memory.
-Dhttp.proxyHost-v0.11The hostname of the proxy server for outbound HTTP requests.
-Dhttp.proxyPort80v0.11The port of the proxy server.