Skip to main content

Helios FHIR Server Installation Guide

Introduction​

In this document, we provide step-by-step instructions for users to rapidly get up and running with the Helios FHIR Server. These instructions are ideal for developers, system administrators, and users who wish to try out the Helios FHIR Server quickly.

Provided below are installation instructions for:

  • Docker - running Helios FHIR Server in a Docker container
  • Native - running Helios FHIR Server on native hardware such as a developer's laptop or a dedicated server.
  • AWS - running Helios FHIR Server in Amazon Web Services.

The Helios FHIR Server runs on Apache Cassandra, and a Quickstart Guide is also provided below for both Docker and Native Cassandra installations. Apache Cassandra's documentation web site can be found here.

Prerequisites​

Docker Installations​

info

Ensure that you have set your memory setting to at least 24 GB in Settings -> Resources -> Memory. The default value is NOT sufficient for running Helios FHIR Server

Native Installations​

AWS Installations​

Installing Helios FHIR Server​

Docker Install Instructions​

Docker Compose Instructions​

Create a file named docker-compose.yml file with the contents below, then run the following command:

docker compose up

version: '3.8'
services:
  cassandra:
    container_name: cassandra
    image: cassandra:4.1.3
    ports:
      - "9042:9042"
    networks:
      - hfs-network
    restart: unless-stopped
  helios-fhir-server:
    container_name: helios-fhir-server
    image: gcr.io/helios-fhir-server/enterprise-edition:latest
    ports:
      - "8181:8181"
    environment:
      CASSANDRA_PROPERTIES_CONTACTPOINTS: "cassandra"
    networks:
      - hfs-network
    depends_on:
      - cassandra
    restart: unless-stopped
networks:
  hfs-network:
    name: hfs-network
    driver: bridge

Docker Command Instructions​

Alternatively, if you wish to use individual Docker commands and not use a Docker compose file, follow these instructions below. These instructions assume you have completed the Cassandra Docker Install steps.

Startup Helios FHIR Server in a container named helios-fhir-server, connecting to a Cassandra instance named cassandra, on the hfs-network and exposing port 8181 which we will use later to access the administrative user interface with a browser.

docker run -d -p 8181:8181 -e CASSANDRA_PROPERTIES_CONTACTPOINTS=cassandra --name helios-fhir-server --net hfs-network gcr.io/helios-fhir-server/enterprise-edition:latest

During initial startup, the logs will pause at the below messages. Karaf is performing initial installation tasks which may take several minutes. This startup delay only happens on the first startup, and is normal.

INFO [features-3-thread-1] Stopping bundles: INFO [features-3-thread-1] org.ops4j.pax.logging.pax-logging-log4j2/2.1.3

Next, use the /opt/apache-karaf/bin/client command in the Docker Terminal window, or use the following command to connect to your running Helios FHIR Server instance Karaf console.

docker exec -it helios-fhir-server client

Next, check the status using the Helios FHIR Server Karaf Shell.

Native Installation Instructions​

Set $JAVA_HOME to point to your Java 11 installation (macOS)​

export JAVA_HOME=`/usr/libexec/java_home -v 11`

Download the current Helios FHIR Server distribution​

Enterprise Edition Download Link Site

Provider Directory Edition Download Link Site

Extract the Helios FHIR Server distribution​

tar xzvf helios-fhir-server-distributable-{version}-EnterpriseEdition.tar.gz

Start Helios FHIR Server​

cd helios-fhir-server-distribution-{version}
bin/karaf

This starts the Helios FHIR Server and presents you with an interactive shell.

AWS Installation Instructions​

A Reference Architecture and Terraform-based installation instructions have been created to help AWS installations get up and running quickly. The Reference Architecture consists of:

  • A Virtual Private Cloud to isolate all services for the Helios FHIR Server
  • A 3 node Cassandra cluster running in across two availability zones
  • The Helios FHIR Server configured to run in an EKS Cluster, and configured for autoscaling

Please follow the step-by-step instructions here to setup Helios FHIR Server in your AWS account.

