Aidbox User Docs
Run Aidbox locallyRun Aidbox in SandboxTalk to us Ask community
  • Aidbox FHIR platform documentation
    • Features
    • Architecture
  • Getting Started
    • Run Aidbox in Sandbox
    • Run Aidbox locally
    • Run Aidbox on AWS
    • Upload Sample Data
  • Tutorials
    • CRUD, Search Tutorials
      • Delete data
      • Set up uniqueness in Resource
      • Search Tutorials
        • Custom SearchParameter tutorial
        • Create custom Aidbox Search resource
        • Multilingual search tutorial
        • Migrate from Aidbox SearchParameter to FHIR SearchParameter
        • Change sort order by locale collation
    • Bulk API Tutorials
      • 🎓Synthea by Bulk API
      • 🎓$dump-sql tutorial
    • Security & Access Control Tutorials
      • Allow patients to see their own data
      • Restrict operations on resource type
      • Relationship-based access control
      • Creating user & set up full user access
      • Restricting Access to Patient Data
      • Create and test access control
      • RBAC
        • Flexible RBAC built-in to Aidbox
        • RBAC with JWT containing role
        • RBAC with ACL
      • Set-up token introspection
      • Prohibit user to login
      • Managing Admin Access to the Aidbox UI Using Okta Groups
      • Run Multibox locally
      • How to enable labels-based access control
      • How to enable patient data access API
      • How to enable SMART on FHIR on Patient Access API
      • How to enable hierarchical access control
      • How to configure Audit Log
      • How is an HTTP request processed in Aidbox
      • How to configure SSO with another Aidbox instance to access Aidbox UI
      • How to configure SSO with Okta to access Aidbox UI
      • How to configure sign-in with Apple for access to the Aidbox UI
      • How to configure Azure AD SSO for access to the Aidbox UI
      • How to configure Microsoft AD FS for access to the Aidbox UI
      • How to configure Azure AD SSO with certificate authentication for access to the Aidbox UI
      • How to configure GitHub SSO for access to Aidbox UI
      • How to configure Keycloak for access for AidboxUI
      • How to implement Consent-based Access Control using FHIR Search and Aidbox Access Policy
      • Debug Access Control
      • AccessPolicy best practices
      • How to configure Basic Auth flow
      • How to configure Authorization Code Grant
      • How to configure Client Credentials Grant
      • How to configure Implicit Grant
      • How to configure Token Exchange
      • How to configure Resource Owner Grant flow
      • Configuring Two Factor Authentication in Aidbox Identity Provider
      • SSO with external OAuth identity provider
    • Terminology Tutorials
      • Load ICD-10 terminology into Aidbox
      • Uploading IG terminology content to external FHIR terminology server
    • Validation Tutorials
      • Upload FHIR Implementation Guide
        • Environment Variable
        • Aidbox UI
          • IG Package from Aidbox Registry
          • Public URL to IG Package
          • Local IG Package
        • Aidbox FHIR API
        • UploadFIG Tool
      • ISiK
      • Carin BB
      • US Core
      • Davinci Pdex
      • mCode
    • Integration Toolkit Tutorials
      • Postmark integration tutorial
      • Mailgun integration tutorial
    • Subscriptions Tutorials
      • Kafka AidboxTopicDestination
      • Tutorial: produce QuestionnaireResponse to Kafka topic
      • GCP Pub/Sub AidboxTopicDestination
      • Webhook AidboxTopicDestination
      • AidboxTopicSubscription NATS tutorial
    • Other tutorials
      • Run Aidbox with FHIR R6
      • Migrate from Multibox to Aidbox
      • SDC with Custom Resources
      • How to create FHIR NPM package
      • Migrate from legacy licence portal to Aidbox portal
      • Set up Aidbox with Postman
      • How to run Aidbox in GCP Cloud Run
  • Overview
    • Licensing and Support
    • Aidbox user portal
      • Projects
      • Licenses
      • Members
    • Aidbox UI
      • Aidbox Notebooks
      • REST Console
      • Database Console
      • Attrs stats
      • DB Tables
      • DB Queries
    • Versioning
    • Release Notes
    • FAQ
    • Contact us
  • Configuration
    • Settings
    • Configure Aidbox and Multibox
    • Init Bundle
  • API
    • REST API
      • CRUD
        • Create
        • Read
        • Update
        • Patch
        • Delete
      • FHIR Search
        • SearchParameter
        • Include and Revinclude
        • Chaining
      • Aidbox Search
      • Bundle
      • History
      • $everything on Patient
      • Other
        • Aidbox & FHIR formats
        • Capability Statement
        • $document
        • Observation/$lastn
        • $validate
        • SQL endpoints
        • $matcho
        • $to-format
        • Aidbox version
        • Health check
    • Bulk API
      • Configure Access Policies for Bulk API
      • $dump
      • $dump-sql
      • $dump-csv
      • $export
      • $load & /fhir/$load
      • $import & /fhir/$import
      • aidbox.bulk data import
      • Bulk import from an S3 bucket
    • Batch/Transaction
    • GraphQL API
    • Other APIs
      • Plan API
        • Provider Directory API
          • Practitioner
          • PractitionerRole
          • Organization
          • OrganizationAffiliation
        • Plan API Overview
      • Archive/Restore API
        • create-archive
        • restore-archive
        • prune-archived-data
        • delete-archive
      • ETAG support
      • Cache
      • Changes API
      • RPC API
      • Sequence API
      • Encryption API
      • Batch Upsert
  • Access Control
    • Overview
    • Identity Management
      • User Management
      • Application/Client Management
    • Authentication
      • Basic HTTP Authentication
      • OAuth 2.0
      • Token Introspector
      • SSO with External Identity Provider
    • Authorization
      • Access Policies
      • SMART on FHIR
        • SMART Client Authorization
          • SMART App Launch
          • SMART Backend services
        • SMART Client Authentication
          • SMART: Asymmetric (/"private key JWT") authentication
          • SMART: Symmetric (/"client secret") authentication
        • SMART: Scopes for Limiting Access
        • Pass Inferno tests with Aidbox
        • Example: SMART App Launch using Aidbox and Keycloak
        • Example: SMART App Launch using Smartbox and Keycloak
      • Scoped API
        • Organization-based hierarchical access control
        • Compartments API
        • Patient data access API
      • Label-based Access Control
    • Audit & Logging
  • Modules
    • Profiling and validation
      • FHIR Schema Validator
        • Aidbox FHIR IGs Registry
        • Setup Aidbox with FHIR Schema validation engine
      • Skip validation of references in resource using request header
      • Asynchronous resource validation
    • Observability
      • Getting started
        • Run Aidbox with OpenTelemetry locally
        • How to export telemetry to the OTEL collector
      • Logs
        • How-to guides
          • OpenTelemetry logs
          • Elastic Logs and Monitoring Integration
          • Datadog Log management integration
          • Loki Log management integration
        • Tutorials
          • Log analysis and visualization tutorial
          • Export logs to Datadog tutorial
        • Extending Aidbox Logs
        • Technical reference
          • Log appenders
          • Log transformations
          • Log Schema
          • OTEL logs exporter parameters
      • Metrics
        • How-to guides
          • How to export metrics to the OTEL collector
          • Use Aidbox Metrics Server
          • Set-up Grafana integration
        • Technical reference
          • OpenTelemetry Metrics
          • OTEL metrics exporter parameters
      • Traces
        • How to use tracing
        • OTEL traces exporter parameters
    • Subscriptions
      • Aidbox topic-based subscriptions
      • Aidbox SubSubscriptions
    • Aidbox Forms
      • Getting started
      • Aidbox Forms Interface
      • Aidbox UI Builder
        • UI Builder Interface
        • Form creation
          • Form Settings
          • Widgets
          • Components
          • Versioning
          • Form customisation in Theme Editor
          • Form signature
          • How-to guides
            • How to: populate forms with data
            • How to extract data from forms
            • How to calculate form filling percentage
          • Multilingual forms
          • FHIRPath Editor
        • Import Questionnaire
        • Form sharing
        • Printing forms
          • Template-based PDF generation
        • FHIR versions
        • Offline forms
        • Embedding
          • Request Interception
        • Configuration
        • Forms multitenancy
        • Building reports using SQL on FHIR
        • Integration with external terminology servers
        • External FHIR servers as a data backend
        • Store attachments in S3-like storages
      • Access Control in Forms
      • Audit Logging in Forms
      • Aidbox Form Gallery
    • Define extensions
      • Extensions using StructureDefinition
      • Extensions using FHIRSchema
    • Custom Resources
      • Custom resources using FHIR Schema
      • Custom resources using StructureDefinition
      • Migrate to FHIR Schema
        • Migrate custom resources defined with Entity & Attributes to FHIR Schema
        • Migrate custom resources defined with Zen to FHIR Schema
    • Aidbox terminology module
      • Concept
        • $translate-concepts
        • Handling hierarchies using ancestors
      • ValueSet
        • ValueSet Expansion
        • ValueSet Code Validation
        • Create a ValueSet
      • CodeSystem
        • CodeSystem Concept Lookup
        • CodeSystem Subsumption testing
        • CodeSystem Code Composition
      • Import external terminologies
        • Import flat file (/CSV)
        • $import operation
        • Ready-to-use terminologies
      • $translate on ConceptMap
    • SQL on FHIR
      • Defining flat views with View Definitions
      • Query data from flat views
      • Reference
    • Integration toolkit
      • C-CDA / FHIR Converter
        • List of supported templates
          • Admission Diagnosis Section (/V3)
          • Advance Directives Section (/entries optional) (/V3)
          • Advance Directives Section (/entries required) (/V3)
          • Allergies and Intolerances Section (/entries optional) (/V3)
          • Allergies and Intolerances Section (/entries required) (/V3)
          • Assessment Section
          • Chief Complaint Section
          • Chief Complaint and Reason for Visit Section
          • Complications Section (/V3)
          • Course of Care Section
          • DICOM Object Catalog Section - DCM 121181
          • Default Section Rules
          • Discharge Diagnosis Section (/V3)
          • Document Header
          • Encounters Section (/entries optional) (/V3)
          • Encounters Section (/entries required) (/V3)
          • Family History Section (/V3)
          • Functional Status Section (/V2)
          • General Status Section
          • Goals Section
          • Health Concerns Section (/V2)
          • History of Present Illness Section
          • Hospital Consultations Section
          • Hospital Course Section
          • Hospital Discharge Instructions Section
          • Hospital Discharge Physical Section
          • Hospital Discharge Studies Summary Section
          • Immunizations Section (/entries optional) (/V3)
          • Immunizations Section (/entries required) (/V3)
          • Medical (/General) History Section
          • Medical Equipment Section (/V2)
          • Medications Administered Section (/V2)
          • Medications Section (/entries optional) (/V2)
          • Medications Section (/entries required) (/V2)
          • Mental Status Section (/V2)
          • Notes
          • Nutrition Section
          • Objective Section
          • Operative Note Fluids Section
          • Operative Note Surgical Procedure Section
          • Past Medical History (/V3)
          • Payers Section (/V3)
          • Plan of Treatment Section (/V2)
          • Postprocedure Diagnosis Section (/V3)
          • Preoperative Diagnosis Section (/V3)
          • Problem Section (/entries optional) (/V3)
          • Problem Section (/entries required) (/V3)
          • Procedure Description Section
          • Procedure Disposition Section
          • Procedure Estimated Blood Loss Section
          • Procedure Implants Section
          • Procedure Specimens Taken Section
          • Procedures Section (/entries optional) (/V2)
          • Procedures Section (/entries required) (/V2)
          • Reason for Visit Section
          • Results Section (/entries optional) (/V3)
          • Results Section (/entries required) (/V3)
          • Review of Systems Section
          • Social History Section (/V3)
          • Vital Signs Section (/entries optional) (/V3)
          • Vital Signs Section (/entries required) (/V3)
        • How to deploy the service
        • Producing C-CDA documents
        • How to customize conversion rules
      • HL7 v2 Integration
        • HL7 v2 integration with Aidbox Project
        • Mappings with lisp/mapping
      • X12 message converter
      • Analytics
        • Power BI
      • Mappings
      • Email Providers integration
        • Setup SMTP provider
    • SMARTbox | FHIR API for EHRs
      • Get started
        • Set up Smartbox locally
        • Deploy Smartbox with Kubernetes
      • (/g)(/10) Standardized API for patient and population services
      • The B11 Decision Support Interventions
        • Source attributes
        • Feedback Sections
      • How-to guides
        • Pass Inferno tests with Smartbox
        • Perform EHR launch
        • Pass Inferno Visual Inspection and Attestation
        • Revoke granted access
        • Set up EHR-level customization
        • Check email templates
        • Setup email provider
        • Register users
        • Set up SSO with Auth0
        • Publish Terms of Use link onto the documentation page
        • Find out what resources were exported during the $export operation
        • Find documentation endpoint
      • Background information
        • Considerations for Testing with Inferno ONC
        • Adding Clients for Inferno tests
        • Multitenancy approach
        • What is Tenant
        • Email templating
    • ePrescription
      • Getting started
      • Authentication with mTLS
      • Pharmacies synchronization
      • Prescribing
        • NewRx Message
        • CancelRx Message
        • How to test Callback
      • Directory
        • DirectoryDownload Message
        • GetProviderLocation Message
        • AddProviderLocation Message
        • UpdateProviderLocation Message
        • DisableProviderLocation Message
      • Medications
        • FDB
      • References
        • Environment Variables
        • List of metrics
      • Frequently Asked Questions
    • Other modules
      • MDM
        • Train model
        • Configure MDM module
        • Find duplicates: $match
        • Mathematical details
      • MCP
      • AidboxTrigger
  • Database
    • Overview
    • Database schema
    • PostgreSQL Extensions
    • AidboxDB
      • HA AidboxDB
    • Tutorials
      • Migrate to AidboxDB 16
      • Working with pgAgent
  • File storage
    • AWS S3
    • GCP Cloud Storage
    • Azure Blob Storage
    • Oracle Cloud Storage
  • Deployment and maintenance
    • Deploy Aidbox
      • Run Aidbox on Kubernetes
        • Deploy Production-ready Aidbox to Kubernetes
        • Deploy Aidbox with Helm Charts
        • Highly Available Aidbox
        • Self-signed SSL certificates
      • Run Aidbox on managed PostgreSQL
      • How to inject env variables into Init Bundle
    • Backup and Restore
      • Crunchy Operator (/pgBackRest)
      • pg_dump
      • pg_basebackup
      • WAL-G
    • Indexes
      • Get suggested indexes
      • Create indexes manually
  • App development
    • Use Aidbox with React
    • Aidbox SDK
      • Aidbox JavaScript SDK
      • Apps
      • NodeJs SDK
      • Python SDK
    • Examples
  • Reference
    • Matcho DSL reference
    • FHIR Schema reference
    • Settings reference
      • General
      • FHIR
      • Security & Access Control
      • Modules
      • Database
      • Web Server
      • Observability
      • Zen Project
    • Environment variables
      • Aidbox required environment variables
      • Optional environment variables
      • AidboxDB environment variables
    • System resources reference
      • IAM Module Resources
      • SDC Module Resources
      • Base Module Resources
      • Bulk Module Resources
      • AWF Module Resources
      • Cloud Module Resources
      • HL7v2 Module Resources
      • SQL on FHIR Module Resources
    • Email Providers reference
      • Notification resource reference
      • Mailgun environment variables
      • Postmark environment variables
    • Aidbox Forms reference
      • FHIR SDC API
      • Aidbox SDC API
      • Generating Questionnaire from PDF API
    • Aidbox SQL functions
  • Deprecated
    • Deprecated
      • Zen-related
        • RPC reference
          • aidbox
            • mdm
              • aidbox.mdm/update-mdm-tables
              • aidbox.mdm/match
        • FTR
        • Aidbox configuration project
          • Run Aidbox locally using Aidbox Configuraiton project
          • Aidbox configuration project structure
          • Set up and use configuration projects
          • Enable IGs
          • Repository
          • Seed Import
          • Manage Indexes in Zen Project
          • Seed v2
          • 🎓Migrate to git Aidbox Configuration Projects
          • Aidbox Configuration project reference
            • Zen Configuration
            • Aidbox project RPC reference
            • aidbox.config/config
          • Custom resources using Aidbox Project
          • First-Class Extensions using Zen
          • Zen Indexes
        • US Core IG
          • US Core IG support reference
        • Workflow Engine
          • Task
            • Aidbox Built-in Tasks
            • Task Executor API
            • Task User API
          • Workflow
            • Workflow User API
          • Services
          • Monitoring
        • FHIR conformance Deprecated guides
          • Touchstone FHIR 4.0.1 basic server
          • Touchstone FHIR USCore ClinData
          • How to enable US Core IG
            • Start Aidbox locally with US Core IG enabled
            • Add US Core IG to a running Aidbox instance
          • HL7 FHIR Da Vinci PDex Plan Net IG
        • Terminology Deprecated Tutorials
          • Inferno Test-Suite US Core 3.1.1
        • API constructor (/beta)
        • zen-lang validator
          • Write a custom zen profile
          • Load zen profiles into Aidbox
        • FHIR topic-based subscriptions
          • Set up SubscriptionTopic
          • Tutorial: Subscribe to Topic (/R4B)
          • API Reference
            • Subscription API
        • 🏗️FHIR Terminology Repository
          • FTR Specification
          • Create an FTR instance
            • FTR from CSV
            • FTR from FHIR IG
            • FTR from FTR — Direct Dependency
            • FTR from FTR — Supplement
          • FTR Manifest
          • Load SNOMED CT into Aidbox
          • Load LOINC into Aidbox
          • Load ICD-10-CM into Aidbox
          • Load RxNorm into Aidbox
          • Load US VSAC Package to Aidbox
          • Import via FTR
        • Zen Search Parameters
        • Access control lists (/ACL)
      • Entity / Attribute
        • Entities & Attributes
        • First-Class Extensions using Attribute
        • Custom Resources using Entity
        • Working with Extensions
        • Aidbox Search Parameters
      • Forms
      • Other
        • Custom Search
        • SearchQuery
        • Subscribe to new Patient resource
        • App Development Deprecated Tutorials
          • Receive logs from your app
            • X-Audit header
          • Patient Encounter notification Application
        • Other Deprecated Tutorials
          • Resource generation with map-to-fhir-bundle-task and subscription triggers
          • APM Aidbox
          • Automatically archive AuditEvent resources in GCP storage guide
          • HL7 v2 pipeline with Patient mapping
          • How to migrate to Apline Linux
          • How to migrate transaction id to bigint
          • How to fix broken dates
          • Configure multi-tenancy
        • AidboxProfile
        • GCP Pub/Sub
