Downloading and Running a Product Stack: HAPI FHIR

Install a Container Runtime

We’ll assume you’ve installed Docker Desktop, or are comfortable enough with container technologies to adapt this tutorial for an alternative container runtime.

Declare a Platform Environment

Log in and navigate to your “Account” page. Create a new “Runtime Platform Environment”. A Platform Environment is just a namespace for products you want managed and deployed together. You may define as many as you like, and recreate them at any time.

Configuring and Deploying HAPI FHIR

Navigate to the “Catalog” and search for “hapi”. Click the product listing for HAPI FHIR.

Products that have enabled distribution and deployment features will have a “Configuration Wizard” and other tabs at the bottom of the page, as shown below.

  • Select the “latest” build,
  • Select the “r4” configuration (for default FHIR R4 settings),
  • Select the platform environment you just created, and
  • Click “Add Configuration to Platform”.

HAPI FHIR and all its underlying linked product dependencies — in this case PostgreSQL — will be added to your platform configuration as “tasks”. Once you see a confirmation notice, go back to the catalog and navigate to the “My Environments” page.

My Environments allows you to inspect and tweak product runtime settings prior to deployment. All fields will only affect these specific instances within the selected platform environment. They will not be saved if you remove and recreate them, nor will they be replicated to your other platform environments.

Note: Should the vendor update the software referenced by your chosen build — as is frequently the case with “evergreen” software version release tags such as “latest” — your platform settings will not be modified.

Any runtime parameters available to you are defined and implemented by the vendor, and with few exceptions are specific to the product. Consult the vendor documentation and support materials for details.

Make sure all the “Deploy” check boxes are selected and click “Docker Stack”. The system will generate and download a docker-compose.yml file. Now the real fun begins!

Go to the command line and run:

docker compose -f ~/Downloads/docker-compose.yml up --pull always --remove-orphans

The --pull always option will force checking for a more recent copy of the software version tags prior to running, while --remove-orphans will delete any abandoned containers and software-defined networks that you may have disabled since last spinning up the product stack. Both PostgreSQL and HAPI FHIR should spin up and start. They may take a minute or so to fully boot.

Note: Vendors are required to provide, at minimum, images built to run on the x64 CPU architecture (AMD and Intel) with the Linux kernel. These will generally run on all Windows, macOS, and Linux operating systems as well as M-series ARM CPUs that ship with modern Apple computers, though may require adjustment of Docker Desktop settings depending on your environment. Namely, new Apple machines require Rosetta to be enabled if the product (or any of it’s bundled product dependencies) has not provided an ARM-based product build.

When fully started, HAPI’s web UI should now be running at http://localhost:8080 and a FHIR base URL of http://localhost:8080/fhir, on top of a real PostgreSQL database!

Manually Connecting to the Database

To connect to the PostgreSQL database with the official psql client, open the docker-compose.yml in a text editor and copy the network name under “networks”, in this case skycapp-tutorial_network.

Open a new terminal and, substituting your own network name, run the following:

docker run -it --network skycapp-tutorial_network --rm postgres psql -h postgresql-server -U postgres

The default database password is “password” (no quotes).

You may now run SQL queries!