Optional environment variables
AIDBOX_BASE_URL
AIDBOX_BASE_URL=<url>
URL to use in links between resources.
Default is
http://localhost:[AIDBOX_PORT]
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 total
when:
you don't use
_page
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"
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_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_DEVLOGS
AIDBOX_DEVLOGS=true
If provided, pushes logs into _logs table of aidboxdb. Can be useful for testing and debugging
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>
entrypoint
is in format specified here.
Specifies entry point for loading Aidbox configuration.
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 locationpath
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.
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_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 functionalty.
BOX_FEATURES_VALIDATION_SKIP_REFERENCE
BOX_FEATURES_VALIDATION_SKIP_REFERENCE=true
Enables skip resource reference validation functionality.
BOX_WEB_MAX__BODY
BOX_WEB_MAX__BODY=<max-size-bytes>
Maximum size of request body in bytes. Default is 8388608 (8 MiB)
BOX_WEB_THREAD
BOX_WEB_THREAD=<count-of-web-worker-threads>
Count of HTTP server web workers. Default is 8
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
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
, jsquery
, 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 -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.
Last updated
Was this helpful?