Configure Aidbox and Multibox

Aidbox is a full-featured single instance of the Aidbox FHIR server. If you are interested in multi-tenant Aidbox, consider using Multibox distribution.

All distributions can be used with standard PostgreSQL or managed PostgreSQL services.

Basic Aidbox installation consists of two components: the backend and the database. Both are released as docker images and can be pulled from HealthSamurai docker hub . For each type of Aidbox license an individual backend image is available — either Aidbox or Multibox .

Aidbox works with standard PostgreSQL 13 and higher. See PostgreSQL Requirements for details.

Recommended environment variables

JAVA_OPTS

JAVA_OPTS="<string>"

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

JAVA_OPTS="-Xms1024m -Xmx1024m"

See also: How to configure Aidbox to use a proxy

Configure performance

By default, Aidbox and Multibox runs with 8 web workers and 16 DB connection pool size.

Common recommendations:

• Box web workers count is dependent on your load profile. We recommend to set BOX_WEB_THREAD equal X2 of CPU count.
• BOX_DB_POOL_MAXIMUM__POOL__SIZE equal X2 of your BOX_WEB_THREADS.

You can configure this parameter using following environment variables.

BOX_DB_POOL_MAXIMUM_POOL_SIZE=16
BOX_WEB_THREAD=8

Aidbox usually needs 2-4 Gb of memory:

JAVA_OPTS="-Xms4096m -Xmx4096m"

Configuring SSL connection with PostgreSQL

Since 2405, 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 . See also how to use SSL .

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 using environment variable BOX_DB_EXTENSION_SCHEMA:

BOX_DB_EXTENSION_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 BOX_DB_EXTENSION_SCHEMA environment variable to set up Aidbox to use dedicated extension schema:

BOX_DB_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 BOX_DB_EXTENSION_SCHEMA and restart Aidbox.

Set up authentication keys (RSA or EC) 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 three signing algorithms: RS256, ES256, and HS256. RS256 and ES256 expect providing private key for signing JWT and public key for verifying it. HS256 needs only a secret for both operations.

Generate keypair

Aidbox supports both RSA and EC keys. Generate an RSA or EC private key and the corresponding public key.

RSA key:

openssl genrsa -traditional -out key.pem 2048
openssl rsa -in key.pem -outform PEM -pubout -out public.pem

EC key:

openssl ecparam -name prime256v1 -genkey -noout -out key.pem
openssl ec -in key.pem -pubout -out public.pem

Use these env vars to pass the keypair:

BOX_SECURITY_AUTH_KEYS_PRIVATE: "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"  # or -----BEGIN EC PRIVATE KEY-----
BOX_SECURITY_AUTH_KEYS_PUBLIC: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

You can also use YAML multi-line strings for passing values of the keys:

      BOX_SECURITY_AUTH_KEYS_PUBLIC: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtknsklLTP1y6HPtR2oYs
        ...
        ewIDAQAB
        -----END PUBLIC KEY-----

Key format requirements

Keys must be provided in full PEM format, including the BEGIN and END headers.

Common mistakes:

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_SECURITY_AUTH_KEYS_SECRET=<rand_string>

References

Refer to the following pages for the specific image description and the list of available configuration options.

You can also see the environment variables in the Settings page in AidboxUI.

If you are looking for the latest versions of the docker images or general release cycle explanation go to the Versioning page.

See also deployment documentation: