Optional environment variables

JAVA_OPTS

JAVA_OPTS="<string>"

Configure general JAVA options. For example - request and max heap size configuration.

JAVA_OPTS="-Xms1024m -Xmx1024m"

AIDBOX_BOX_ID

Assigns unique id for Aidbox instance. Important to set if you deploy few Aidbox instances and wish to separate their telemetry data (logs, metrics, traces) in your observability system.

AIDBOX_BASE_URL

AIDBOX_BASE_URL=<url>

Aidbox Base URL is URL Aidbox is available at. It consists of schema (http, https), domain, port (optional) and URL path (optional). Trailing slash is not allowed.

Default is

http://localhost:[AIDBOX_PORT]

Examples:

AIDBOX_BASE_URL=http://fhir.example.com

AIDBOX_BASE_URL=http://fhir.example.com:8080

AIDBOX_BASE_URL=http://fhir.example.com/aidbox

AIDBOX_DB_PARAM_*

AIDBOX_DB_PARAM_<parameter name>=<parameter value>

Parameters prefixed with AIDBOX_DB_PARAM_ will be passed to JDBC PostgreSQL connection string.

AIDBOX_ES_URL

If provided, enables mode to push logs to ElasticSearch.

BOX_SEARCH_DEFAULT__PARAMS_TOTAL

box_search_default__params_total=<value>

value is one of: none, estimate, accurate.

Sets the default total search parameter value.

if you use box_search_default__params_total=none you still get totalwhen:

1. you don't use _page

2. the number of returned resources is less than _count (by default is 100).

AIDBOX_ES_AUTH

AIDBOX_ES_AUTH=<user>:<password>

Basic auth credentials for ElasticSearch. API key is not supported.

AIDBOX_ES_BATCH_SIZE

AIDBOX_ES_BATCH_SIZE=<size>

Log batch size used to optimize log shipping performance. The default value is 200

AIDBOX_ES_BATCH_TIMEOUT

AIDBOX_ES_BATCH_TIMEOUT=<timeout>

Timeout to post a batch to ElasticSearch. If there is not enough records to reach full batch size

AIDBOX_ES_INDEX_PAT

AIDBOX_ES_INDEX_PAT=<format>

Custom index format string. The default value is 'aidbox-logs'-yyyy-MM-dd.

AIDBOX_LOGS

AIDBOX_LOGS=<filepath>

If provided, enables mode to pipe logs as json into the file by specified path. If ElasticSearch URL is provided then the file is used as a fallback in case if ElasticSearch is not available

AIDBOX_LOGS_MAX_LINES

AIDBOX_LOGS_MAX_LINES=<max-lines>

Sets the limit of log records to push into the file. When the limit is reached, the current log file is renamed with ".old" postfix and a new log file is created. The default value is "10000"

BOX_LOGGING_DISABLE__HEALTH__LOGS

BOX_LOGGING_DISABLE__HEALTH__LOGS=<boolean>

Disable /health endpoint requests logging. Default value is false.

BOX_LOGGING_SQL_MIN__DURATION

BOX_LOGGING_SQL_MIN__DURATION=<integer>

Threshold for logging only long queries. Analogue from Postgres.

Log only requests whose execution time exceeds the specified number of milliseconds.

BOX_LOGGING_SQL_MAX__LENGTH

BOX_LOGGING_SQL_MAX__LENGTH=<integer>

Max length of a query to be logged.

AIDBOX_INSTALL_PG_EXTENSIONS

AIDBOX_INSTALL_PG_EXTENSIONS=<boolean>

Says Aidbox to install PostgreSQL extensions at startup time. The default value is true.

AIDBOX_STDOUT_JSON

AIDBOX_STDOUT_JSON=<log-level>

log-level is one of: off, fatal, error, warn, info, debug, trace, all.

By setting one of these values you would also get all the values to the left. e.g. if you set log level to warn you would also get log events with fatal and error levels (off is excluded).

Example of the log output

{"sql":"SELECT 1","d":2,"ts":"2022-10-26T10:59:59.825Z","w":"main","ev":"db/q"}

AIDBOX_STDOUT_GOOGLE_JSON

Produces logs in Google Logging format (see LogEntry).

AIDBOX_STDOUT_GOOGLE_JSON=<log-level>

log-level is one of: off, fatal, error, warn, info, debug, trace, all.

By setting one of these values you would also get all the values to the left. e.g. if you set log level to warn you would also get log events with fatal and error levels (off is excluded).