Powered by GitBook
On this page
  • JAVA_OPTS
  • AIDBOX_BOX_ID
  • AIDBOX_BASE_URL
  • AIDBOX_DB_PARAM_*
  • AIDBOX_ES_URL
  • BOX_SEARCH_DEFAULT__PARAMS_TOTAL
  • AIDBOX_ES_AUTH
  • AIDBOX_ES_BATCH_SIZE
  • AIDBOX_ES_BATCH_TIMEOUT
  • AIDBOX_ES_INDEX_PAT
  • AIDBOX_LOGS
  • AIDBOX_LOGS_MAX_LINES
  • BOX_LOGGING_DISABLE__HEALTH__LOGS
  • BOX_LOGGING_SQL_MIN__DURATION
  • BOX_LOGGING_SQL_MAX__LENGTH
  • AIDBOX_INSTALL_PG_EXTENSIONS
  • AIDBOX_STDOUT_JSON
  • AIDBOX_STDOUT_GOOGLE_JSON
  • AIDBOX_STDOUT_PRETTY
  • AIDBOX_DD_API_KEY
  • AIDBOX_DD_BATCH_SIZE
  • AIDBOX_DD_BATCH_TIMEOUT
  • AIDBOX_DD_LOGS
  • AIDBOX_CREATED_AT_URL
  • AIDBOX_CORRECT_AIDBOX_FORMAT
  • BOX_CACHE_REPLICATION_DISABLE
  • AIDBOX_DEV_MODE
  • AIDBOX_ZEN_ENTRYPOINT
  • AIDBOX_ZEN_DEV_MODE
  • AIDBOX_ZEN_PATHS
  • AIDBOX_EXTENSION_SCHEMA
  • AIDBOX_SECURITY_AUDIT__LOG_ENABLED
  • BOX_SEARCH_DEFAULT__PARAMS_COUNT
  • BOX_SEARCH_FHIR__COMPARISONS
  • BOX_SEARCH_INCLUDE_CONFORMANT
  • BOX_SEARCH_AUTHORIZE__INLINE__REQUESTS
  • BOX_SEARCH_INCLUDE_ITERATE__MAX
  • BOX_SEARCH_RESOURCE__COMPAT
  • BOX_COMPATIBILITY_VALIDATION_JSON__SCHEMA_REGEX
  • BOX_COMPATIBILITY_AUTH_PKCE_CODE__CHALLENGE_S256_CONFORMANT
  • BOX_DEBUG_SU_ENABLE
  • BOX_FEATURES_VALIDATION_SKIP_REFERENCE
  • BOX_WEB_MAX__BODY
  • BOX_WEB_THREAD
  • BOX_WEB_MAX__LINE
  • BOX_WEB_CORS_ENABLED
  • BOX_WEB_CORS_ORIGINS
  • BOX_FEATURES_TERMINOLOGY_IMPORT_SYNC
  • BOX_FEATURES_AUTHENTICATION_INTROSPECTION_CREATE__USER
  • BOX_FEATURES_GRAPHQL_WARMUP__ON__STARTUP
  • BOX_FEATURES_GRAPHQL_TIMEOUT
  • BOX_FEATURES_FHIR_TRANSACTION_MAX__ISOLATION__LEVEL
  • BOX_CONFIG_FEATURES_INDEX_SYNC__ON__START
  • Enable Aidbox compliance mode
  • Configuring SSL connection with PostgreSQL
  • Use different PostgreSQL schema
  • Set up RSA private/public keys and secret
  • Configure Aidbox WEB server workers and DB connection pool
  • Telemetry
  • Security Labels
  • Observability
  • Content security policy

