Configuration

Configuration

Configuration lives in config.yml at the project root. Environment variables always take precedence over config.yml.

Copy .env.example to .env for secret and deployment-specific overrides.

config.yml Reference

server:
  port: 8080                        # TCP port
  baseUrl: http://localhost:8080    # Public base URL — set when behind a reverse proxy

fhir:
  packagesDir: ./packages           # Directory containing FHIR IG .tgz packages

capability:
  publisher: Siming                 # CapabilityStatement.publisher
  description: Siming FHIR R4 Server

database:
  migrationsPath: ./migrations
  pool:
    min: 4                          # Minimum idle connections
    max: 40                         # Maximum concurrent connections

search:
  defaultCount: 20                  # Results per page when _count is omitted
  maxCount: 1000                    # Hard upper limit on _count

security:
  # rateLimit:
  #   rps: 100                      # Requests/second per IP (enables limiting when set)
  #   burst: 200                    # Burst size (default: 2×rps)

validator:
  url: ""                           # HL7 FHIR Validator URL — enables deep profile validation

logging:
  level: info                       # trace | debug | info | warn | error

Environment Variables

Environment variables override the corresponding config.yml field.

Server

Variable	Overrides	Description
SERVER_PORT	server.port	TCP port
SERVER_BASE_URL	server.baseUrl	Public base URL

Database

Variable	Overrides	Description
DATABASE_URL	—	Full Postgres URL, e.g. postgres://user:pass@host:5432/db (takes priority over PG* vars)
PGHOST	—	Postgres host (default: localhost)
PGPORT	—	Postgres port (default: 5432)
PGUSER	—	Postgres user
PGPASSWORD	—	Postgres password
PGDATABASE	—	Postgres database name
MIGRATIONS_PATH	database.migrationsPath	Path to migration files
DB_POOL_MIN	database.pool.min	Min pool size
DB_POOL_MAX	database.pool.max	Max pool size

FHIR & Validation

Variable	Overrides	Description
PACKAGES_DIR	fhir.packagesDir	FHIR package directory
VALIDATOR_URL	validator.url	HL7 FHIR Validator base URL

SMART on FHIR (optional)

Set SMART_ISSUER to enable JWT bearer authentication. All other SMART variables are optional.

Variable	Description
SMART_ISSUER	Expected JWT iss value — enables auth when set
SMART_JWKS_URL	JWKS endpoint URL, fetched at startup
SMART_PUBLIC_KEY_PEM	RSA public key PEM (alternative to SMART_JWKS_URL)
SMART_AUDIENCE	Expected JWT aud value

Exempt paths (always accessible without token): /health, /metadata, /metrics, /.well-known/smart-configuration

Rate Limiting (optional)

Variable	Overrides	Description
RATE_LIMIT_RPS	security.rateLimit.rps	Requests/second per IP — enables limiting when set
RATE_LIMIT_BURST	security.rateLimit.burst	Burst size (default: 2×RPS)

Logging

Variable	Overrides	Description
LOG_LEVEL	logging.level	trace debug info warn error

FHIR Packages

Place FHIR R4 IG packages in the packages/ directory before starting the server:

packages/
  hl7.fhir.r4.core-4.0.1.tgz          # Required base package
  tw.gov.mohw.twcore-1.0.0.tgz         # TW Core IG (optional)

scripts/fetch-packages.sh downloads the base R4 package automatically.

The server reads packages at startup to:

• Build the GET /metadata CapabilityStatement
• Index terminology (CodeSystem + ValueSet) for $validate binding checks