Aidbox Settings Reference

This document contains the full list of settings available in Aidbox.

General

General settings

Aidbox name

BOX_ID: "devbox"

Aidbox instance unique ID. Can be used to separate telemetry data (logs, metrics, traces) in observability systems for multiple deployments.

Instance name

BOX_INSTANCE_NAME: "Aidbox"

Provided instance name will be attached to metric labels. It is required for monitoring multiple Aidbox instances.

Root FHIR package

BOX_ROOT_FHIR_PACKAGE: "app.aidbox.main#0.0.1"

Identifier for the main Aidbox FHIR package that stores dependencies and canonical resources provided by the user.

Bootstrap FHIR package list

BOX_BOOTSTRAP_FHIR_PACKAGES: "hl7.fhir.r4.core#4.0.1"

During the first startup Aidbox loads these packages. This setting has no effect on any consecutive starts.

Format: <name1>#<version1>:<name2>#<version2>...

Init bundle

BOX_INIT_BUNDLE: "<String>"

URL of the Bundle resource in JSON format executed on Aidbox startup. Not available to edit because if file is not reachable, Aidbox will not start.

Share usage statistics with Aidbox developers

BOX_USAGE_STATS: true

Allows Aidbox to collect and send high-level API usage statistics to help improve the product.

Settings mode

BOX_SETTINGS_MODE: "read-write"

Settings mode defines the source of settings values and possibility to change them at runtime.

Enable export settings endpoint

BOX_EXPORT_SETTINGS_ENDPOINT: false

Allow user to request current Aidbox settings as a set of environment variables on /api/v1/settings/export.

Be aware, that endpoint may expose your sensitive settings.

Enable cache replication

BOX_CACHE_REPLICATION_DISABLE: false

Aidbox automatically syncs runtime cache (SearchParameters, FHIR Schemas, OperationDefinitions, etc) across multiple instances for high availability. If you configure everything at startup and don't modify metadata at runtime, you can disable cache replication to improve performance.

Aidbox modules load list

BOX_MODULE_LOAD: "<String>"

During startup Aidbox loads these modules. Format: <module-name2>,<module-name2>,<module-name3>...

Aidbox module jar

BOX_MODULE_JAR: "<String>"

Path to an Aidbox module jar files separated by ":" Format: <path1>:<path2>:<path3>...

FHIR

FHIR settings

General

General FHIR settings

Enable FHIR compliant mode

BOX_FHIR_COMPLIANT_MODE: true

Enforces FHIR compatibility when 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 BOX_WEB_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

Return 404 on deleting non-existent resources

BOX_FHIR_RETURN_404_ON_EMPTY_DELETE: false

Controls server response when deleting non-existing resources. When enabled, returns 404 (Not Found) status code instead of the default 204 (No Content). Follows FHIR REST implementation where DELETE operations on missing resources can signal resource absence rather than successful deletion.

Transaction max isolation level

BOX_FHIR_TRANSACTION_MAX_ISOLATION_LEVEL: "none"

Sets the maximum (inclusive) isolation level for transactions. Can be overridden by the x-max-isolation-level header.

Validation

Validation settings

Enable FHIR Schema validation mode

BOX_FHIR_SCHEMA_VALIDATION: true

Activates the FHIR Schema validation engine which replaces legacy ZEN and Entity/Attribute validation systems. Provides more comprehensive structure validation against the FHIR resource schemas, ensuring stronger conformance to FHIR specifications and more precise error reporting.

Enforce strict profile resolution

BOX_FHIR_VALIDATOR_STRICT_PROFILE_RESOLUTION: false

Requires all referenced profiles to be pre-loaded in Aidbox before validation. When enabled, validation fails if profiles referenced in resources are unknown to the server. Ensures complete validation integrity by preventing partial validation against unknown profiles.

Enforce strict FHIR extension resolution

BOX_FHIR_VALIDATOR_STRICT_EXTENSION_RESOLUTION: false

Requires all referenced extensions to be formally defined in profiles loaded to the server.

Bundle execution validation mode

BOX_FHIR_BUNDLE_EXECUTION_VALIDATION_MODE: "limited"

Define validation mode for FHIR Bundle execution (after POST on /fhir endpoint). Doesn't effect CRUD on Bundle resources. Doesn't effect if fhir.validation.fhir-schema-validation is disabled.

Skip FHIR reference validation