Example of the log output

{"sql":"SELECT 1","d":2,"timestamp":"2022-10-26T10:59:59.825Z","severity":"INFO","w":"main","ev":"db/q"}

AIDBOX_STDOUT_PRETTY

AIDBOX_STDOUT_PRETTY=<log-level>

log-level is one of: off, fatal, error, warn, info, debug, trace, all.

By default log-level is error.

By setting one of these values you would also get all the values to the left. e.g. if you set log level to warn you would also get log events with fatal and error levels (off is excluded).

Example of the log output

11:01:12 main [1ms] SELECT 1

AIDBOX_DD_API_KEY

AIDBOX_DD_API_KEY=true

If provided, enables mode to push logs to DataDog

AIDBOX_DD_BATCH_SIZE

AIDBOX_DD_BATCH_SIZE=<batch-size>

Size of log batch, used to optimize performance of log shipping. The default value is 200

AIDBOX_DD_BATCH_TIMEOUT

AIDBOX_DD_BATCH_TIMEOUT=<timeout-ms>

Timeout (in ms) to post a batch to DataDog if there are not enough records to reach full batch size. Default value: 3600000 (1 hour)

AIDBOX_DD_LOGS

AIDBOX_DD_LOGS=<filepath>

Fallback file to write logs in if uploading to DataDog fails

AIDBOX_CREATED_AT_URL

AIDBOX_CREATED_AT_URL=<url>

Overrides createdAt extension url, default is ex:createdAt

AIDBOX_CORRECT_AIDBOX_FORMAT

AIDBOX_CORRECT_AIDBOX_FORMAT=true

If provided, activates transforming unknown polymorphic extensions to the correct Aidbox format avoiding keeping them at FHIR-format.

For example, extension.*.valueString stored as extension.0.value.string

BOX_CACHE_REPLICATION_DISABLE

BOX_CACHE_REPLICATION_DISABLE=true

By default, Aidbox works in multi-replica mode, so more than one Aidbox replica could be connected to the same database. If you are sure you'll be running only one Aidbox replica, you could disable replication mechanism with this variable. Check Highly Available Aidbox for additional information.

AIDBOX_DEV_MODE

AIDBOX_DEV_MODE=true

Enables _debug=policy for access policy debugging

AIDBOX_ZEN_ENTRYPOINT

AIDBOX_ZEN_ENTRYPOINT=<entrypoint>

Specifies entry point for loading Aidbox configuration. Example:

AIDBOX_ZEN_ENTRYPOINT=main/box

AIDBOX_ZEN_DEV_MODE

AIDBOX_ZEN_DEV_MODE=true

Enables watcher which reloads zen namespaces when they change.

AIDBOX_ZEN_PATHS

AIDBOX_ZEN_PATHS=<source>:<format>:<path>[,<source>:<format>:<path>]*

<source> is either url, or path.

• url is used to load project from remote location

• path is used to load project from local location

<format> is either zip, or dir, or edn.

Table of sources and format compatibility:

source/format	zip	dir	edn
url	✓		✓
path	✓	✓	✓

AIDBOX_EXTENSION_SCHEMA

AIDBOX_EXTENSION_SCHEMA=<schema>

Schema for PostgreSQL extensions. Default is current schema. See use different PostgreSQL schema section.

AIDBOX_SECURITY_AUDIT__LOG_ENABLED

AIDBOX_SECURITY_AUDIT__LOG_ENABLED=true

Enable producing audit logs in FHIR AuditEvent format for significant events.

BOX_SEARCH_DEFAULT__PARAMS_COUNT

BOX_SEARCH_DEFAULT__PARAMS_COUNT=<count>

Overrides the default count search parameter value. 100 is the default value. The provided value should be <= 1000

BOX_SEARCH_FHIR__COMPARISONS

BOX_SEARCH_FHIR__COMPARISONS=true

Use FHIR compliant date search.

BOX_SEARCH_INCLUDE_CONFORMANT

BOX_SEARCH_INCLUDE_CONFORMANT=true

When set to true, the behavior of _include and _revinclude becomes FHIR conformant:

1. Without the :recur or :iterate modifier _(rev)include is only applied to the initial result.

2. With the :recur or :iterate modifier _(rev)include is repeatedly applied to the resources found in the previous step.

BOX_SEARCH_AUTHORIZE__INLINE__REQUESTS

