Setting up a FHIR Server Locally

What You Need

Before starting, make sure you have:

• Docker installed on your computer - https://docs.docker.com/get-docker/

Project Structure

Your project has these important files:

├── docker-compose.yml          # Main setup file
├── hapi.application.yaml       # Server configuration
└── hapi.postgress.data/        # Database storage folder

Step 1: Understanding the Docker Compose File

The docker-compose.yaml file is like a recipe that tells Docker how to set up your FHIR server.

version: '3.7'

services:
  fhir:
    container_name: fhir
    image: "hapiproject/hapi:v7.0.0"
    ports:
      - "8080:8080"
    configs:
      - source: hapi
        target: /app/config/application.yaml
    depends_on:
      - db
  db:
    image: postgres:14
    restart: always
    environment:
      POSTGRES_PASSWORD: admin
      POSTGRES_USER: admin
      POSTGRES_DB: hapi
    volumes:
      - ./hapi.postgress.data:/var/lib/postgresql/data

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

Breaking Down Each Part:

Version: version: '3.7'

• This tells Docker which format to use

FHIR Service: fhir:

• container_name: fhir - Names your FHIR server container “fhir”
• image: "hapiproject/hapi:v7.0.0" - Downloads the HAPI FHIR server software
• ports: "8080:8080" - Makes the server available at http://localhost:8080
• configs: - Points to your configuration file
• depends_on: db - Waits for the database to start first

Database Service: db:

• image: postgres:14 - Uses PostgreSQL database version 14
• restart: always - Restarts the database if it crashes
• environment: - Sets up database login details:
  • Username: admin
  • Password: admin
  • Database name: hapi
• volumes: - Saves database data to your computer

Configs Section:

• Links your hapi.application.yaml file to the server

Step 2: Understanding the Configuration File

The hapi.application.yaml file tells your FHIR server how to connect to the database.

spring:
  datasource:
    url: 'jdbc:postgresql://db:5432/hapi'
    username: admin
    password: admin
    driverClassName: org.postgresql.Driver
  jpa:
    properties:
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      hibernate.search.enabled: false

Breaking Down Each Part:

Spring Framework Settings:

• spring: - The framework that runs the FHIR server

Database Connection: datasource:

• url: - Where to find the database (db:5432 means the “db” container on port 5432)
• username: admin - Database login username
• password: admin - Database login password
• driverClassName: - How to talk to PostgreSQL

Database Settings: jpa:

• hibernate.dialect: - Special HAPI FHIR database language
• hibernate.search.enabled: false - Turns off search indexing (saves memory)

Step 3: Starting Your FHIR Server

1. Open Terminal/Command Prompt

   • Navigate to your project folder

2. Start the Server

   docker-compose up -d

   • The -d flag runs it in the background

3. Check if It’s Running

   docker-compose ps

   • You should see both “fhir” and “db” containers running

Step 4: Testing Your Server

1. Open Your Web Browser

   • Go to: http://localhost:8080

2. You Should See

   • The HAPI FHIR server welcome page
   • Links to test the server

3. Test the API

   • Try: http://localhost:8080/fhir/Patient
   • This should return an empty list of patients (normal for a new server)

Step 5: Understanding What Happens

When you run docker-compose up -d:

1. Docker downloads the HAPI FHIR server and PostgreSQL database
2. Database starts with your admin username/password
3. FHIR server starts and connects to the database
4. Your server is ready to store and serve healthcare data

Common Commands

Start the server:

docker-compose up -d

Stop the server:

docker-compose down

View server logs:

docker-compose logs fhir

View database logs:

docker-compose logs db

Restart everything:

docker-compose restart

What’s Stored Where

• Database files: hapi.postgress.data/ folder
• Server logs: Available through Docker commands
• Configuration: hapi.application.yaml file

Security Notes for Beginners

⚠️ Important: This setup is for learning only!

• Username and password are both “admin” (not secure)
• No encryption is used
• Database is accessible without restrictions

For real projects, you’ll need proper security.

Troubleshooting

Server won’t start?

• Check if port 8080 is already used
• Make sure Docker is running

Database connection errors?

• Wait a few seconds for the database to fully start
• Check the logs with docker-compose logs db

Can’t access the server?

• Make sure you’re using http://localhost:8080 (not https)
• Check if containers are running with docker-compose ps

Your server is ready to receive and store healthcare data in the standard FHIR format!