BOX_FHIR_VALIDATION_SKIP_REFERENCE: false

Bypasses validation of resource references during FHIR operations. When enabled, allows creating and updating resources containing references to non-existent target resources. Useful for staged data loading or systems with eventual consistency but may compromise referential integrity.

Correct Aidbox format

BOX_FHIR_CORRECT_AIDBOX_FORMAT: true

Transforms polymorphic extensions from FHIR format to Aidbox's internal format. When enabled, extensions like extension.*.valueString are stored as extension.0.value.string instead. Improves query performance and consistency in Aidbox-specific operations while maintaining FHIR compatibility in API responses.

createdAt extension URL

BOX_FHIR_CREATEDAT_URL: "https://aidbox.app/ex/createdAt"

Specifies the URL for the createdAt extension.

JSON schema datetime

BOX_FHIR_JSON_SCHEMA_DATETIME_REGEX: "#{:fhir-datetime}"

Enables strict datetime validation in JSON schema validation engine.

Legacy FCE package

BOX_FHIR_LEGACY_FCE_PACKAGE: "<String>"

The name and version of the package from which Aidbox first-class extensions are generated Format: package-name#package-version

Search

Search settings

Use correct range arithmetic in search

BOX_FHIR_SEARCH_COMPARISONS: true

FHIR date search is range based. That is, dates are always converted to datetime ranges and then compared.

Historically, Aidbox uses slightly different range comparison arithmetic. Turn on this setting to use FHIR comparisons.

Enable FHIR-conformant (rev)include behavior

BOX_FHIR_SEARCH_INCLUDE_CONFORMANT: true

Due to historical reasons Aidbox treats the _include and _revinclude parameters slightly differently from the behavior described in the specification (without FHIR-conformant mode on). The _(rev)include search parameter without the :iterate or :recurse modifier should only be applied to the initial ("matched") result. However, in Aidbox mode, it is also applied to the previous _(rev)include. The _(rev)include parameter with the :iterate(:recurse) modifier should be repeatedly applied to the result with included resources. However, in Aidbox mode, it only resolves cyclic references. In Aidbox mode, it is possible to search without specifying source type: GET /Patient?_include=general-practitioner, but in the FHIR-conformant mode it is not possible.

Authorize inline requests

BOX_FHIR_SEARCH_AUTHORIZE_INLINE_REQUESTS: true

Authorize inline requests (_revinclude and _include) with access policies. Learn more

Use semi join in chained searches

BOX_FHIR_SEARCH_CHAIN_SUBSELECT: true

When the search query does not use _has search parameters, use subselect instead of INNER JOIN for forward chain searches. This is a performance optimization which could require building additional indexes.

Enable FHIR composite search parameters

BOX_FHIR_SEARCH_COMPOSITE_PARAMETERS: false

Enable support for FHIR composite search parameters.

Iteration limit for (rev)include:iterate

BOX_FHIR_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.

Default search timeout

BOX_FHIR_SEARCH_DEFAULT_PARAMS_TIMEOUT: 60

Default timeout value (seconds). Also uses as timeout for the count query.

Default number of results per search page

BOX_FHIR_SEARCH_DEFAULT_PARAMS_COUNT: 100

This is the default value of the _count search parameter.

It limits number of results per page

Default search result count estimation method

BOX_FHIR_SEARCH_DEFAULT_PARAMS_TOTAL: "accurate"

FHIR search response bundle may contain a result count estimation.

SQL operator to use for token search

BOX_FHIR_SEARCH_TOKEN_OPERATOR: "@>"

Token and Reference search parameters use exact match.

Aidbox uses Postgres @> operator for this type of searches. The @> operator is the containment operator. It checks that FHIR resource contains some subresource.

The main advantage of the @> operator is that the single GIN index covers all token and reference searches. However sometimes Postgres planner can not build effecient query plan.

Alternatively in some cases it is possible to extract value directly using #>> operator. This operator extracts value from the given path. There is a limitation: path must not contain any arrays. Engines options:

JSONB query engine

BOX_FHIR_SEARCH_ENGINE: "knife"

Aidbox has two engines to search: jsonpath and jsonknife.

The engine is responsible for SQL generation for search operations. SQL by jsonpath and jsonknife is different for search parameter types: date, number, quantity, reference, string, token, uri. _lastUpdated, _createdAt senarch parameters and :missing modifier searches also differ by engine. jsonpath-engine:

