Configuration Reference

This is the comprehensive reference for Fire Arrow Server's application.yaml configuration. Properties are organized by section, with descriptions, defaults, and examples.

spring.datasource -- Database Connection

Fire Arrow Server uses PostgreSQL as its primary data store. For quick local experimentation, H2 in-memory is also supported.

PostgreSQL (Recommended)

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/hapi
    username: hapi
    password: hapi
    driverClassName: org.postgresql.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
  jpa:
    properties:
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      hibernate.search.enabled: false

H2 In-Memory (Development Only)

spring:
  datasource:
    url: jdbc:h2:mem:hapi;DB_CLOSE_ON_EXIT=FALSE
    username: sa
    password:
    driverClassName: org.h2.Driver
  jpa:
    properties:
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect

warning

H2 is suitable for quick experiments only. Data is lost when the server stops. Always use PostgreSQL for persistent deployments.

Property	Description	Default
url	JDBC connection URL	jdbc:postgresql://localhost:5432/hapi
username	Database username	hapi
password	Database password	hapi
driverClassName	JDBC driver class	org.postgresql.Driver
hikari.maximum-pool-size	Maximum connections in the pool	20
hikari.minimum-idle	Minimum idle connections maintained	5

hapi.fhir -- FHIR Server Behavior

Controls the FHIR server's capabilities, supported resources, and API features.

hapi:
  fhir:
    fhir_version: R4
    graphql_enabled: true
    openapi_enabled: true
    default_page_size: 20
    max_page_size: 200
    search_index_full_text_enabled: false
    cors:
      enabled: true
      allowed_origins:
        - "*"
    subscription:
      resthook_enabled: false
      websocket_enabled: false
      email:
        enabled: false
        from: "[email protected]"

Property	Description	Default
fhir_version	FHIR specification version	R4
graphql_enabled	Enable the GraphQL API endpoint	true
openapi_enabled	Enable Swagger UI and OpenAPI spec	true
default_page_size	Default number of results per page	20
max_page_size	Maximum results per page	200
search_index_full_text_enabled	Enable full-text search (_text, _content parameters)	false
cors.enabled	Enable CORS headers	true
cors.allowed_origins	Allowed CORS origins	["*"]
subscription.resthook_enabled	Enable REST hook subscription channel	false
subscription.websocket_enabled	Enable WebSocket subscription channel	false
subscription.email.enabled	Enable email subscription channel	false
subscription.email.from	Sender address for email subscriptions	--

fire-arrow.authentication -- Authentication Providers

Configure OAuth 2.0 / OIDC providers and API token support. See Authentication for a detailed guide.

fire-arrow:
  authentication:
    enabled: true
    providers:
      - name: my_oidc_provider
        type: oidc
        enabled: true
        oidc-uri: "https://login.example.com"
        audience: "api://fire-arrow"
        api-scope: "fhir.access"
        claim-mapping:
          scope-claim: "scp"
          roles-claim: "roles"
          subject-claim: "sub"
          email-claim: "email"
          name-claim: "name"
          fhir-resource-type-claim: "resource_type"
          fhir-id-claim: "fhir_id"
        identity-resolution:
          identifier-system: "https://your-app.example.com/fhir/user-id"
          auto-create-enabled: true
    api-tokens:
      hmac-secret: "${API_TOKEN_SECRET}"

Property	Description	Default
enabled	Enable authentication globally	false
providers[].name	Unique provider name	--
providers[].type	Provider type (oidc, azure-identity)	--
providers[].enabled	Enable this provider	true
providers[].oidc-uri	OIDC issuer URI	--
providers[].audience	Expected token audience	--
providers[].api-scope	Required API scope	--
providers[].claim-mapping.*	Maps token claims to identity fields	--
providers[].identity-resolution.identifier-system	FHIR identifier system for user lookup	--
providers[].identity-resolution.auto-create-enabled	Create FHIR resources for new users	false
api-tokens.hmac-secret	Secret key for API token generation/validation	--

fire-arrow.authorization -- Access Control

Configure role-based access control rules. See Authorization for a detailed guide.

fire-arrow:
  authorization:
    default-validator: Forbidden
    debug: false
    cache:
      enabled: true
      ttl-seconds: 300
    validation-rules:
      - client-role: "Patient"
        resource: "Patient"
        operation: "read"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Patient"
        operation: "graphql-read"
        validator: "PatientCompartment"
      - client-role: "Practitioner"
        resource: "Patient"
        operation: "search"
        validator: "LegitimateInterest"

