Rob Ferguson

Getting started with HAPI FHIR

Rob Ferguson -

Introduction

HAPI FHIR is an open source implementation of the HL7 FHIR standard for healthcare interoperability.

Getting Started

The easiest way to get started with HAPI FHIR is to use the HAPI FHIR JPA Server Starter Project.

I created a fork of the repository and then cloned the fork:

git clone git@github.com:Robinyo/hapi-fhir-jpaserver-starter.git
cd ~/hapi-fhir-jpaserver-starter

And I configured Git to sync the fork with the upstream repository:

git remote add upstream git@github.com:hapifhir/hapi-fhir-jpaserver-starter.git

To verify the new upstream repository you have specified for your fork:

git remote -v
origin   git@github.com:Robinyo/hapi-fhir-jpaserver-starter.git (fetch)
origin	 git@github.com:Robinyo/hapi-fhir-jpaserver-starter.git (push)
upstream git@github.com:hapifhir/hapi-fhir-jpaserver-starter.git (fetch)
upstream git@github.com:hapifhir/hapi-fhir-jpaserver-starter.git (push)

You should see the URL for your fork as origin, and the URL for the upstream repository as upstream.

Docker Compose

I created a Docker Compose configuration file, as follows:

services:

  hapi-fhir:
    image: robferguson/hapi-fhir-au:8.4.0-3
    container_name: hapi-fhir
    build: .
    restart: unless-stopped
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/${HAPI_FHIR_DB}
      SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER}
      SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
      SPRING_DATASOURCE_DRIVER_CLASS_NAME: org.postgresql.Driver
      SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgresDialect
      SPRING_JPA_PROPERTIES_HIBERNATE_SEARCH_ENABLED: false
    env_file:
      - ./.env
    ports:
      - "8080:8080"
    configs:
      - source: hapi
        target: /app/config/application.yaml
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:17.5-alpine
    container_name: postgres
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${HAPI_FHIR_DB} -U $${POSTGRES_USER}"]
      start_period: 10s
      interval: 30s
      retries: 5
      timeout: 5s
    environment:
      POSTGRES_DB: ${HAPI_FHIR_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    env_file:
      - ./.env
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
    driver: local

configs:
  hapi:
    file: ./hapi.application.yaml

See: docker-compose-fhir-au.yml

I also created an override configuration file:

server:
  max-http-request-header-size: 64KB
spring:
  ai:
    mcp:
      server:
        enabled: true
  main:
    banner-mode: off
hapi:
  fhir:
    fhir_version: R4
    tester:
      home:
        name: Local Tester
        server_address: 'http://localhost:8080/fhir'
        refuse_to_fetch_third_party_urls: false
        fhir_version: R4

See: hapi.application.yaml

To build HAPI FHIR:

mvn clean install

# or

mvn clean install -DskipTests=true

To build a Docker Image:

docker system prune && \
docker container prune && docker volume prune && docker network prune

docker compose -f docker-compose-fhir-au.yml build

To create and start the services:

docker compose -f docker-compose-fhir-au.yml up

The containers may take a minute or two to startup.

Note: Docker Compose will look for an .env file in the current working directory.

Navigate to the Welcome page:

http://localhost:8080

You should see something like:

To stop the services:

docker compose -f docker-compose-fhir-au.yml stop

To remove the services:

docker compose -f docker-compose-fhir-au.yml down

To remove the data volume:

docker volume rm hapi-fhir-jpaserver-starter_postgres_data

To restart the services:

docker compose -f docker-compose-fhir-au.yml up

Web Testpage Overlay

You can customise the Web Testpage Overlay by modifying the templates in the src/main/webapp/WEB-INF/templates directory:

What's Next

In the next post, we'll we'll configure HAPI FHIR to install a FHIR Implementation Guide.

Source Code
Resources