jsonknife: *using indexes makes performance approximately the same

Enable support for multiple languages in search

BOX_FHIR_SEARCH_MULTILINGUAL_ENABLE: false

FHIR uses special extension to provide translations in resources. Enable this setting to turn on the _search-language parameter. This parameter (_search-language) specifies which language to use for search. i.e. which translation in a resource to use.

This feature requires Aidbox to build more complex (so possibly slower) queries. Leave this setting disabled if you don't need to search across translations.

Use Accept-Language header for search

BOX_FHIR_SEARCH_MULTILINGUAL_USE_ACCEPT_LANGUAGE_HEADER: false

Use the Accept-Language header to specify search language

See fhir.search.multilingual.enable for details.

Use main value if translation is not found

BOX_FHIR_SEARCH_MULTILINGUAL_FALLBACK: true

When the _search-language parameter is used, Aidbox uses translation in FHIR extension for search.

If this setting is enabled, Aidbox additionally uses the main value (i.e. not in translation extension)

Terminology

Terminology settings

FHIR terminology service base URL

BOX_FHIR_TERMINOLOGY_SERVICE_BASE_URL: "https://tx.health-samurai.io/fhir"

Specifies the base URL of the terminology server used for code validation and ValueSet expansion operations. Required for validating coded elements against their ValueSets and CodeSystems. When not configured, code validation is skipped entirely.

Terminology Engine

BOX_FHIR_TERMINOLOGY_ENGINE: "hybrid"

Controls how Aidbox handles terminology APIs

External Terminology Server

BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: "https://tx.health-samurai.io/fhir"

Specifies the base URL of an external terminology server to be used in 'hybrid' terminology engine mode. This setting is ignored for other modes.

Bulk Data Export

Bulk Data Export settings

Bulk storage provider

BOX_FHIR_BULK_STORAGE_PROVIDER: "<Enum>"

Storage provider for bulk export

GCP service account

BOX_FHIR_BULK_STORAGE_GCP_SERVICE_ACCOUNT: "<String>"

GCPServiceAccount resource ID for $export

GCP bucket

BOX_FHIR_BULK_STORAGE_GCP_BUCKET: "<String>"

GCP bucket name for $export

AWS service account ID

BOX_FHIR_BULK_STORAGE_AWS_ACCOUNT: "<String>"

AWS Account resource ID for $export

AWS bucket

BOX_FHIR_BULK_STORAGE_AWS_BUCKET: "<String>"

AWS S3 bucket name for $export

Azure service account ID

BOX_FHIR_BULK_STORAGE_AZURE_CONTAINER: "<String>"

Azure Container resource ID for $export

Security and Access Control

Security & Access Control settings

Grant page URL

BOX_SECURITY_GRANT_PAGE_URL: "/auth/grant"

URL of consent screen. A consent screen is an interface presented to a user during the authorization code grant flow.

Enable FHIR Audit Log

BOX_SECURITY_AUDIT_LOG_ENABLED: true

Generates structured audit logs in FHIR R4 AuditEvent format (with other FHIR versions will not be generated).

Audit Log repository URL

BOX_SECURITY_AUDIT_LOG_REPOSITORY_URL: "<String>"

Full URL of the external destination where Aidbox streams all audit events. Before setting the URL, you must enable the audit log in Aidbox. If audit log is enabled, repository URL not specified, Aidbox will store Audit Event in the PostgreSQL database.

Audit Log flush interval

BOX_SECURITY_AUDIT_LOG_FLUSH_INTERVAL: 5000

Interval time in ms to flush audit events to Audit Log Repository

Audit Log maximum flush interval

BOX_SECURITY_AUDIT_LOG_MAX_FLUSH_INTERVAL: 60000

If sending the audit event to the repository fails, the send interval gradually increases up to this value.

Audit Log batch count

BOX_SECURITY_AUDIT_LOG_BATCH_COUNT: 1000

Max count of Audit Log batch (FHIR bandle entry count).

Audit Log request headers

BOX_SECURITY_AUDIT_LOG_REQUEST_HEADERS: "<String>"

The headers for Audit Log external repository requests, formatted as HeaderName:HeaderValue\nHeaderName:HeaderValue.

Enable access control for mapping

BOX_SECURITY_IAM_MAPPING_ENABLE_ACCESS_CONTROL: false