Property	Description	Default
default-validator	Validator applied when no rule matches	Forbidden
debug	Enable authorization debug mode (logs detailed rule evaluation)	false
cache.enabled	Cache authorization decisions	true
cache.ttl-seconds	Cache entry time-to-live in seconds	300
validation-rules[]	List of authorization rules	[]
validation-rules[].client-role	Role this rule applies to (Patient, Practitioner, RelatedPerson, Device, Public)	--
validation-rules[].resource	FHIR resource type this rule applies to	--
validation-rules[].operation	Operation (read, search, create, write, delete, graphql-read, graphql-search, me, binary-upload, subscribe, generate-durable-token, generate-one-time-token)	--
validation-rules[].validator	Validator to use (PatientCompartment, LegitimateInterest, CareTeam, Forbidden, Permit)	--

Authorization Debug Mode

Set debug: true during development to see detailed logs of how each request is evaluated against your authorization rules. Disable it in production -- debug mode logs sensitive information.

fire-arrow.binary-storage -- Azure Blob Storage

Configure binary file storage. See Binary Storage for the full guide.

fire-arrow:
  binary-storage:
    enabled: false
    azure:
      connection-string: "${AZURE_STORAGE_CONNECTION_STRING}"
      container-name: "fhir-binaries"
      max-file-size: 10485760
      pre-signed-url-expiration-seconds: 120

Property	Description	Default
enabled	Enable binary storage	false
azure.connection-string	Azure Blob Storage connection string	--
azure.endpoint	Azure Blob endpoint (for managed identity)	--
azure.container-name	Blob container name	--
azure.max-file-size	Maximum upload size in bytes	10485760 (10 MB)
azure.pre-signed-url-expiration-seconds	Pre-signed URL lifetime	120

fire-arrow.careplan-events -- CarePlan Scheduling

Configure server-side CarePlan activity materialization. See CarePlan Events for the full guide.

fire-arrow:
  careplan-events:
    enabled: false
    scheduling:
      horizon-duration: "P30D"
      check-interval: "PT1H"
    subscriptions:
      max-ttl: "P90D"
    delivery:
      max-retries: 3
      retry-interval: "PT30S"
      failure-threshold: 5
    cleanup:
      interval: "P1D"
      completed-task-retention: "P90D"
    task:
      auto-transition-to-ready: true

Property	Description	Default
enabled	Enable CarePlan event processing	false
scheduling.horizon-duration	How far ahead to materialize tasks (ISO 8601 duration)	P30D
scheduling.check-interval	How often to run the materialization check	PT1H
subscriptions.max-ttl	Maximum subscription lifetime	P90D
delivery.max-retries	Webhook delivery retry attempts	3
delivery.retry-interval	Delay between retries	PT30S
delivery.failure-threshold	Consecutive failures before disabling subscription	5
cleanup.interval	Cleanup job frequency	P1D
cleanup.completed-task-retention	Retention period for completed tasks	P90D
task.auto-transition-to-ready	Auto-transition tasks to ready when due	true

fire-arrow.subscription.azure-queue -- Azure Storage Queue

Configure the Azure Storage Queue subscription delivery channel. See Subscriptions for details.

fire-arrow:
  subscription:
    azure-queue:
      enabled: false
      connection-string: "${AZURE_STORAGE_CONNECTION_STRING}"
      queue-name: "fhir-subscription-events"

Property	Description	Default
enabled	Enable Azure Storage Queue delivery	false
connection-string	Azure Storage account connection string	--
queue-name	Target queue name	--

fire-arrow.license -- License Configuration

Configure the Fire Arrow Server license. See Licensing for the full guide.

fire-arrow:
  license:
    source: file
    path: "/etc/fire-arrow/license.key"
    deployment-id: "my-deployment-prod"
    runtime-environment: prod

Property	Description	Values
source	License delivery method	file, inline
path	Path to license file	File path (when source: file)
content	Inline license string	License content (when source: inline)
deployment-id	Deployment identifier	Must match the issued license
runtime-environment	Deployment tier	prod, nonprod

fire-arrow.admin -- Admin Web UI

Configure the browser-based administration interface.

fire-arrow:
  admin:
    enabled: true
    config-viewer:
      enabled: true
    auth-profiles:
      - name: "Development"
        token: "${ADMIN_DEV_TOKEN}"

