Configuration

Overview

Configuration is loaded in this order (later overrides earlier):

Built-in defaults
config.yaml (optional)
Environment variables with FHIR__ prefix (e.g. FHIR__SERVER__PORT)
DATABASE_URL fallback for database.url when FHIR__DATABASE__URL is unset
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`

Option	Default	Description
`host`	`"0.0.0.0"`	Bind address
`port`	`8080`	Listen port
`cors_origins`	`[]`	Allowed CORS origins (empty = no CORS)
`max_request_body_size`	`10485760` (10 MB)	Max request body bytes
`max_response_body_size`	`52428800` (50 MB)	Max response body bytes

`database`

Option	Default	Description
`url`	`"postgresql://fhir:fhir@localhost/fhir"`	Connection string
`test_database_url`	`null`	Override for test environments
`pool_min_size`	`2`	API server pool min connections
`pool_max_size`	`20`	API server pool max connections
`pool_timeout_seconds`	`60`	API server pool timeout
`worker_pool_min_size`	`1`	Worker pool min connections
`worker_pool_max_size`	`5`	Worker pool max connections
`worker_pool_timeout_seconds`	`60`	Worker pool timeout
`indexing_batch_size`	`50`	Resources per indexing batch
`indexing_bulk_threshold`	`200`	Min resources to use bulk indexing
`statement_timeout_seconds`	`300`	Max query execution time
`lock_timeout_seconds`	`30`	Max lock wait time

`fhir`

Option	Default	Description
`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_create`	`true`	Allow PUT to create resources
`hard_delete`	`false`	Physical delete vs soft-delete
`install_internal_packages`	`true`	Install bundled packages from `fhir_packages/`
`internal_packages_dir`	`null`	Override path for internal packages
`registry_url`	`null`	Custom 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

Option	Default	Description
`inline_indexing`	`true`	Index synchronously during CRUD; set `false` for large bulk ingests
`enable_text`	`true`	Enable `_text` search
`enable_content`	`true`	Enable `_content` search
`default_count`	`20`	Default page size
`max_count`	`1000`	Max `_count` value
`max_total_results`	`10000`	Max total results across pages
`max_include_depth`	`3`	Max `_include`/`_revinclude` depth
`max_includes`	`10`	Max `_include` parameters
`search_parameter_active_statuses`	`["draft","active"]`	Active SearchParameter statuses

fhir.fhirpath

Option	Default	Description
`enable_resolve`	`true`	Allow `resolve()` for references
`enable_external_http`	`false`	Allow external HTTP fetches (security risk)
`resolve_cache_size`	`100`	LRU cache size for resolved resources
`http_timeout_seconds`	`5`	Timeout for external HTTP

fhir.referential_integrity

Option	Default	Description
`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`

Option	Default	Description
`enabled`	`true`	Enable background workers
`embedded`	`true`	Run workers in server process; `false` = separate `fhir-worker` binary
`poll_interval_seconds`	`5`	Poll interval (plus LISTEN/NOTIFY)
`max_concurrent_jobs`	`1`	Max concurrent jobs
`reconnect_initial_seconds`	`1`	Initial reconnect backoff
`reconnect_max_seconds`	`30`	Max reconnect backoff
`reconnect_jitter_ratio`	`0.2`	Jitter for reconnect (0–1)

`logging`

Option	Default	Description
`level`	`"info"`	trace, debug, info, warn, error
`json`	`false`	JSON log format
`file_enabled`	`false`	Enable file logging
`file_directory`	`"./logs"`	Log file directory
`file_prefix`	`"fhir-server"`	Log file prefix
`file_rotation`	`"daily"`	daily, hourly, minutely, never
`opentelemetry_enabled`	`false`	OpenTelemetry integration
`otlp_endpoint`	`"http://localhost:4317"`	OTLP endpoint
`trace_sample_ratio`	`1.0`	Trace sampling (0–1)
`service_name`	`"fhir-server"`	Service name
`deployment_environment`	`"development"`	dev, staging, prod
`service_version`	`null`	Override version
`otlp_timeout_seconds`	`10`	OTLP export timeout

logging.audit — Audit logging for FHIR operations.

Option	Default	Description
`enabled`	`true`	Master switch
`include_success`	`true`	Record successful interactions
`include_authz_failure`	`true`	Record 401/403
`include_processing_failure`	`true`	Record other failures
`capture_search_query`	`true`	Capture search request in AuditEvent
`capture_operation_outcome`	`true`	Capture OperationOutcome on failure
`per_patient_events_for_search`	`true`	One 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`

Option	Default	Description
`enabled`	`true`	Enable admin UI
`title`	`"FHIR Admin"`	Browser tab title
`password`	`null`	Admin password (use `FHIR__UI__PASSWORD` for secrets)
`session_secret`	`null`	Session signing key (recommended in production)
`session_ttl_seconds`	`43200` (12h)	Session lifetime

`auth`

Option	Default	Description
`enabled`	`false`	Enable OIDC authentication
`required`	`true`	Reject unauthenticated requests
`public_paths`	health, /, favicon, metadata, smart-config	Paths 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.

Getting Started

Server

Overview

Config Reference

`server`

`database`

`fhir`

`workers`

`logging`

`ui`

`auth`

Example

Runtime Configuration

​Overview

​Config Reference

​server

​database

​fhir

​workers

​logging

​ui

​auth

​Example

​Runtime Configuration

Overview

Config Reference

`server`

`database`

`fhir`

`workers`

`logging`

`ui`

`auth`

Example

Runtime Configuration