Enable access control for /Mapping/<mapping-id>/$apply operation. If enabled, access control will be applied to the resulting transaction. If disabled, only access to $apply endpoints are verified.

Encryption API secret

BOX_SECURITY_ENCRYPT_SECRET: "<String>"

Secret key for encryption API. Learn more

Allow CORS requests

BOX_SECURITY_CORS_ENABLED: true

Enable Cross-Origin Resource Sharing (CORS) request handling.

Allow CORS requests from origins

BOX_SECURITY_CORS_ORIGINS: "*"

Comma separated list of origins [schema]://[domain]:[port] Default is wildcard value "*"

Content security policy header

BOX_SECURITY_CONTENT_SECURITY_POLICY_HEADER: "<String>"

Defines the Content Security Policy (CSP) header to enhance security by restricting resource loading. It specifies the policies for loading scripts, styles, media, fonts, and other resources.

Refer to the OWASP Content Security Policy Cheat Sheet

Recommended value:

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'; manifest-src 'self'; media-src 'self'; worker-src 'self';

Skip JWT validation

BOX_SECURITY_SKIP_JWT_VALIDATION: false

Skip JWT token validation process.

JWT public key

BOX_SECURITY_AUTH_KEYS_PUBLIC: "<String>"

RS256 signing algorithm expects providing private key for signing JWT and public key for verifying it.

JWT private key

BOX_SECURITY_AUTH_KEYS_PRIVATE: "<String>"

RS256 signing algorithm expects providing private key for signing JWT and public key for verifying it.

JWT secret

BOX_SECURITY_AUTH_KEYS_SECRET: "<String>"

HS256 signing algorithm needs only having a secret for both operations.

Auto-create users from foreign tokens

BOX_SECURITY_INTROSPECTION_CREATE_USER: false

Creates local user accounts automatically when valid external JWT tokens are presented but no matching user exists.

Auth with non-validated JWT

BOX_SECURITY_AUTH_WITH_NOT_VALIDATED_JWT: "<String>"

This configuration is used when skip-jwt-validation setting is enabled. It's a string that contains EDN object with :headers and :user-id-paths keys. For example: {:headers #{"authorization" "x-client-token"}, :user-id-paths #{[:authorization :user_id] [:my-client-token :user :id]}}

Enable LBAC

BOX_SECURITY_LBAC_ENABLED: false

Label-based Access Control engine provides a mechanism to restrict access to bundles, resources, or resource elements depending on permissions associated with a request.

Strip security labels

BOX_SECURITY_LBAC_STRIP_LABELS: false

Removes security labels from resource responses before returning them to clients. When enabled, prevents sensitive security metadata from being exposed in API responses while maintaining access control enforcement internally. Useful for hiding security implementation details from end users.

Enable organization-based hierarchical access control

BOX_SECURITY_ORGBAC_ENABLED: false

Activates hierarchical access control based on organizational structure. Restricts user access to resources based on their organizational affiliation and hierarchy position.

Enable SU header

BOX_SECURITY_DEBUG_SU_ENABLE: false

This setting enables SU header functionality. SU header allows a user to substitute User ID for the duration of the request. Only the administrator is allowed to use the SU header.

Enable Aidbox developer mode

BOX_SECURITY_DEV_MODE: true

Activates debugging features for access policy development, including the _debug=policy URL parameter and x-debug header. Returns detailed policy evaluation traces showing why requests were allowed or denied. For development environments only - not recommended for production systems.

Modules

Modules settings

Subscriptions

Google Cloud Pub/Sub subscriptions settings

Google Cloud Pub/Sub topic name

BOX_MODULE_SUBSCRIPTIONS_PUBSUB_TOPIC: "<String>"

Name of the Google Cloud Pub/Sub topic.

Google Cloud Pub/Sub project name

BOX_MODULE_SUBSCRIPTIONS_PUBSUB_PROJECT: "<String>"

Name of the Google Cloud Project which contains Pub/Sub topics and subscriptions.

Google Cloud Pub/Sub resource types

BOX_MODULE_SUBSCRIPTIONS_PUBSUB_RESOURCE_TYPES: "<String>"

Specify resource types and boxes for which to publish notifications. If not set, messages for all resource types from all boxes are published.

<rt>:?<box-id>?( <rt>:?<box-id>?)*
// Examples:
//
// Notify only on Patient or Encounter resources
// change from any box.

