Server, database & telemetry

The listener and REST surface ([server] and its sub-tables), the PostgreSQL connection ([db]), and the two observability sections ([log], [telemetry]). Precedence, the environment-name grammar, and file discovery are on the Configuration reference index.

• [server]
  • base_path: shortening the REST base path
  • Behind a path-prefixed reverse proxy
  • [server.limits]: request-body sizes
  • [server.rate_limit]: per-caller request rates
  • [server.connection]: bounds before a request exists
  • system_id: the data-authoring identity
  • [server.tls]: native TLS and mutual-TLS client authentication
  • [server.identity]
• [db]
• [storage]
• [log]
• [telemetry]

[server]

The HTTP listener and REST surface.

[server]
bind = "0.0.0.0:8080"
base_path = "/ferroehr/rest/openehr/v1"
max_in_flight = 256
swagger_ui = "private"
cors_permissive = false
system_id = "ferroehr.local"

The shed sits on the clinical API subtree only, as its outermost layer: a shed request never reaches authentication, auditing, or the request body, and the always-on status, health, discovery and management routes are never shed.

base_path: shortening the REST base path

ITS-REST leaves the API base to the deployment and fixes only the version segment at its end, so you may shorten base_path. The shape is checked at boot, and a value that breaks a rule stops the server with an error naming the key and every rule it broke:

• The first segment is ferroehr. /ferroehrx/v1 and /x/ferroehr/v1 are refused. This segment is not configurable away.
• The last segment is v1, the openEHR API version this server implements. The shortest accepted value is therefore /ferroehr/v1.
• No trailing slash, no empty segment (//), and every segment uses only the unreserved URL characters A-Z a-z 0-9 - . _ ~.

The status and documentation routes hang off the REST root, which the server derives from base_path by dropping the segments that name the openEHR API: the trailing v1, plus an openehr segment directly before it when you spell one.

The Swagger UI ({rest root}/swagger-ui), the OpenAPI documents ({rest root}/api-docs/…) and the SMART discovery document ({rest root}/.well-known/smart-configuration) move with it. The health family stays at the process root: /health, /health/liveness, /health/readiness.

Set it from the environment with:

FERROEHR__SERVER__BASE_PATH=/ferroehr/v1

Note

The ferroehr healthcheck subcommand, which the published container images run as their Docker health check, derives its default URL from the effective configuration (http://127.0.0.1:<port><REST root>/status), so it follows a shortened base path on its own. An explicit FERROEHR_HEALTHCHECK_URL still wins, for example to probe /health/readiness, which no base path affects.

Behind a path-prefixed reverse proxy

A proxy that mounts the CDR under a prefix stacks that prefix on top of base_path. A proxy serving the server at /cdr with the default base path gives clients URLs like:

https://cdr.example.org/cdr/ferroehr/rest/openehr/v1/definition/template/adl1.4

Two ways to shorten that. Strip the prefix at the proxy, so the server sees the path it serves (nginx proxy_pass http://cdr:8080/; with the trailing slash, Caddy handle_path, Traefik StripPrefix). Or shorten the base path:

FERROEHR__SERVER__BASE_PATH=/ferroehr/v1

which gives https://cdr.example.org/cdr/ferroehr/v1/definition/template/adl1.4.

Whichever you choose, tell every client. The server builds its Location headers, its served OpenAPI paths and its SMART discovery document from its own base_path, and it cannot see a prefix the proxy adds. The FerroEHR Viewer has its own mirror key, cdr.base_path, which must match.

[server.limits]: request-body sizes

[server.limits]
body_bytes = 16777216        # 16 MiB
bulk_body_bytes = 67108864   # 64 MiB

A request over its tier’s limit is refused 413 Payload Too Large with the standard openEHR error body. The status is not in the ITS-REST status table; it is admitted there as an additional, non-conflicting code, and is what RFC 9110 §15.5.14 defines for this refusal.

The defaults are sized against the measured payloads in the vendored clinical corpus rather than chosen as round numbers: the clinical tier clears the largest operational template in that corpus several times over, and the bulk tier is four times the clinical one, for payloads with no published bound (a whole-EHR extract, a TDD batch). Raise body_bytes if your compositions embed large DV_MULTIMEDIA data: a base64 radiology image can exceed either tier on its own, and that is a deliberate operator decision rather than a default.

[server.rate_limit]: per-caller request rates

[server.rate_limit]
enabled = true
principal_per_second = 1024
principal_burst = 2048
address_per_second = 2048
address_burst = 4096

This is not max_in_flight, and you should be able to tell them apart from the status alone. max_in_flight protects capacity: too many requests in flight at once, from anyone, and the excess is shed 503 + Retry-After. Rate limiting protects fairness: one caller asking too often over time, refused 429 + Retry-After. A 503 means the server is full; a 429 means you are asking too fast.

Two tiers, because they defend different things. The address tier sits outside authentication, so a flood of unauthenticated requests is refused before it can make the server verify a signature per request; a limiter must not itself be the expensive path. The principal tier sits inside authentication, keyed on the authenticated subject, which is the only fair key for a clinical API: a hospital behind one NAT is a single address, so an address-keyed clinical limit would throttle an entire site because one client was busy.

Both defaults sit above this implementation’s own measured whole-server ceiling, so neither tier can refuse a caller until it is asking for more than the server could have served; below that line, capacity is max_in_flight’s job. A deployment sized for more than the reference measurement environment should raise both in proportion.

Refusals carry the limiter’s own Retry-After and x-ratelimit-* headers alongside the openEHR error body. 429 is the status RFC 6585 §4 defines for this refusal, admitted by ITS-REST as an additional, non-conflicting code.

The always-on health family is covered by the address tier only, deliberately: an orchestrator probe must never be refused because a principal-keyed bucket was exhausted, and probe rates are nowhere near the address ceiling.

Tip

Benchmarking this server? Turn the limiter off first, or you will measure it instead of the server. The project’s own measurement lanes compose an overlay that does exactly that, and both instruments refuse to write a record if the server answered any 429.

[server.connection]: bounds before a request exists

[server.connection]
header_read_timeout_secs = 10
max_concurrent_streams = 256
http2_keep_alive_interval_secs = 30
http2_keep_alive_timeout_secs = 10

Every other limit on this page engages once a request has been parsed and dispatched: body size, the request timeout, the rate limiter, the in-flight shed. A client that opens a socket and then trickles request headers reaches none of them, while costing itself almost nothing. This table is where that is bounded, and HTTP/1 and HTTP/2 need different bounds because the exposure differs: HTTP/1 streams a request head, so it can be trickled; HTTP/2 multiplexes streams, so the exposure is concurrency.

system_id: the data-authoring identity

system_id is the identifier this CDR stamps into the data it authors. It appears on the wire in three places:

• EHR.system_id, recorded when an EHR is created. The openEHR RM (EHR Information Model, EHR Identifier Allocation) says the EHR.system_id “should be set to the value that would normally be used for locally created EHRs”: a value the deployment chooses, not a product constant.
• AUDIT_DETAILS.system_id on every commit for which the client did not supply one through the openehr-audit-details header. The openEHR REST API requires that “when system_id is not provided by the client, the server MUST set it to its own configured system identifier”.
• OBJECT_VERSION_ID.creating_system_id: the middle segment of every version identifier the server mints (<object_id>::<creating_system_id>::<version>).

Practical notes:

• The value must be a legal openEHR UID: a UUID, an ISO OID, or an internet id (a reverse-domain / DNS-style name) per the openEHR BASE identification grammar. The server judges it with the same validating constructor its reader uses and refuses to boot on an illegal value, because it becomes the creating_system_id segment of every version identifier the server mints and an illegal value would produce ids the server’s own reader rejects. A DNS-style name like cdr.hospital.example is valid; an empty value, or one containing the :: field separator, is not.
• Choose it before going live and keep it stable. The value is stored with each EHR and each version; changing it later affects only newly authored data: existing EHR ids, audit rows and version identifiers are never rewritten, and previously issued OBJECT_VERSION_IDs stay valid.
• Make it unique per system, so data exchanged between openEHR systems keeps unambiguous provenance.
• system_id is not [server.identity]. system_id says which system authored the data; [server.identity] is the display identity of the OPTIONS System-Options manifest. Rebranding changes the manifest and nothing in stored data; changing system_id changes what new data says about its origin and leaves the manifest alone.

[server.tls]: native TLS and mutual-TLS client authentication

Native TLS termination on the main listener, off by default; deployments commonly terminate TLS at an ingress. client_auth = "required" is the IHE ATNA ITI-19 mutually-authenticated-node posture (see the Audit trail chapter). The separate-port management listener always stays plain HTTP.

[server.tls]
enabled = false
client_auth = "off"
min_version = "1.3"

Note

min_version defaults to 1.3 only, following the OWASP Transport Layer Security Cheat Sheet: web applications must default to TLS 1.3 and may support TLS 1.2 for compatibility. Setting "1.2" enables 1.2 alongside 1.3, never instead of it; pick it only for a client that genuinely cannot do 1.3, such as an older integration engine or a pinned Java runtime. TLS 1.1 and 1.0 are not selectable at all: RFC 8996 deprecates them, and neither this key nor the TLS library offers them.

[server.identity]

The System-Options manifest identity (OPTIONS on the API base path, e.g. OPTIONS /ferroehr/rest/openehr/v1, the System API’s one location). This is the deployment’s display identity only; the identifier stamped into authored data is system_id.

The defaults are derived from the build rather than typed into the handler, so the manifest never out-claims what was actually measured. Override them only to rebrand.

[db]

PostgreSQL connection.

[db]
url = "postgres://ferroehr:ferroehr@localhost:5432/ferroehr"
migrate = "apply"
max_connections = 20
min_connections = 2
acquire_timeout_secs = 30
statement_timeout_ms = 60000

statement_timeout_ms is the backstop the HTTP request timeout cannot be: answering a client by dropping the handler future does not cancel the statement PostgreSQL is running, so without it a handful of expensive queries can hold every pooled connection while every one of their callers has already given up. Keep it above query.timeout_ms so the AQL engine’s own typed refusal fires first and this only catches what the engine does not govern.

[storage]

One DSN per storage domain. Every domain always lives in its own schema (clinical, party, linkage, audit) and every pool carries only its own on its search_path, so no statement can reach another domain’s relations without naming a schema it is not granted. Setting a url here adds the CREDENTIAL separation, and — if the DSN names another host — lets the domain live in a database or cluster of its own.

[storage.party]
url_file = "/run/secrets/db-party-dsn"

[storage.linkage]
url_file = "/run/secrets/db-linkage-dsn"

Why a schema is not always enough: a base backup, WAL archiving and physical replication carry every schema of a database together (PostgreSQL 18, Backup and Restore), so a separation that must survive those is a separation of databases. The Swiss EPDV Art. 10 Abs. 1 lit. b asks for storage “von anderen Datenbeständen getrennt” and the DSV Art. 4 Abs. 5 for the log to be kept “getrennt vom System, in welchem die Personendaten bearbeitet werden”; openEHR reads the same way for the identity cross-reference, which “could be located on different machines” (BASE architecture_overview/master07-security.adoc §Anonymity). No openEHR spec governs pools or database roles — this is our own design.

What the server checks at boot:

• a runtime role that can read another domain’s relations is refused, always;
• two domains configured on different DSNs that turn out to authenticate as the same database role are refused — a separation that exists only in the configuration is worse than none, because it reads as one that holds;
• a missing domain role is a warning under deployment_profile = "sandbox" and a refusal under production, where there are no grants to separate anything with.

One constraint on relocation: the linkage migration set revokes a function the party set creates, so those two domains are prepared in the same database. A layout that splits them is refused before anything connects, with the remedy.

[log]

[log]
format = "auto"
filter = "info,ferroehr=info"

Tip

The ASCII boot banner follows the rendering that is actually installed, not the configured word: it prints for pretty, and for auto only when stdout is a terminal. Under json, and under auto off a terminal (a container, a pipe into a log collector) stdout is parseable JSON from the first byte.

[telemetry]

OpenTelemetry export. With otlp_endpoint unset the trace export layer is not installed at all, at zero overhead.

[telemetry]
service_name = "ferroehr"
environment = "dev"
traces_sample_ratio = 1.0
metrics_push = false

Note

Instrument names carry no Prometheus suffix; the exporter derives one. A counter named auth_failures is scraped as auth_failures_total, and units add _seconds/_bytes. Over OTLP the unsuffixed name is what a collector receives.

The scrape endpoint itself is not opened here; it is management.endpoints.prometheus, which is off until you name a level.