BOX_SEARCH_AUTHORIZE_INLINE_REQUESTS=true

Authorize inline requests

BOX_SEARCH_INCLUDE_ITERATE__MAX

BOX_SEARCH_INCLUDE_ITERATE__MAX=10

Maximum number of iterations for _include and _revinclude with :recur or :iterate modifier. The default value is 10. If set to 0, queries for _(rev)include will not be performed. If set to a negative value, no limit will be applied.

BOX_SEARCH_RESOURCE__COMPAT

BOX_SEARCH_RESOURCE__COMPAT=false

false to use preferred version of zen-search (true to backward compatibility zen search)

BOX_COMPATIBILITY_VALIDATION_JSON__SCHEMA_REGEX

BOX_COMPATIBILITY_VALIDATION_JSON__SCHEMA_REGEX="#{:fhir-datetime}"

Enables strict date time validation in JSON schema validation engine per FHIR spec.

BOX_COMPATIBILITY_AUTH_PKCE_CODE__CHALLENGE_S256_CONFORMANT

BOX_COMPATIBILITY_AUTH_PKCE_CODE__CHALLENGE_S256_CONFORMANT=true

Use conformant S256 code challenge validation scheme.

BOX_DEBUG_SU_ENABLE

BOX_DEBUG_SU_ENABLE=true

Enables su request header functionality.

BOX_FEATURES_VALIDATION_SKIP_REFERENCE

BOX_FEATURES_VALIDATION_SKIP_REFERENCE=true

Enables skipping resource reference validation.

BOX_WEB_MAX__BODY

BOX_WEB_MAX__BODY=<max-size-bytes>

Maximum size of request body in bytes. Default is 20971520 (20 MiB)

BOX_WEB_THREAD

BOX_WEB_THREAD=<count-of-web-worker-threads>

Count of HTTP server web workers. Default is 8

BOX_WEB_MAX__LINE

BOX_WEB_MAX__LINE=<max-line-bytes>

Length limit for HTTP initial line and per header, 414(Request-URI Too Long) will be returned if exceeding this limit. Default to 8192.

BOX_WEB_CORS_ENABLED

BOX_WEB_CORS_ENABLED=true

Allow CORS requests

BOX_WEB_CORS_ORIGINS

BOX_WEB_CORS_ORIGINS=*

Comma-separated list of allowed origins [schema]://[domain]:[port]

The default value is wildcard "*"

BOX_FEATURES_TERMINOLOGY_IMPORT_SYNC

BOX_FEATURES_TERMINOLOGY_IMPORT_SYNC=true

Enables synchronous terminology bundle import

BOX_FEATURES_AUTHENTICATION_INTROSPECTION_CREATE__USER

BOX_FEATURES_AUTHENTICATION_INTROSPECTION_CREATE__USER=<boolean>

Create a user when using foreign JWT access token and the user does not already exist.

BOX_FEATURES_GRAPHQL_WARMUP__ON__STARTUP

BOX_FEATURES_GRAPHQL_WARMUP__ON__STARTUP=<boolean>

Warmup graphql caches on startup

BOX_FEATURES_GRAPHQL_TIMEOUT

BOX_FEATURES_GRAPHQL_TIMEOUT=<integer>

Sets timeout for graphql queries in seconds. Default value is 60.

BOX_FEATURES_FHIR_TRANSACTION_MAX__ISOLATION__LEVEL

BOX_FEATURES_FHIR_TRANSACTION_MAX__ISOLATION__LEVEL=<isolation-level>

isolation-level is one of: none, read-committed, repeatable-read, serializable.

Sets maximum (inclusive) isolation level for transactions. This value can be overridden by x-max-isolation-level header (see here).

BOX_CONFIG_FEATURES_INDEX_SYNC__ON__START

BOX_CONFIG_FEATURES_INDEX_SYNC__ON__START=<boolean>

If enabled, Aidbox synchronizes managed index on startup.

Enable Aidbox compliance mode

AIDBOX_COMPLIANCE=enabled:

- Adds various attributes and endpoints info to CapabilityStatement

- Sanitises CapabilityStatement (i.e. removes attributes containing null values and empty arrays)

- Adds /fhir to base URL for FHIR search parameters definitions in CapabilityStatement

- Adds AIDBOX_BASE_URL in Bundle.link.url

- Adds FHIR date search parameter validation on lastUpdated search parameter

- Adds "alg": "RS256" entry for JWKS

- Changes validation error status to 422 (instead of 400)