"Patient Encounter"

// Notify on Patient changes from boxone or boxtwo
// and about Encounter from any box.

"Patient:boxone Patient:boxtwo Encounter"

Google Cloud Pub/Sub service account email

BOX_MODULE_SUBSCRIPTIONS_PUBSUB_SERVICE_ACCOUNT_EMAIL: "<String>"

Email of the Google Cloud Pub/Sub service account.

Google Cloud Pub/Sub service account private key

BOX_MODULE_SUBSCRIPTIONS_PUBSUB_SERVICE_ACCOUNT_PRIVATE_KEY: "<String>"

Private key of the Google Cloud Pub/Sub service account.

Google Cloud Pub/Sub publish before save

BOX_MODULE_SUBSCRIPTIONS_PUBSUB_BEFORE_SAVE: false

If true, the resource will be published to the Pub/Sub topic before saving it to the database.

Google Cloud Pub/Sub emulator URL

BOX_MODULE_SUBSCRIPTIONS_PUBSUB_EMULATOR_URL: "<String>"

URL of the Google Cloud Pub/Sub emulator. If set, the emulator will be used instead of the real Pub/Sub service.

Notebooks

Aidbox notebooks settings

Notebook repository URL

BOX_MODULE_NOTEBOOK_REPO_URL: "https://aidbox.app"

Set repository to fetch published notebooks

Mail Provider

Mail Provider settings

Default provider type

BOX_MODULE_PROVIDER_DEFAULT_TYPE: "<String>"

Specifies the email service provider used for system-generated communications.

Default provider from address

BOX_MODULE_PROVIDER_DEFAULT_FROM: "<String>"

From address for the default provider

Default provider username

BOX_MODULE_PROVIDER_DEFAULT_USERNAME: "<String>"

Username for the default provider

Default provider password

BOX_MODULE_PROVIDER_DEFAULT_PASSWORD: "<String>"

Password for the default provider

Default provider URL

BOX_MODULE_PROVIDER_DEFAULT_URL: "<String>"

URL for the default provider

Default provider port

BOX_MODULE_PROVIDER_DEFAULT_PORT: "<String>"

Port for the default provider

Default provider SSL

BOX_MODULE_PROVIDER_DEFAULT_SSL: false

Enable SSL for the default provider

Default provider TLS

BOX_MODULE_PROVIDER_DEFAULT_TLS: false

Enable TLS for the default provider

Default provider host

BOX_MODULE_PROVIDER_DEFAULT_HOST: "<String>"

Host for the default provider

Mailgun provider from address

BOX_MODULE_PROVIDER_MAILGUN_FROM: "<String>"

From address for the Mailgun provider

Mailgun provider username

BOX_MODULE_PROVIDER_MAILGUN_USERNAME: "<String>"

Username for the Mailgun provider

Mailgun provider password

BOX_MODULE_PROVIDER_MAILGUN_PASSWORD: "<String>"

Password for the Mailgun provider

Mailgun provider URL

BOX_MODULE_PROVIDER_MAILGUN_URL: "<String>"

URL for the Mailgun provider

Postmark provider from address

BOX_MODULE_PROVIDER_POSTMARK_FROM: "<String>"

From address for the Postmark provider

Postmark provider API key

BOX_MODULE_PROVIDER_POSTMARK_API_KEY: "<String>"

API key for the Postmark provider

SMTP provider from address

BOX_MODULE_PROVIDER_SMTP_FROM: "<String>"

From address for the SMTP provider

SMTP provider host

BOX_MODULE_PROVIDER_SMTP_HOST: "<String>"

Host for the SMTP provider

SMTP provider password

BOX_MODULE_PROVIDER_SMTP_PASSWORD: "<String>"

Password for the SMTP provider

SMTP provider port

BOX_MODULE_PROVIDER_SMTP_PORT: "<String>"

Port for the SMTP provider

SMTP provider SSL

BOX_MODULE_PROVIDER_SMTP_SSL: false

Enable SSL for the SMTP provider

SMTP provider TLS

BOX_MODULE_PROVIDER_SMTP_TLS: false

Enable TLS for the SMTP provider

SMTP provider username

BOX_MODULE_PROVIDER_SMTP_USERNAME: "<String>"

Username for the SMTP provider

SMARTbox

SMARTbox settings

Sandbox URL