Was this helpful?

Edit on GitHub
  1. Reference
  2. Environment variables

Optional environment variables

JAVA_OPTS

JAVA_OPTS="<string>"

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

JAVA_OPTS="-Xms1024m -Xmx1024m"

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=<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]

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_*

AIDBOX_DB_PARAM_<parameter name>=<parameter value>

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 totalwhen:

  1. you don't use _page

  2. 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"

BOX_LOGGING_DISABLE__HEALTH__LOGS

BOX_LOGGING_DISABLE__HEALTH__LOGS=<boolean>

Disable /health endpoint requests logging. Default value is false.

BOX_LOGGING_SQL_MIN__DURATION

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

BOX_LOGGING_SQL_MAX__LENGTH=<integer>

Max length of a query to be logged.

AIDBOX_INSTALL_PG_EXTENSIONS

AIDBOX_INSTALL_PG_EXTENSIONS=<boolean>

Says Aidbox to install PostgreSQL extensions at startup time. The default value is true.

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_GOOGLE_JSON

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

Example of the log output

{"sql":"SELECT 1","d":2,"timestamp":"2022-10-26T10:59:59.825Z","severity":"INFO","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_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

AIDBOX_DEV_MODE

AIDBOX_DEV_MODE=true

AIDBOX_ZEN_ENTRYPOINT

AIDBOX_ZEN_ENTRYPOINT=<entrypoint>

Specifies entry point for loading Aidbox configuration. Example:

AIDBOX_ZEN_ENTRYPOINT=main/box

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 location

  • path 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>

AIDBOX_SECURITY_AUDIT__LOG_ENABLED

AIDBOX_SECURITY_AUDIT__LOG_ENABLED=true

Enable producing audit logs in FHIR AuditEvent format for significant events.

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

BOX_SEARCH_INCLUDE_CONFORMANT

BOX_SEARCH_INCLUDE_CONFORMANT=true

When set to true, the behavior of _include and _revinclude becomes FHIR conformant:

  1. Without the :recur or :iterate modifier _(rev)include is only applied to the initial result.

  2. 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_AUTHORIZE_INLINE_REQUESTS=true

BOX_SEARCH_INCLUDE_ITERATE__MAX

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

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}"

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