Property	Description	Default
enabled	Enable the admin web UI at /admin/	true
config-viewer.enabled	Show server configuration in the admin UI	true
auth-profiles[]	Pre-configured auth profiles for the admin GraphQL explorer	[]
auth-profiles[].name	Display name for the profile	--
auth-profiles[].token	Bearer token to use with this profile	--

Auth profiles let you switch between different user identities in the admin GraphQL explorer without manually copying tokens. This is useful during development when you want to test queries as different roles.

fire-arrow.mutex -- Distributed Locking

Controls how Fire Arrow Server coordinates background tasks across nodes.

fire-arrow:
  mutex:
    type: local

Property	Description	Values
type	Lock implementation	local (single node), jdbc (multi-node via PostgreSQL)

Use jdbc when running multiple Fire Arrow Server instances to ensure CarePlan materialization and subscription processing run on exactly one node at a time.

Environment Variable Override Pattern

Every YAML property can be overridden with an environment variable. The conversion rules:

1. Remove the YAML hierarchy and join with underscores
2. Convert to uppercase
3. Replace dots and hyphens with underscores

Examples:

YAML Path	Environment Variable
spring.datasource.url	SPRING_DATASOURCE_URL
spring.datasource.password	SPRING_DATASOURCE_PASSWORD
hapi.fhir.graphql_enabled	HAPI_FHIR_GRAPHQL_ENABLED
fire-arrow.authentication.enabled	FIRE_ARROW_AUTHENTICATION_ENABLED
fire-arrow.binary-storage.azure.connection-string	FIRE_ARROW_BINARY_STORAGE_AZURE_CONNECTION_STRING
fire-arrow.careplan-events.scheduling.horizon-duration	FIRE_ARROW_CAREPLAN_EVENTS_SCHEDULING_HORIZON_DURATION
fire-arrow.license.source	FIRE_ARROW_LICENSE_SOURCE
fire-arrow.mutex.type	FIRE_ARROW_MUTEX_TYPE

Complete Example

Here's a production-ready application.yaml with all major features enabled:

spring:
  datasource:
    url: jdbc:postgresql://db:5432/hapi
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driverClassName: org.postgresql.Driver
    hikari:
      maximum-pool-size: 20
  jpa:
    properties:
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect

hapi:
  fhir:
    fhir_version: R4
    graphql_enabled: true
    openapi_enabled: true
    default_page_size: 20
    max_page_size: 200
    cors:
      enabled: true
      allowed_origins:
        - "https://your-app.example.com"
    subscription:
      resthook_enabled: true
      websocket_enabled: true

fire-arrow:
  authentication:
    enabled: true
    providers:
      - name: primary_oidc
        type: oidc
        enabled: true
        oidc-uri: "https://login.example.com"
        audience: "api://fire-arrow"
        api-scope: "fhir.access"
        claim-mapping:
          scope-claim: "scp"
          roles-claim: "roles"
          subject-claim: "sub"
          email-claim: "email"
          name-claim: "name"
          fhir-resource-type-claim: "resource_type"
          fhir-id-claim: "fhir_id"
        identity-resolution:
          identifier-system: "https://your-app.example.com/fhir/user-id"
          auto-create-enabled: true
    api-tokens:
      hmac-secret: ${API_TOKEN_SECRET}

  authorization:
    default-validator: Forbidden
    debug: false
    cache:
      enabled: true
      ttl-seconds: 300
    validation-rules:
      - client-role: "Patient"
        resource: "Patient"
        operation: "read"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Patient"
        operation: "graphql-read"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Observation"
        operation: "graphql-search"
        validator: "PatientCompartment"
      - client-role: "Practitioner"
        resource: "Patient"
        operation: "search"
        validator: "LegitimateInterest"

  binary-storage:
    enabled: true
    azure:
      connection-string: ${AZURE_STORAGE_CONNECTION_STRING}
      container-name: "fhir-binaries"
      max-file-size: 10485760

  careplan-events:
    enabled: true
    scheduling:
      horizon-duration: "P30D"
      check-interval: "PT1H"
    subscriptions:
      max-ttl: "P90D"
    delivery:
      max-retries: 3
      failure-threshold: 5

  subscription:
    azure-queue:
      enabled: true
      connection-string: ${AZURE_STORAGE_CONNECTION_STRING}
      queue-name: "fhir-events"

  license:
    source: inline
    content: ${FIRE_ARROW_LICENSE_CONTENT}
    deployment-id: "production-01"
    runtime-environment: prod

  admin:
    enabled: true

  mutex:
    type: jdbc