BOX_MODULE_SMARTBOX_SANDBOX_URL: "<String>"

URL for accessing sandbox environment

Terms of use URL

BOX_MODULE_SMARTBOX_TERMS_OF_USE_URL: "<String>"

URL for accessing terms of use

Sandbox basic

BOX_MODULE_SMARTBOX_SANDBOX_BASIC: "<String>"

Basic authentication credentials for sandbox

Sandbox admin

BOX_MODULE_SMARTBOX_SANDBOX_ADMIN: "<String>"

Admin credentials for sandbox access

Session logs link

BOX_MODULE_SMARTBOX_SESSION_LOGS_LINK: "<String>"

Link to access session logs

MDM

MDM settings

Default MDM model

BOX_MODULE_DEFAULT_PATIENT_MODEL: "<String>"

The default MDM model used for $match operation. Will be used if no model is specified with the model query parameter.

MCP

MCP settings

Enable MCP server

BOX_MODULE_MCP_SERVER_ENABLED: false

Enable MCP server working through SSE protocol

Forms

Forms settings

Questionnaire.url prefix

BOX_MODULE_SDC_BUILDER_FORM_URL_PREFIX: "http://forms.aidbox.io/questionnaire/"

URL prefix that will be used in URL generation for new forms

OpenAI API key

BOX_MODULE_SDC_OPENAI_API_KEY: "<String>"

API key for OpenAI service

Gemini API key

BOX_SDC_GEMINI_API_KEY: "<String>"

API key for Gemini service

Default language for UI

BOX_MODULE_SDC_LANGUAGE: "en"

Language used as default in Form Builder and Form Renderer

Default form theme

BOX_MODULE_SDC_THEME: "<String>"

Theme that will be used in all forms

Hide builder's back button

BOX_MODULE_SDC_BUILDER_HIDE_BACK_BUTTON: false

Hide back button in UI Form Builder

Form's redirect-on-submit URL

BOX_MODULE_SDC_FORM_REDIRECT_ON_SUBMIT: "<String>"

Redirect URI that will be used on form submit/amend button click

Form's redirect-on-save URL

BOX_MODULE_SDC_FORM_REDIRECT_ON_SAVE: "<String>"

Redirect URI that will be used on form save/close button click

Enable strict access control for sdc operations

BOX_MODULE_SDC_STRICT_ACCESS_CONTROL: true

Enable strict access control for operations(like populate/submit/reference-lookup) that can request different FHIR resources

GraphQL

GraphQL settings

Warmup GraphQL cache on startup

BOX_MODULE_GRAPHQL_WARMUP_ON_STARTUP: false

Warmup GraphQL API cache on startup. When false, cache will be warmed up on first request.

Allow reference to any resource

BOX_MODULE_GRAPHQL_REFERENCE_ANY: false

Enable GraphQL API (rev)include for reference with target - any

GraphQL timeout

BOX_MODULE_GRAPHQL_TIMEOUT: 60

GraphQL API query timeout in seconds: Set to zero to disable.

GraphQL access control mode

BOX_MODULE_GRAPHQL_ACCESS_CONTROL: "disabled"

Access control in GraphQL API

Webpush

Webpush settings

Public Key

BOX_MODULE_WEBPUSH_PUBLIC_KEY: "<String>"

ECDH/BC/prime256v1 Public Key

Private Key

BOX_MODULE_WEBPUSH_PRIVATE_KEY: "<String>"

ECDH/BC/prime256v1 Private Key

JWT mail

BOX_MODULE_WEBPUSH_JWT_MAIL: "<String>"

JWT.sub field value needs to be either a URL or a mailto email address. If a push service needs to reach out to sender, it can find contact information from the JWT.

Database

Database settings

Primary

Primary database settings

Database host

BOX_DB_HOST: "postgres"

Database host address.

Database port

BOX_DB_PORT: 5432

Database port.

Database name

BOX_DB_DATABASE: "aidbox"

The database name. postgres name is not allowed.

Database user

BOX_DB_USER: "aidbox"

The database username.

Database password

BOX_DB_PASSWORD: "<pg-password>"

A password of database role name.

Install PostgreSQL extensions at startup

BOX_DB_INSTALL_PG_EXTENSIONS: true

Automatically installs PostgreSQL extensions (pgcrypto, unaccent, pg_trgm, fuzzystrmatch) during server startup.

Database extension schema