Using the Helios FHIR Server Karaf Shell​

At the Karaf prompt, you can try log:tail or bundle:list to interact with the Helios FHIR Server and see some interesting information about the system.

  • log:tail tails the Helios FHIR Server system log. You can inspect this log for a message that looks like the lines below to know when the Helios FHIR Server has completed its startup.
    12:32:55.471 INFO [features-3-thread-1] Deployment finished. Registering FeatureDeploymentListener
    12:32:55.770 INFO [features-3-thread-1] Done.

  • bundle:list lists all the Bundles that are running in the Helios FHIR Server. This can be an easy way to check if your system is healthy and if the features you want are running.

  • See more commands here

Check the health of Helios FHIR Server​

Using the Karaf shell, run the command bundle:list | grep -i failure. This command should show any bundles that failed to startup correctly. An empty result indicates success. Should you have a failure, run the command bundle:diag <failed bundle id> to display the error log for that bundle.

Log in to the Helios FHIR Server interactive web user interface​

Navigate to http://localhost:8181/ui in a browser. You will be prompted to log in, the default credentials are username: admin@heliossoftware.com and password: admin.

From here, you can check the status of the system at a glance on the landing dashboard, configure the system, enable and disable FHIR Resources and Search Parameters, and manage the Helios FHIR Server users.

Post Installation Steps​

After you have verified the above steps, you should perform the follow post-installation steps:

  • Configure Authentication - The Helios FHIR Server ships with open authentication (i.e. no authentication). See the Authentication options and configure for your environment.
  • Configure System Settings - Change the Full URL setting for your environment.
  • Generate a new JWT key pair
    • In the $KARAF_ROOT/etc folder, execute the following commands:
      • mv helios-keystore.jks helios-keystore.jks.old
      • In the next command, change the -alias value from helios to another value of your choice and -storepass from changeit to another value
      • keytool -genkeypair -keystore helios-keystore.jks -alias helios -keyalg RSA -sigalg SHA384withRSA -storepass changeit
    • Change the keystoreAlias and keystorePassword values in Authentication Settings.
  • After you have setup TLS/HTTPS for your server, change blockUnsecureRequests to true in Authentication Settings.
  • If you are using our Reference Architecture, change the default value of require_tls in variables.tf to true.

Cassandra Quickstart Guide​

Cassandra Docker Install​

The easiest way to get started with Cassandra is by using the Cassandra Docker container by running the following series of commands:

First, create a network such that Helios FHIR Server can talk to Cassandra by name. Our network will be called hfs-network.

docker network create -d bridge hfs-network

Next, startup Cassandra in a container named cassandra, exposing the 9042 port so that Helios FHIR Server may connect.

docker run -d -p 9042:9042 --name cassandra --net hfs-network cassandra:4.1.3

Finally, check if Cassandra has started successfully.

Cassandra Native Install​

The instructions below will walk you through the steps for installing Cassandra on your local machine or on a dedicated server.

First, make sure you have Java 11 installed and that it is your current version.

java -version
openjdk version "11.0.12" 2021-07-20
OpenJDK Runtime Environment Homebrew (build 11.0.12+0)
OpenJDK 64-Bit Server VM Homebrew (build 11.0.12+0, mixed mode)

From here, you can follow the instructions provided by Apache Cassandra (Stop when you get to the header Installing the Debian packages)

Alternatively, we have reproduced the necessary steps here:

Download the Apache Cassandra distribution​

Download Link Site

Unpack the Apache Cassandra distribution​

tar xzvf apache-cassandra-4.1.3-bin.tar.gz

Start Apache Cassandra​

cd apache-cassandra-4.1.3
bin/cassandra

Check the Status of Cassandra​

Wait until Cassandra has fully started. You should see a message saying "state jump to NORMAL" followed by "Startup complete" in Cassandra's log output.

Alternatively, use the nodetool utility to check on Cassandra's status.

bin/nodetool status

Once the result is UN, which stands for Up/Normal, the Cassandra installation is ready to use with Helios FHIR Server.