BOX_FEATURES_VALIDATION_SKIP_REFERENCE

BOX_FEATURES_VALIDATION_SKIP_REFERENCE=true

Enables skipping resource reference validation.

BOX_WEB_MAX__BODY

BOX_WEB_MAX__BODY=<max-size-bytes>

Maximum size of request body in bytes. Default is 20971520 (20 MiB)

BOX_WEB_THREAD

BOX_WEB_THREAD=<count-of-web-worker-threads>

Count of HTTP server web workers. Default is 8

BOX_WEB_MAX__LINE

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

BOX_WEB_CORS_ENABLED=true

Allow CORS requests

BOX_WEB_CORS_ORIGINS

BOX_WEB_CORS_ORIGINS=*

Comma-separated list of allowed origins [schema]://[domain]:[port]

The default value is wildcard "*"

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

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.

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.

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

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
                       , 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 -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-----"

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

      BOX_AUTH_KEYS_PUBLIC: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtknsklLTP1y6HPtR2oYs
        ...
        ewIDAQAB
        -----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.

Security Labels

BOX_FEATURES_SECURITY__LABELS_ENABLE

BOX_FEATURES_SECURITY__LABELS_ENABLE=true

BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS

By default, stripping is disabled. To enable it, set the env to true.

BOX_FEATURES_SECURITY__LABELS_STRIP__LABELS=true