BOX_DB_EXTENSION_SCHEMA: "<String>"

Schema for PostgreSQL extensions. Default is current schema.

ViewDefinition materialization schema

BOX_VIEW_DEFINITION_SCHEMA: "sof"

Schema for storing ViewDefinition materialization. Changing this setting does not affect already materialized views; it applies only to new ones. It is recommended to use a dedicated schema for ViewDefinition to avoid potential collisions.

Pool connection timeout

BOX_DB_POOL_CONNECTION_TIMEOUT: 30000

Maximum wait time (in milliseconds) for a database connection from the pool before timing out.

Pool connection init SQL

BOX_DB_POOL_CONNECTION_INIT_SQL: "select 1"

Specifies a SQL statement that will be executed after every new connection creation before adding it to the pool.

Pool idle timeout

BOX_DB_POOL_IDLE_TIMEOUT: 10000

Maximum timeout (in milliseconds) to close idle connection.

Pool minimum idle

BOX_DB_POOL_MINIMUM_IDLE: 0

Minimum number of connections.

Pool size

BOX_DB_POOL_MAXIMUM_POOL_SIZE: 8

Maximum number of simultaneous database connections.

Propagate DB health status to Aidbox

BOX_PROPAGATE_DB_HEALTH_STATUS_TO_BOX: false

If enabled, the health status of the database will be reflected in the overall health status of Aidbox. If the database is unhealthy, Aidbox will also be considered unhealthy.

NOTE: Aidbox caches DB connections. That may cause inconsistencies when DB status is already fail but Aidbox instance still has valid connections.

Read-only replica

Read-only database replica settings

Read-only replica enable

BOX_DB_RO_REPLICA_ENABLED: false

Enable options to process requests to read-only db replica. If enabled you should define: db.ro-replica.database, db.ro-replica.host, db.ro-replica.port, db.ro-replica.user, and db.ro-replica.password.

Database name

BOX_DB_RO_REPLICA_DATABASE: "<String>"

The database name. postgres name is not allowed.

Database host

BOX_DB_RO_REPLICA_HOST: "<String>"

AidboxDB host address.

Database port

BOX_DB_RO_REPLICA_PORT: "<Int>"

The database port number.

Database user

BOX_DB_RO_REPLICA_USER: "<String>"

The database username.

Database password

BOX_DB_RO_REPLICA_PASSWORD: "<String>"

The database password.

Database extension schema

AIDBOX_EXTENSION_SCHEMA: "<String>"

The database extension schema.

Maximum wait time

BOX_DB_RO_REPLICA_POOL_CONNECTION_TIMEOUT: 30000

Maximum wait time (in milliseconds) for a database connection from the pool before timing out.

Pool idle timeout

BOX_DB_RO_REPLICA_POOL_IDLE_TIMEOUT: 10000

Maximum timeout (in milliseconds) to close idle connection.

Pool minimum idle

BOX_DB_RO_REPLICA_POOL_MINIMUM_IDLE: 0

Minimum number of connections.

Pool size

BOX_DB_RO_REPLICA_POOL_MAXIMUM_POOL_SIZE: 8

Maximum number of simultaneous database connections.

Pool connection init SQL

BOX_DB_RO_REPLICA_POOL_CONNECTION_INIT_SQL: "select 1"

The pool connection initialization SQL statement.

Web Server

Web Server settings

Base URL

BOX_WEB_BASE_URL: "<base-url>"

Base URL is the URL Aidbox is available at. It consists of scheme (HTTP, HTTPS), domain, port (optional) and URL path (optional). Trailing slash is not allowed.

Web server port

BOX_WEB_PORT: 8888

Web server port that Aidbox listens on.

Web thread count

BOX_WEB_THREAD: 8

The number of web server workers in Aidbox. The number of workers determines how many concurrent web requests Aidbox can handle.

HTTP initial line max length

BOX_WEB_MAX_LINE: 8192

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

Request max body size

BOX_WEB_MAX_BODY: 20971520

Maximum size of the request body in bytes.

Observability

Observability settings

Logs

Logs settings

Disable health logs

BOX_OBSERVABILITY_DISABLE_HEALTH_LOGS: false

Disable /health endpoint requests logging. Default value is false

Log file path

BOX_OBSERVABILITY_LOG_FILE_PATH: "<String>"

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.

Logs max lines

BOX_OBSERVABILITY_LOG_FILE_MAX_LINES: 10000

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