- Changes cache-control header to no-store on authorization code auth flow (instead of no-cache, no-store, max-age=0, must-revalidate)

- Removes Bundle.entry if empty

Configuring SSL connection with PostgreSQL

Parameters prefixed with AIDBOX_DB_PARAM is passed to JDBC PostgreSQL connection string.

For an instance:

AIDBOX_DB_PARAM_SSL=true AIDBOX_DB_PARAM_SSLMODE=verify-ca

will add ssl=true&sslmode=verify-ca params to connection string.

These parameters will enable SSL connection from Aidbox to postgresql Docs on JDBC PostgreSQL connection string are here: https://jdbc.postgresql.org/documentation/80/connect.html https://jdbc.postgresql.org/documentation/head/ssl-client.html

The next step is to configure your database to accept SSL connections. You can do that by passing your own postgresql.conf with argument -c config_file passed into the db containter and probably you want to set up postgres to receive only SSL connections, you can do that by passing your own pg_hba.conf file with -c hba_file

Use different PostgreSQL schema

By default Aidbox uses public schema. If you want Aidbox to use different schema, set JDBC parameter currentSchema using environment variable AIDBOX_DB_PARAM_CURRENT_SCHEMA:

AIDBOX_DB_PARAM_CURRENT_SCHEMA=myschema

PostgreSQL extensions can create objects. By default PostgreSQL sets up extension to use current schema. If you are going to share database between multiple applications, we recommend to create a dedicated schema for the extensions.

Use AIDBOX_EXTENSION_SCHEMA environment variable to set up Aidbox to use dedicated extension schema:

AIDBOX_EXTENSION_SCHEMA=myextensionschema

Note: if your database already has extensions installed and you change extension schema (or current schema if extension schema is not configured), then you need to drop extensions from previous schema:

DROP EXTENSION IF EXISTS fuzzystrmatch
                       , jsonknife
                       , pg_stat_statements
                       , pg_trgm
                       , pgcrypto
                       , unaccent;

Then change AIDBOX_EXTENSION_SCHEMA and restart Aidbox.

Set up RSA private/public keys and secret

Aidbox generates JWT tokens for different purposes:

• As part of OAuth 2.0 authorization it generates authorization_code in JWT format

• If you specify auth token format as JWT, then your access_token and refresh_token will be in JWT format.

Aidbox supports two signing algorithms: RS256 and HS256. RS256 expects providing private key for signing JWT and public key for verifing it. As far as HS256 needs only having secret for both operations.

Attention: by default Aidbox generates both keypair and secret on every startup. This means that on every start all previously generated JWT will be invalid. In order to avoid such undesirable situation, you may pass RSA keypair and secret as Aidbox parameters.\

It is required to pass RSA keypair and secret as Aidbox parameters if you have multiple replicas of the same Aidbox/Multibox instance.

Generate RSA keypair

Generate private key with openssl genrsa -traditional -out key.pem 2048 in your terminal. Private key will be saved in file key.pem. To generate public key run openssl rsa -in key.pem -outform PEM -pubout -out public.pem. You will find public key in public.pem file.

Use next env vars to pass RSA keypair:

BOX_AUTH_KEYS_PRIVATE=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----
BOX_AUTH_KEYS_PUBLIC=-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----

Generate secret

To generate random string for HS256 algoritm you can run openssl rand -base64 36 command. The length of the random string must be more than 256 bits (32 bytes).

use next env var to pass secret param:

BOX_AUTH_KEYS_SECRET=<rand_string>

Configure Aidbox WEB server workers and DB connection pool

By default Aidbox and Multibox runs with 8 web workers and 8 DB connection pool size. That means that Aidbox can process at same time 8 concurrent connections.

A good practice is stay pool size the same as CPU count of your database. For example, if your database has 16 CPU cores you can set BOX_DB_POOL_MAXIMUM__POOL__SIZE=16. Box web workers count is dependent on your load profile. For example, if you have a lot of fast read queries you can set BOX_WEB_THREAD equal x2 or x3 of your DB pool size (32 or 48). Or if you have a lot of batch insert queries we recommend stay web workers count as the same DB pool size.

You can configure this parameter using following environment variables.

BOX_DB_POOL_MAXIMUM__POOL__SIZE=8
BOX_WEB_THREAD=8

Telemetry

By default, Aidbox collects and sends high-level anonymous API usage statistics used solely for Aidbox improvement.

BOX_TELEMETRY_ERRORS

BOX_TELEMETRY_ERRORS=false

Disable sending anonymous errors data.

BOX_TELEMETRY_USAGE__STATS

BOX_TELEMETRY_USAGE_STATS=false

Disable sending anonymous API usage statistics.

Security Labels

BOX_FEATURES_SECURITY__LABELS_ENABLE

The Security Labels access control feature is disabled by default. To enable it, set the env to true.

BOX_FEATURES_SECURITY__LABELS_ENABLE=true

BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS

By default, stripping is disabled. To enable it, set the env to true.

BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS=true

Stripping is only applied during the masking.

Observability

Follow the link below to learn how Aidbox metrics work.

Metrics

BOX_METRICS_PORT

Defines the port which will be used to expose metrics.

BOX_METRICS_POSTGRES_ON

BOX_METRICS_POSTGRES_ON=false

If you have a different pg exporter, disable Aidbox PostgreSQL metrics to avoid metrics duplication by setting the env to false.

BOX_METRICS_GRAFANA_URL

Specify the Grafana instance URL in this env.

BOX_METRICS_GRAFANA_USER

Specify the Grafana user name.

BOX_METRICS_GRAFANA_PASSWORD

Specify the Grafana user password.

Content security policy

AIDBOX_CONTENT_SECURITY_POLICY_HEADER

A Content Security Policy (CSP) is a security mechanism that helps protect web applications from threats like Cross-Site Scripting (XSS), data injection, and clickjacking. It works by specifying rules for browsers about which resources (e.g., scripts, styles, images) can be loaded and executed.

AIDBOX_CONTENT_SECURITY_POLICY_HEADER=default-src 'self'; script-src 'report-sample' 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'report-sample' 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'; connect-src 'self'; font-src 'self'; frame-src 'self'; frame-ancestors 'self'; img-src 'self' data:; manifest-src 'self'; media-src 'self'; worker-src 'self';

Recommended policies:

default-src 'self'; 
script-src 'report-sample' 'self' 'unsafe-inline' 'unsafe-eval';
style-src 'report-sample' 'self' 'unsafe-inline'; 
object-src 'none'; 
base-uri 'self'; 
connect-src 'self'; 
font-src 'self';
frame-src 'self'; 
frame-ancestors 'self'; 
img-src 'self' data:; 
manifest-src 'self'; 
media-src 'self'; 
worker-src 'self';

Explanation:

Directive	Allowed Sources	Description	Security Implications
default-src	'self'	Sets the default policy for all resource types unless overridden by specific directives.	Restricts all resources to the same origin unless explicitly allowed elsewhere.
script-src	'report-sample', 'self', 'unsafe-inline', 'unsafe-eval'	Controls JavaScript sources.	Allows same-origin scripts but also permits inline scripts and eval(), which are security risks.
style-src	'report-sample', 'self', 'unsafe-inline'	Defines valid sources for stylesheets.	Allows same-origin styles but permits inline styles, which can be exploited if not carefully managed.
object-src	'none'	Blocks <object> elements entirely.	Prevents the use of potentially dangerous <object> elements, mitigating XSS risks.
base-uri	'self'	Restricts the URLs allowed in <base> elements to the same origin.	Protects against base URL manipulation attacks.
connect-src	'self'	Limits connections (e.g., AJAX, WebSocket) to the same origin.	Prevents data exfiltration to unauthorized endpoints.
font-src	'self'	Restricts font loading to the same origin.	Reduces risks from malicious or unauthorized fonts.
frame-src	'self'	Allows embedding content in frames only from the same origin.	Mitigates clickjacking attacks by disallowing external framing of your content.
frame-ancestors	'self'	Ensures that only pages from the same origin can embed this page in a frame.	Further protects against clickjacking by controlling who can frame Aidbox pages .
img-src	'self' data:	Limits image sources to the same origin.	Prevents data leaks via malicious or unauthorized images.
manifest-src	'self'	Ensures that web app manifests are loaded only from the same origin.	Protects against unauthorized or malicious web app manifests being loaded into Aidbox.
media-src	'self'	Restricts audio and video sources to the same origin.	Prevents unauthorized media files from being loaded into Aidbox
worker-src	'self'	Limits web workers and shared workers to scripts from the same origin.	Reduces risks of malicious workers being executed within your Aidbox context.

Please refer to the OWASP Content Security Policy Cheat Sheet for additional guidance