Skip to main content

System Settings

Introduction​

This document describes the configuration of several system-wide settings for the Helios FHIR Server.

System Settings​

There are three ways to configure these configuration settings.

  • Manually modify the $KARAF_HOME/etc/system.cfg file prior to, or after startup.
  • Use the Helios FHIR Server administrative user interface (Default - http://localhost:8181/ui), Settings menu to view or modify these values. Changes to these values in the administrative user interface will overwrite the values in system.cfg.
  • Use environment variables to override the system.cfg values. This approach is helpful when you need to pass configuration values to a Docker container or otherwise do not wish to modify the values in the system.cfg file.

Each setting section below lists two values.

  • The first is the system.cfg value, and
  • the second is the same value expressed as an environment variable. In the case of the Port number, the etc/org.ops4j.pax.web.cfg file should also be changed to also set org.osgi.service.http.port to the same value.

Port​

The TCP listening port number of the Helios FHIR Server's FHIR API.

port = 8181 # in system.cfg
org.ops4j.pax.web.cfg = 8181 # in org.osgi.service.http.port
SYSTEM_PORT = 8181
ORG_OPS4J_PAX_WEB_ORG_OSGI_SERVICE_HTTP_PORT=8181

Full URL​

The FHIR Specification permits paging of results whereby queries that return a large amount of data may offer additional pages of results in "next" links. The Paging section of the FHIR Specification describes this API feature. The default page size (known as the fetch size in Cassandra) is set in the Fetch Size setting and can be overridden using the _count query parameter.

Helios FHIR Server installations are often setup behind firewalls, or in a separate virtual private network with various port forwarding rules in place. The Helios FHIR Server installation itself is not aware of these networking specifics, yet it is important that the "next" links that are sent to clients must have the correct hostname and port.

For example, an installation may offer a publicly-facing Helios FHIR Server at the following URL: https://fhirserver.example.com/fhir In this example, port 443 traffic would need to be forwarded to port 8181 internally if the port setting above is set to 8181.

Set the Full URL setting to the correct hostname as required for your installation.

fullURL = http://localhost:8181/fhir
SYSTEM_FULLURL = http://localhost:8181/fhir

Auth Token Cache Initial Capacity​

The Helios FHIR Server has an in-memory cache of JSON web tokens (JWTs) that are used in authentication of API requests. Entries will remain in the cache until the JWT Expiry Time has elapsed.

This setting is the initial, pre-allocated capacity size of the JWT cache.

authTokenCacheInitialCapacity = 5
SYSTEM_AUTHTOKENCACHEINITIALCAPACITY = 5

Auth Token Cache Maximum Size​

This setting is the maximum size of the JWT cache. Cache entries will be evicted based on a least recently used algorithm.

authTokenCacheMaximumSize = 10
SYSTEM_AUTHTOKENCACHEMAXIMUMSIZE = 10

JWT Expiry TTL​

The length of time, in seconds, that the JWT will be valid. Defaults to 1 hour (3600 seconds)

jwtExpiryTTLInSeconds = 3600
SYSTEM_JWTEXPIRYTTLINSECONDS = 3600

JWKS Cache Initial Capacity​

JSON Web Key Set (JWKS) is a set of keys, available at a public, open URL, containing the public keys used to verify a JSON Web Token (JWT) issued by an Authorization Server and signed using a signing algorithm. These are the public keys of the client application (NOT the Helios FHIR Server) and the JWKS URI should be supplied to the Helios FHIR Server when registering a client application.

For performance reasons, the Helios FHIR Server maintains an in-memory cache of these keys such that they do not need to be retrieved for each and every JWT verification.

This setting is the initial, pre-allocated capacity size of the JWKS cache.

jwksCacheInitialCapacity = 5
SYSTEM_JWKSCACHEINITIALCAPACITY = 5

JWKS Cache Maximum Size​

This setting is the maximum size of the JWKS cache. Cache entries will be evicted based on a least recently used algorithm.

jwksCacheMaximumSize = 10
SYSTEM_JWKSCACHEMAXIMUMSIZE = 10

JWKS Expiry TTL​

The length of time, in seconds, that the JWKS entry will be valid. Defaults to 24 hours (86400 seconds)

Please note that a JWKS URL may offer a set of keys (perhaps the current key and the new key), and it is a recommended practice to change the kid value when switching to use a new key.

jwksExpiryTTLInSeconds = 86400
SYSTEM_JWKSEXPIRYTTLINSECONDS = 86400

Notification Message Expiry TTL​

The length of time, in seconds, that the Notification Messages, such as Bulk Export Complete, will be displayed in the Dashboard. Defaults to 2 weeks (1209600 seconds)

notificationMessageExpiryTTLInSeconds = 1209600
SYSTEM_NOTIFICATIONMESSAGEEXPIRYTTLINSECONDS = 1209600

Export Path​

A fully qualified path where the Helios FHIR Server will write bulk exported resources.

exportPath = ${karaf.data}/bulk-exports
SYSTEM_EXPORTPATH = [your custom fully qualified path]/bulk-exports

SQL on FHIR Server URL​

The URL of the SQL on FHIR Server.

sqlOnFhirServerURL = http://localhost:3000
SYSTEM_SQLONFHIRSERVERURL = http://localhost:3000

Schema Registry URL​

The URL of the Kafka Schema Registry.

schemaRegistryURL = http://localhost:8281
SYSTEM_SCHEMAREGISTRYURL = http://localhost:8281