Recipe: Running the IBM FHIR Server behind a Reverse Proxy

A common deployment pattern for the IBM FHIR Server is to run the Application Server behind a reverse proxy (e.g. OpenShift Route, Kubernetes Ingress, NGINX or API Gateway). By default, the IBM FHIR Server runs under the https://localhost:9443/fhir-server/api/v4 context root and URI. With a modest configuration change, one can change to a context root (baseUrl) or use the X-FHIR-FORWARDED-URL to forward the incoming url to the IBM FHIR Server (expected to be from a trusted reverse proxy).

In #1965, the fhirServer/core/externalBaseUrl is a tenant aware configuration that sets the context root and base URL. Note, the fhirServer/core/externalBaseUrl overrides the incomingUrl from X-FHIR-FORWARDED-URL.

This document outlines how to set the externalBaseUrl for the IBM FHIR Server.

Let me show you how to add a set the externalBaseUrl to an IBM FHIR Server container Docker: ibmcom/ibm-fhir-server. This feature requires 4.9.0 or higher.


  1. Prior to 4.9.0, build the Maven Projects and the Docker Build. You should see [INFO] BUILD SUCCESS after each Maven build, and when the Docker build is successful.
mvn clean install -f fhir-examples -B -DskipTests -ntp
mvn clean install -f fhir-parent -B -DskipTests -ntp
docker build -t ibmcom/ibm-fhir-server:latest fhir-install</code></pre>
  1. Download the fhir-server-config.json
curl -L -o fhir-server-config.json \
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  8423  100  8423    0     0  35095      0 --:--:-- --:--:-- --:--:-- 34950
  1. Update the fhir-server-config.json at path fhirServer/core/externalBaseUrl to https://chocolate.fudge.
"externalBaseUrl": "https://chocolate.fudge"
  1. Start the Docker container, and capture the container id. It’s going to take a few moments to start up as it lays down the test database.
docker run -d -p 9443:9443 -e BOOTSTRAP_DB=true \
  -v $(pwd)/fhir-server-config.json:/config/config/default/fhir-server-config.json \
  1. Check the logs until you see:
docker logs a096978867195ff6e610c36cdba77ff423c31c0ad488a7390f42cef6e89e7fd0
[6/16/21, 15:31:34:533 UTC] 0000002a FeatureManage A   CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 17.665 seconds.
  1. Download the Sample Data

curl -L -o Antonia30_Acosta403.json

  1. Load the Sample Data bundle to the IBM FHIR Server
curl -k --location --request POST 'https://localhost:9443/fhir-server/api/v4' \
--header 'Content-Type: application/fhir+json' \
--user "fhiruser:${DUMMY_PASSWORD}" \
--data-binary  "@Antonia30_Acosta403.json" -o response.json
  1. Scan the response.json for any status that is not "status": "201". For example, the status is in the family of User Request Error or Server Side Error.

  2. Check the patient and you’ll see the self and next relation links include https://chocolate.fudge

curl -k --location --request GET 'https://localhost:9443/fhir-server/api/v4/Patient' \
--header 'Content-Type: application/fhir+json' \
--user "fhiruser:${DUMMY_PASSWORD}" \
    "resourceType": "Bundle",
    "id": "37c5abc7-d3e7-4506-b596-9725c59f9b6b",
    "type": "searchset",
    "total": 23,
    "link": [
            "relation": "self",
            "url": "https://chocolate.fudge/Patient?_count=10&_page=1"
            "relation": "next",
            "url": "https://chocolate.fudge/Patient?_count=10&_page=2"
    "entry": [
            "id": "17b123f9a79-bd2011c1-6606-4617-90ed-3187790955b8",
            "fullUrl": "https://chocolate.fudge/Patient/17b123f9a79-bd2011c1-6606-4617-90ed-3187790955b8",
            "resource": {
                "resourceType": "Patient",
                "id": "17b123f9a79-bd2011c1-6606-4617-90ed-3187790955b8",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2021-08-04T17:39:23.385314Z",
                    "tag": [
                            "system": "",
                            "code": "HTEST",
                            "display": "test health data"


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.