Stripping is only applied during the 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

BOX_METRICS_POSTGRES_ON=false

If you have a different pg exporter, disable Aidbox PostgreSQL metrics to avoid metrics duplication by setting the env to 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.

Content security policy

AIDBOX_CONTENT_SECURITY_POLICY_HEADER

A Content Security Policy (CSP) is a security mechanism that helps protect web applications from threats like Cross-Site Scripting (XSS), data injection, and clickjacking. It works by specifying rules for browsers about which resources (e.g., scripts, styles, images) can be loaded and executed.

AIDBOX_CONTENT_SECURITY_POLICY_HEADER=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' data:; manifest-src 'self'; media-src 'self'; worker-src 'self';

Recommended policies:

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

Explanation:

Directive

Allowed Sources

Description

Security Implications

default-src

'self'

Sets the default policy for all resource types unless overridden by specific directives.

Restricts all resources to the same origin unless explicitly allowed elsewhere.

script-src

'report-sample', 'self', 'unsafe-inline', 'unsafe-eval'

Controls JavaScript sources.

Allows same-origin scripts but also permits inline scripts and eval(), which are security risks.

style-src

'report-sample', 'self', 'unsafe-inline'

Defines valid sources for stylesheets.

Allows same-origin styles but permits inline styles, which can be exploited if not carefully managed.

