Optional environment variables
JAVA_OPTS
Configure general JAVA options. For example - request and max heap size configuration.
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 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
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_*
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
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:
you don't use
_pagethe number of returned resources is less than
_count(by default is 100).
AIDBOX_ES_AUTH
Basic auth credentials for ElasticSearch. API key is not supported.
AIDBOX_ES_BATCH_SIZE
Log batch size used to optimize log shipping performance. The default value is 200
AIDBOX_ES_BATCH_TIMEOUT
Timeout to post a batch to ElasticSearch. If there is not enough records to reach full batch size
AIDBOX_ES_INDEX_PAT
Custom index format string. The default value is 'aidbox-logs'-yyyy-MM-dd.
AIDBOX_LOGS
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
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
Disable /health endpoint requests logging. Default value is false.
BOX_LOGGING_SQL_MIN__DURATION
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
Max length of a query to be logged.
AIDBOX_STDOUT_JSON
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
AIDBOX_STDOUT_GOOGLE_JSON
Produces logs in Google Logging format (see LogEntry).
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
AIDBOX_STDOUT_PRETTY
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
AIDBOX_DD_API_KEY
If provided, enables mode to push logs to DataDog
AIDBOX_DD_BATCH_SIZE
Size of log batch, used to optimize performance of log shipping. The default value is 200
AIDBOX_DD_BATCH_TIMEOUT
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
Fallback file to write logs in if uploading to DataDog fails
AIDBOX_CREATED_AT_URL
Overrides createdAt extension url, default is ex:createdAt
AIDBOX_CORRECT_AIDBOX_FORMAT
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
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
Enables _debug=policy for access policy debugging
AIDBOX_ZEN_ENTRYPOINT
Specifies entry point for loading Aidbox configuration. Example:
AIDBOX_ZEN_DEV_MODE
Enables watcher which reloads zen namespaces when they change.
AIDBOX_ZEN_PATHS
<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:
AIDBOX_EXTENSION_SCHEMA
Schema for PostgreSQL extensions. Default is current schema. See use different PostgreSQL schema section.
AIDBOX_SECURITY_AUDIT__LOG_ENABLED
Enable producing audit logs in FHIR AuditEvent format for significant events.
BOX_SEARCH_DEFAULT__PARAMS_COUNT
Overrides the default count search parameter value. 100 is the default value. The provided value should be <= 1000
BOX_SEARCH_FHIR__COMPARISONS
Use FHIR compliant date search.
BOX_SEARCH_INCLUDE_CONFORMANT
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
BOX_SEARCH_INCLUDE_ITERATE__MAX
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
false to use preferred version of zen-search (true to backward compatibility zen search)
BOX_COMPATIBILITY_VALIDATION_JSON__SCHEMA_REGEX
Enables strict date time validation in JSON schema validation engine per FHIR spec.
BOX_COMPATIBILITY_AUTH_PKCE_CODE__CHALLENGE_S256_CONFORMANT
Use conformant S256 code challenge validation scheme.
BOX_DEBUG_SU_ENABLE
Enables su request header functionalty.
BOX_FEATURES_VALIDATION_SKIP_REFERENCE
Enables skip resource reference validation functionality.
BOX_WEB_MAX__BODY
Maximum size of request body in bytes. Default is 20971520 (20 MiB)
BOX_WEB_THREAD
Count of HTTP server web workers. Default is 8
BOX_WEB_MAX__LINE
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
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
Enables synchronous terminology bundle import
BOX_FEATURES_AUTHENTICATION_INTROSPECTION_CREATE__USER
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:
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:
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:
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:
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:
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.
Telemetry
By default, Aidbox collects and sends high-level anonymous API usage statistics used solely for Aidbox improvement.
BOX_TELEMETRY_ERRORS
Disable sending anonymous errors data.
BOX_TELEMETRY_USAGE__STATS
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_STRIP__LABELS
By default, stripping is disabled. To enable it, set the env to true.
Stripping is only applied during the masking. More details about masking
Observability
Follow the link below to learn how Aidbox metrics work.
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.
Last updated