Logging SQL min duration

BOX_OBSERVABILITY_SQL_MIN_DURATION: -1

Threshold for logging only long queries. Analogous from PostgreSQL. Log only requests whose execution time exceeds the specified number of milliseconds.

Logging SQL max length

BOX_OBSERVABILITY_SQL_MAX_LENGTH: 500

Max length of a query to be logged.

Metrics

Metrics settings

Metrics server port

BOX_METRICS_PORT: "<Int>"

Port on which Aidbox will expose metrics. To disable metrics server, leave this setting empty

Enable Postgres metrics

BOX_OBSERVABILITY_METRICS_ENABLE_POSTGRES_METRICS: true

Controls whether to provide metrics related to PostgreSQL

Stdout

Stdout settings

Stdout log level

BOX_OBSERVABILITY_STDOUT_LOG_LEVEL: "<Enum>"

Controls stdout with specified logs level. Possible values: off, fatal, error, warn, info, debug, trace, all, true By setting one of these levels you would also get all the levels 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).

Pretty print log level

BOX_OBSERVABILITY_STDOUT_PRETTY_LOG_LEVEL: "warn"

Controls pretty print of logs to stdout with specified level. Possible values: off, fatal, error, warn, info, debug, trace, all, true By setting one of these levels you would also get all the levels 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).

Google log level

BOX_OBSERVABILITY_STDOUT_GOOGLE_LOG_LEVEL: "<Enum>"

Produces in Google Logging format with specified log level. Possible values: off, fatal, error, warn, info, debug, trace, all, true By setting one of these levels you would also get all the levels 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).

Loki

Grafana Loki settings

Loki URL

BOX_OBSERVABILITY_LOKI_URL: "<String>"

Loki URL to enable Aidbox logs uploading into Loki

Loki batch size

BOX_OBSERVABILITY_LOKI_BATCH_SIZE: "<String>"

Loki batch size for log uploading. Aidbox uploads logs when either at least specific observability.loki.batch-size collected or time passed from previous log uploading exceeds observability.loki.batch-timeout.

Loki batch timeout

BOX_OBSERVABILITY_LOKI_BATCH_TIMEOUT: "<Int>"

How long to wait before uploading Aidbox uploads logs when either at least observability.loki.batch-size entries collected or time passed from previous log uploading exceeds observability.loki.batch-timeout.

Loki stream

BOX_OBSERVABILITY_LOKI_STREAM: "<String>"

Stream refers to the labels or metadata associated with a log stream Is defined by a unique set of labels, which serve as the stream key. For example: {"box": "aidbox"}

Datadog

Datadog settings

Datadog API Key

BOX_OBSERVABILITY_DATADOG_API_KEY: "<String>"

Datadog API Key.

Datadog regional site

BOX_OBSERVABILITY_DATADOG_SITE: "<Enum>"

The regional site for a Datadog customer.

Datadog log tags

BOX_OBSERVABILITY_DATADOG_TAGS: "<String>"

Tags associated with your logs. Convenient for transferring the name of the environment. For example env:staging.

Datadog log file path

BOX_OBSERVABILITY_DATADOG_LOGS: "<String>"

Fallback file to write logs in if uploading to Datadog fails

Datadog log batch size

BOX_OBSERVABILITY_DATADOG_BATCH_SIZE: "<Int>"

How many log entries to collect before uploading. Aidbox uploads logs when either at least specific observability.datadog.batch-size collected or time passed from previous log uploading exceeds observability.datadog.batch-timeout.

Datadog log batch timeout

BOX_OBSERVABILITY_DATADOG_BATCH_TIMEOUT: "<Int>"

How long to wait before uploading Aidbox uploads logs when either at least specific observability.datadog.batch-size collected or time passed from previous log uploading exceeds observability.datadog.batch-timeout.

Elastic

Elastic settings

Elastic Search auth

BOX_OBSERVABILITY_ELASTIC_SEARCH_AUTH: "<String>"

Format: <user>:<password> Basic auth credentials for ElasticSearch. API key is not supported.

Elastic Search URL

BOX_OBSERVABILITY_ELASTIC_SEARCH_URL: "<String>"

If provided, enables mode to push logs to ElasticSearch

Elastic Search batch size

BOX_OBSERVABILITY_ELASTIC_BATCH_SIZE: "<Int>"

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