JAVA_OPTS="<string>"
Configure general JAVA options. For example - request and max heap size configuration.
JAVA_OPTS="-Xms1024m -Xmx1024m"
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=<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]
{% hint style="info" %} Examples:
AIDBOX_BASE_URL=http://fhir.example.com
AIDBOX_BASE_URL=http://fhir.example.com:8080
AIDBOX_BASE_URL=http://fhir.example.com/aidbox
{% endhint %}
AIDBOX_DB_PARAM_<parameter name>=<parameter value>
Parameters prefixed with AIDBOX_DB_PARAM_ will be passed to JDBC PostgreSQL connection string.
If provided, enables mode to push logs to ElasticSearch.
box_search_default__params_total=<value>
value is one of: none, estimate, accurate.
Sets the default total search parameter value.
{% hint style="warning" %}
if you use box_search_default__params_total=none you still get totalwhen:
- you don't use
_page - the number of returned resources is less than
_count(by default is 100). {% endhint %}
AIDBOX_ES_AUTH=<user>:<password>
Basic auth credentials for ElasticSearch. API key is not supported.
AIDBOX_ES_BATCH_SIZE=<size>
Log batch size used to optimize log shipping performance. The default value is 200
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=<format>
Custom index format string. The default value is 'aidbox-logs'-yyyy-MM-dd.
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=<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=<boolean>
Disable /health endpoint requests logging. Default value is false.
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=<integer>
Max length of a query to be logged.
AIDBOX_INSTALL_PG_EXTENSIONS=<boolean>
Says Aidbox to install PostgreSQL extensions at startup time. The default value is true.
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).
{"sql":"SELECT 1","d":2,"ts":"2022-10-26T10:59:59.825Z","w":"main","ev":"db/q"}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).
{"sql":"SELECT 1","d":2,"timestamp":"2022-10-26T10:59:59.825Z","severity":"INFO","w":"main","ev":"db/q"}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).
11:01:12 main [1ms] SELECT 1
AIDBOX_DD_API_KEY=true
If provided, enables mode to push logs to DataDog
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=<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=<filepath>
Fallback file to write logs in if uploading to DataDog fails
AIDBOX_CREATED_AT_URL=<url>
Overrides createdAt extension url, default is ex:createdAt
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=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=true
Enables _debug=policy for access policy debugging
AIDBOX_ZEN_ENTRYPOINT=<entrypoint>
Specifies entry point for loading Aidbox configuration. Example:
AIDBOX_ZEN_ENTRYPOINT=main/box
AIDBOX_ZEN_DEV_MODE=true
Enables watcher which reloads zen namespaces when they change.
AIDBOX_ZEN_PATHS=<source>:<format>:<path>[,<source>:<format>:<path>]*
<source> is either url, or path.
urlis used to load project from remote locationpathis 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=<schema>
Schema for PostgreSQL extensions. Default is current schema. See use different PostgreSQL schema section.
AIDBOX_SECURITY_AUDIT__LOG_ENABLED=true
Enable producing audit logs in FHIR AuditEvent format for significant events.
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=true
Use FHIR compliant date search.
BOX_SEARCH_INCLUDE_CONFORMANT=true
When set to true, the behavior of _include and _revinclude becomes FHIR conformant:
- Without the :recur or :iterate modifier _(rev)include is only applied to the initial result.
- With the :recur or :iterate modifier _(rev)include is repeatedly applied to the resources found in the previous step.
BOX_SEARCH_AUTHORIZE_INLINE_REQUESTS=true
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=falsefalse to use preferred version of zen-search (true to backward compatibility zen search)
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=true
Use conformant S256 code challenge validation scheme.
BOX_DEBUG_SU_ENABLE=true
Enables su request header functionalty.
BOX_FEATURES_VALIDATION_SKIP_REFERENCE=true
Enables skip resource reference validation functionality.
BOX_WEB_MAX__BODY=<max-size-bytes>
Maximum size of request body in bytes. Default is 20971520 (20 MiB)
BOX_WEB_THREAD=<count-of-web-worker-threads>
Count of HTTP server web workers. Default is 8
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=true
Allow CORS requests
BOX_WEB_CORS_ORIGINS=*
Comma-separated list of allowed origins [schema]://[domain]:[port]
The default value is wildcard "*"
BOX_FEATURES_TERMINOLOGY_IMPORT_SYNC=true
Enables synchronous terminology bundle import
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=<boolean>
Warmup graphql caches on startup
BOX_FEATURES_GRAPHQL_TIMEOUT=<integer>
Sets timeout for graphql queries in seconds. Default value is 60.
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=<boolean>
If enabled, Aidbox synchronizes managed index on startup.
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
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
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
, jsquery
, pg_stat_statements
, pg_trgm
, pgcrypto
, unaccent;
Then change AIDBOX_EXTENSION_SCHEMA and restart Aidbox.
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.
{% hint style="warning" %} 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. {% endhint %}
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-----
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>
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
By default, Aidbox collects and sends high-level anonymous API usage statistics used solely for Aidbox improvement.
BOX_TELEMETRY_ERRORS=false
Disable sending anonymous errors data.
BOX_TELEMETRY_USAGE_STATS=false
Disable sending anonymous API usage statistics.
The Security Labels access control feature is disabled by default. To enable it, set the env to true.
BOX_FEATURES_SECURITY__LABELS_ENABLE=trueBy default, stripping is disabled. To enable it, set the env to true.
BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS=true{% hint style="info" %} Stripping is only applied during the masking. More details about masking {% endhint %}
Follow the link below to learn how Aidbox metrics work.
{% content-ref url="../../../modules/observability/metrics/" %} metrics {% endcontent-ref %}
BOX_METRICS_PORT
Defines the port which will be used to expose metrics.
BOX_METRICS_POSTGRES_ON
If you have a different pg exporter, disable Aidbox PostgreSQL metrics to avoid metrics duplication by setting the env to false.
BOX_METRICS_POSTGRES_ON=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.