object-src

'none'

Blocks <object> elements entirely.

Prevents the use of potentially dangerous <object> elements, mitigating XSS risks.

base-uri

'self'

Restricts the URLs allowed in <base> elements to the same origin.

Protects against base URL manipulation attacks.

connect-src

'self'

Limits connections (e.g., AJAX, WebSocket) to the same origin.

Prevents data exfiltration to unauthorized endpoints.

font-src

'self'

Restricts font loading to the same origin.

Reduces risks from malicious or unauthorized fonts.

frame-src

'self'

Allows embedding content in frames only from the same origin.

Mitigates clickjacking attacks by disallowing external framing of your content.

frame-ancestors

'self'

Ensures that only pages from the same origin can embed this page in a frame.

Further protects against clickjacking by controlling who can frame Aidbox pages .

img-src

'self' data:

Limits image sources to the same origin.

Prevents data leaks via malicious or unauthorized images.

manifest-src

'self'

Ensures that web app manifests are loaded only from the same origin.

Protects against unauthorized or malicious web app manifests being loaded into Aidbox.

media-src

'self'

Restricts audio and video sources to the same origin.

Prevents unauthorized media files from being loaded into Aidbox

worker-src

'self'

Limits web workers and shared workers to scripts from the same origin.

Reduces risks of malicious workers being executed within your Aidbox context.

