Skip to main content

​
Overview

Configuration is loaded in this order (later overrides earlier):
  1. Built-in defaults
  2. config.yaml (optional)
  3. Environment variables with FHIR__ prefix (e.g. FHIR__SERVER__PORT)
  4. DATABASE_URL fallback for database.url when FHIR__DATABASE__URL is unset
  5. Runtime overrides in PostgreSQL (Admin UI / Admin API)
Nested keys map to env vars via __: FHIR__DATABASE__URL → database.url. Arrays use comma: FHIR__SERVER__CORS_ORIGINS=https://a.com,https://b.com.

​
Config Reference

​
server

OptionDefaultDescription
host"0.0.0.0"Bind address
port8080Listen port
cors_origins["http://localhost:3000"]Allowed CORS origins (empty = no CORS)
max_request_body_size10485760 (10 MB)Max request body bytes
max_response_body_size52428800 (50 MB)Max response body bytes

​
database

OptionDefaultDescription
url"postgresql://fhir:fhir@localhost/fhir"Connection string
test_database_urlnullOverride for test environments
pool_min_size2API server pool min connections
pool_max_size20API server pool max connections
pool_timeout_seconds60API server pool timeout
worker_pool_min_size1Worker pool min connections
worker_pool_max_size5Worker pool max connections
worker_pool_timeout_seconds60Worker pool timeout
indexing_batch_size50Resources per indexing batch
indexing_bulk_threshold200Min resources to use bulk indexing
statement_timeout_seconds300Max query execution time
lock_timeout_seconds30Max lock wait time

​
fhir

OptionDefaultDescription
version"R4"FHIR version (R4, R4B, R5)
default_format"json"Default format (json, xml)
default_prefer_return"representation"Prefer header default (minimal, representation, operationoutcome)
allow_update_createtrueAllow PUT to create resources
hard_deletefalsePhysical delete vs soft-delete
install_internal_packagestrueInstall bundled packages from fhir_packages/
internal_packages_dirnullOverride path for internal packages
registry_urlnullCustom package registry URL
fhir.interactions — Toggle FHIR operations. All default to true.
  • system: capabilities, search, history, delete, batch, transaction, history_bundle
  • type_level: create, conditional_create, search, history, conditional_update, conditional_patch, conditional_delete
  • instance: read, vread, update, patch, delete, history, delete_history, delete_history_version
  • compartment: search
  • operations: system, type_level, instance
fhir.search
OptionDefaultDescription
enable_texttrueEnable _text search
enable_contenttrueEnable _content search
default_count20Default page size
max_count1000Max _count value
max_total_results10000Max total results across pages
max_include_depth3Max _include/_revinclude depth
max_includes10Max _include parameters
search_parameter_active_statuses["draft","active"]Active SearchParameter statuses
fhir.fhirpath
OptionDefaultDescription
enable_resolvetrueAllow resolve() for references
enable_external_httpfalseAllow external HTTP fetches (security risk)
resolve_cache_size100LRU cache size for resolved resources
http_timeout_seconds5Timeout for external HTTP
fhir.referential_integrity
OptionDefaultDescription
mode"lenient"lenient (no checks) or strict (reject broken refs, block deletes of referenced)
fhir.default_packages — core, extensions, terminology. Each: install, install_examples, include_resource_types, exclude_resource_types (mutually exclusive). fhir.packages — Additional packages: name, version, install_examples, include_resource_types, exclude_resource_types. fhir.capability_statement — Metadata for GET /metadata: id, name, title, publisher, description, software_name, software_version, contact_email, supported_resources.

​
workers

OptionDefaultDescription
enabledtrueEnable background workers
embeddedtrueRun workers in server process; false = separate fhir-worker binary
poll_interval_seconds5Poll interval (plus LISTEN/NOTIFY)
max_concurrent_jobs1Max concurrent jobs
reconnect_initial_seconds1Initial reconnect backoff
reconnect_max_seconds30Max reconnect backoff
reconnect_jitter_ratio0.2Jitter for reconnect (0–1)

​
logging

OptionDefaultDescription
level"info"trace, debug, info, warn, error
jsonfalseJSON log format
file_enabledfalseEnable file logging
file_directory"./logs"Log file directory
file_prefix"fhir-server"Log file prefix
file_rotation"daily"daily, hourly, minutely, never
opentelemetry_enabledfalseOpenTelemetry integration
otlp_endpoint"http://localhost:4317"OTLP endpoint
trace_sample_ratio1.0Trace sampling (0–1)
service_name"fhir-server"Service name
deployment_environment"development"dev, staging, prod
service_versionnullOverride version
otlp_timeout_seconds10OTLP export timeout
logging.audit — Audit logging for FHIR operations.
OptionDefaultDescription
enabledtrueMaster switch
include_successtrueRecord successful interactions
include_authz_failuretrueRecord 401/403
include_processing_failuretrueRecord other failures
capture_search_querytrueCapture search request in AuditEvent
capture_operation_outcometrueCapture OperationOutcome on failure
per_patient_events_for_searchtrueOne AuditEvent per patient for search
logging.audit.interactions — Per-interaction audit toggles: read, vread, history, search, create, update, patch, delete, capabilities (default: false), operation, batch, transaction, export.

​
ui

OptionDefaultDescription
enabledtrueEnable admin UI
title"FHIR Admin"Browser tab title
passwordnullAdmin password (use FHIR__UI__PASSWORD for secrets)
session_secretnullSession signing key (recommended in production)
session_ttl_seconds43200 (12h)Session lifetime

​
auth

OptionDefaultDescription
enabledfalseEnable OIDC authentication
requiredtrueReject unauthenticated requests
public_pathshealth, /, favicon, metadata, smart-configPaths that skip auth
auth.oidc — Required when auth.enabled=true: issuer_url, audience. Optional: jwks_url, jwks_cache_ttl_seconds (300), http_timeout_seconds (5).

​
Example

server:
  host: "0.0.0.0"
  port: 8080

database:
  url: "postgresql://fhir:fhir@db:5432/fhir"

fhir:
  version: "R4"
  allow_update_create: true
  hard_delete: false
  search:
    max_count: 1000

workers:
  embedded: true

ui:
  password: null  # Use FHIR__UI__PASSWORD in production

auth:
  enabled: false

​
Runtime Configuration

A subset of settings can be changed at runtime via Admin UI (Settings) or Admin API (GET/PUT /admin/config/{key}). Stored in PostgreSQL; multi-instance sync via LISTEN/NOTIFY. See apps/server/src/runtime_config/keys.rs for supported keys.