ibmcom/ibm-fhir-server

By ibmcom

Updated over 2 years ago

IBM FHIR Server - Universal Base Image

Image

500K+

Overview

The IBM FHIR Server implements version 4.0.1 (R4) of the HL7 FHIR HTTP API and supports the full set of FHIR-defined resource types.

For more information on the server and its capabilities, check the project website.

Run

  1. Run the server

    Starting with version 4.6.0:

    docker run -p 9443:9443 -e BOOTSTRAP_DB=true ibmcom/ibm-fhir-server
    

    For previous versions:

    docker run -p 9443:9443 -e FHIR_TRANSACTION_MANAGER_TIMEOUT=240s ibmcom/ibm-fhir-server
    
  2. Test the server

    curl -k -i -u 'fhiruser:change-password' 'https://localhost:9443/fhir-server/api/v4/$healthcheck'
    

This healthcheck tests the application server's connection to the database and, if successful, should return an HTTP response code of 200 OK:

HTTP/2 200 
date: Wed, 14 Jul 2021 14:17:08 GMT
content-length: 0
content-language: en-US

Previous versions of the IBM FHIR Server also returned an OperationOutcome with a single issue with detail text "All OK".

To learn more about what you can do with this server, please see https://www.hl7.org/fhir/R4/http.html. The default [base] URL for the IBM FHIR Server is https://[host]:9443/fhir-server/api/v4.

Note: Prior to version 4.6.0, the FHIR_TRANSACTION_MANAGER_TIMEOUT setting was required to extend the transaction timeout period for bootstrapping the embedded derby database. Starting with 4.6.0, bootstrapping is opt-in via the BOOTSTRAP_DB environment variable, and the bootstrapping occurs before the server starts (and therefor outside of the server's transaction manager). While suitable for getting up-and-running quickly, we strongly recommend using an external database for doing anything "real".

Configure

The server has two main configuration files.

Starting with version 4.7.0:

  • /opt/ol/wlp/usr/servers/defaultServer/server.xml
  • /opt/ol/wlp/usr/servers/defaultServer/config/default/fhir-server-config.json

For previous versions:

  • /opt/ol/wlp/usr/servers/fhir-server/server.xml
  • /opt/ol/wlp/usr/servers/fhir-server/config/default/fhir-server-config.json

The following sections will provide paths which align with the latest container path (defaultServer).

server.xml

The server.xml format is defined by the OpenLiberty project. Its possible to override specific portions of the default configuration by dropping your extension into /opt/ol/wlp/usr/servers/defaultServer/configDropins/overrides.

Configure ports

The server is installed with only port 9443 (HTTPS) enabled by default. To change the port numbers, modify the values in the httpEndpoint element.

Configure the keystore/truststore

The server is installed with a default keystore file that contains a single self-signed certificate for localhost.

For production use, you must create and configure your own keystore and truststore files for the FHIR server deployment (that is, generate your own server certificate or obtain a trusted certificate, and then share the public key certificate with API consumers so that they can insert it into their client-side truststore).

Configure authentication/authorization

The server is installed with a basic user registry that contains two users:

  • a user named fhiruser with a default password of change-password
  • a user named fhiradmin with a default password of change-password

This default passwords can be overridden by setting the FHIR_USER_PASSWORD and FHIR_ADMIN_PASSWORD environment variables, respectively.

For production use, you must configure authentication/authorization for your own use case. For information about configuring a user registry in Liberty, see https://openliberty.io/guides/security-intro.html#configuring-the-user-registry.

Configure dataSources

By default, the FHIR server is installed with a single Embedded Derby dataSource definition under /opt/ol/wlp/usr/servers/fhir-server/configDropins/defaults with JNDI name jdbc/bootstrap_default_default.

For production use, we recommend either PostgreSQL or IBM Db2. Information on configuring the JDBC persistence layer can be found in the IBM FHIR Server User's Guide.

Starting with version 4.6.0, dataSource definitions must be provided via server.xml configDropins. Sample definitions can be found within the /opt/ol/wlp/usr/servers/defaultServer/configDropins/disabled directory of the image.

fhir-server-config.json

While the server.xml file is for generic Liberty configuration, the fhir-server-config.json file is for configuration that is specific to the IBM FHIR Server.

For a full list of supported properties, see Section 5.1 Configuration properties reference of the User's Guide.

Configure persistence

By default, the FHIR server is installed with the JDBC persistence layer configured to use the single-tenant Embedded Derby dataSource with JNDI name jdbc/bootstrap_default_default.

For production use, we recommend either PostgreSQL or IBM Db2. Information on configuring the JDBC persistence layer can be found in the IBM FHIR Server User's Guide.

To add support for an alternative relational database or "bring your own persistence", see https://ibm.github.io/FHIR/guides/BringYourOwnPersistence.

Configure your IBM FHIR Server with Docker

There are multiple patterns for configuring your IBM FHIR Server in a repeatable pattern.

Copy the configuration as a Layer

Create your own Dockerfile and add a layer to copy your configuration to the image

FROM ibmcom/ibm-fhir-server:your-version
COPY --chown=1001:0 fhir-server-config.json /opt/ol/wlp/usr/servers/defaultServer/config/default
COPY --chown=1001:0 overrides/ /opt/ol/wlp/usr/servers/defaultServer/configDropins/
Put the Configuration into a Volume

Copy the default config directory to a local folder <local_fhir_config_dir>.

Create a folder for server.xml overrides on your local system <local_liberty_overrides_dir>.

Run your Docker with the local folders mounted as volumes.

 docker run -p 9443:9443 \
    -v <local_fhir_config_dir>:/opt/ol/wlp/usr/servers/defaultServer/config \
    -v <local_liberty_overrides_dir>:/opt/ol/wlp/usr/servers/defaultServer/configDropins/overrides \
    ibmcom/ibm-fhir-server

In the local_fhir_config_dir, each tenant should have a configuration folder. For example, for the default tenant, use default/fhir-server-config.json and not just fhir-server-config.json.

Note: other combinations and volume mounts are possible. The power with this technique is that your configuration is not on ephemeral storage.

License

The IBM FHIR Server is licensed under the Apache 2.0 license. Full license text is available at https://github.com/IBM/FHIR/blob/master/LICENSE.


FHIR® is the registered trademark of HL7 and is used with the permission of HL7. Use of the FHIR trademark does not constitute endorsement of this product by HL7.

IBM and the IBM logo are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on ibm.com/trademark.

Docker Pull Command

docker pull ibmcom/ibm-fhir-server