PreviousAidbox required environment variablesNextAidboxDB environment variables

Last updated 6 days ago

Was this helpful?

Parameters prefixed with AIDBOX_DB_PARAM_ will be passed to .

Produces logs in Google Logging format (see ).

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 for additional information.

Enables _debug=policy for

Schema for PostgreSQL extensions. Default is current schema. See .

Use FHIR compliant .

Enables strict date time validation in JSON schema validation engine per .

Sets maximum (inclusive) isolation level for transactions. This value can be overridden by x-max-isolation-level header (see ).

These parameters will enable SSL connection from Aidbox to postgresql Docs on JDBC PostgreSQL connection string are here:

By default Aidbox uses public schema. If you want Aidbox to use different schema, set using environment variable AIDBOX_DB_PARAM_CURRENT_SCHEMA:

The access control feature is disabled by default. To enable it, set the env to true.

Please refer to the for additional guidance

JDBC PostgreSQL connection string
LogEntry
Highly Available Aidbox
access policy debugging
use different PostgreSQL schema section
date search
Authorize inline requests
FHIR spec
here
https://jdbc.postgresql.org/documentation/80/connect.html
https://jdbc.postgresql.org/documentation/head/ssl-client.html
JDBC parameter currentSchema
Security Labels
Metrics
OWASP Content Security Policy Cheat Sheet