HAPI FHIR

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a subnet in the target region.

Standard_B2ms (2 vCPU / 8 GiB RAM) is a comfortable starting size. HAPI FHIR is a Java Spring Boot application and benefits from the extra memory.

Configure the network security group (NSG) to allow inbound 22/tcp from your management network, 80/tcp for the UI and API, and 443/tcp if you add TLS.

The image serves plain HTTP on port 80. For any use with real patient data, terminate TLS in front of it with your own domain and add FHIR-level authorization. See Maintenance and the Compliance card below.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for HAPI FHIR by SecureAnyCloud, and select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80).

Review the dedicated data disk on the Disks tab. Then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:hapi-fhir-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name hapi-fhir \
  --image sac1647283583153:hapi-fhir-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name hapi-fhir --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active docker.service nginx.service
sudo docker ps

Both services report active, and docker ps shows the hapiproject/hapi:v8.10.0-2 container Up and healthy.

HAPI FHIR listens on the loopback connector 127.0.0.1:8080. nginx fronts the tester UI and the FHIR API on port 80, adds the per-VM HTTP Basic Auth gate, and serves an unauthenticated /healthz. The bundled H2 database is persisted on the dedicated Azure data disk mounted at /var/lib/hapi-fhir.

Step 5 - Retrieve your password

nginx protects both the FHIR tester UI and the FHIR API with HTTP Basic Auth. The username is admin. A unique password is generated on the first boot of your VM and written to a root-only file:

sudo cat /root/hapi-fhir-credentials.txt

This file contains HAPI_FHIR_USERNAME, HAPI_FHIR_PASSWORD, the HAPI_FHIR_URL to open in a browser and the HAPI_FHIR_BASE REST endpoint.

The password is stored on disk only as a bcrypt hash in /var/lib/hapi-fhir/.htpasswd, so no plaintext password ships in the image. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves a health endpoint for load balancers and probes. It requires no authentication:

curl -s http://localhost/healthz

It returns ok. Because this endpoint never requires authentication, you can use it for an Azure Load Balancer health probe.

Step 7 - Confirm authentication and run a FHIR round-trip

Because a password is set on first boot, an unauthenticated request to the FHIR API returns HTTP 401, so nobody reaches your FHIR server without the password.

Run the following to read the per-VM password from the credentials file and prove the round-trip. An unauthenticated request is rejected, a wrong password is rejected, and the correct password returns the FHIR CapabilityStatement. The script then creates and reads back a Patient resource:

PW=$(sudo grep '^HAPI_FHIR_PASSWORD=' /root/hapi-fhir-credentials.txt | cut -d= -f2-)
echo "unauth : $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/fhir/metadata)" echo "wrong pw : $(curl -s -o /dev/null -w '%{http_code}' -u admin:wrong http://127.0.0.1/fhir/metadata)" echo "authed : $(curl -s -o /dev/null -w '%{http_code}' -u admin:$PW http://127.0.0.1/fhir/metadata)"
ID=$(curl -s -u admin:$PW -H 'Content-Type: application/fhir+json' -X POST http://127.0.0.1/fhir/Patient \
  -d '{"resourceType":"Patient","name":[{"family":"Smith","given":["Ada"]}]}' | grep -oP '"id"\s*:\s*"\K[^"]+' | head -1)
echo "created : Patient/$ID"
echo "read back: $(curl -s -o /dev/null -w '%{http_code}' -u admin:$PW http://127.0.0.1/fhir/Patient/$ID)"

The script prints unauth : 401, wrong pw : 401, authed : 200, then the created Patient/<id> and read back : 200. The /fhir/metadata endpoint returns the server's FHIR CapabilityStatement. The Patient you created is now stored in the H2 database on the data disk.

Step 8 - Sign in to the FHIR tester UI

Browse to http://<vm-public-ip>/. When your browser prompts for a username and password, enter admin and the password from Step 5.

The HAPI FHIR tester UI opens on the server home page. The left side lists every FHIR resource type the server supports. The right side shows the server software version, the FHIR base URL and a set of server actions.

Step 9 - Read the server CapabilityStatement

Click Conformance on the server home page. The tester fetches the server's FHIR CapabilityStatement (also reachable directly at /fhir/metadata) and shows the full request and response. This includes the HTTP 200 status and the X-Powered-By: HAPI FHIR 8.10.0 REST Server header.

FHIR clients use the CapabilityStatement to discover which resources and operations this server supports.

Step 10 - Search a FHIR resource

Select Patient from the resource list, open the Search tab and run the search. The tester executes GET /fhir/Patient against the server and returns a FHIR Bundle of the stored Patient resources. It also shows the client code snippet you would use to run the same search from your own application.

Step 11 - Read a single Patient resource

From the search results, read an individual Patient. The tester issues GET /fhir/Patient/<id> and returns the single resource with HTTP 200. The response includes the Content-Location and Last-Modified headers and the resource version history reference.

This is the read interaction every FHIR client uses to retrieve a known resource by id.

Step 12 - Confirm data lives on the dedicated disk

HAPI FHIR's H2 database and the per-VM password file are kept under /var/lib/hapi-fhir on the dedicated Azure data disk. Your FHIR data therefore survives OS changes, and you can resize the disk independently:

findmnt /var/lib/hapi-fhir ls -lh /var/lib/hapi-fhir/db/hapi.mv.db

The mount is backed by a separate Azure data disk that is captured into the image and re-provisioned on every VM. The hapi.mv.db file is the persistent H2 database that holds your FHIR resources.

Maintenance

• Password: The password is set on first boot and stored as a bcrypt entry in /var/lib/hapi-fhir/.htpasswd. To change it, run sudo htpasswd -B /var/lib/hapi-fhir/.htpasswd admin, then sudo systemctl reload nginx.
• FHIR-level authorization: The nginx Basic Auth credential is a single shared gate in front of the whole server, and HAPI FHIR itself ships with no authorization. Add FHIR-level access control so that access is scoped per user and per resource rather than a single shared password. HAPI supports authorization interceptors and SMART-on-FHIR / OAuth2.
• The FHIR API: The REST base is http://<vm-public-ip>/fhir. Point your FHIR client at it with the admin Basic Auth credential. /fhir/metadata returns the CapabilityStatement. The server supports FHIR R4 by default, and the starter also supports R5.
• Persistence and database: FHIR data is stored in the bundled H2 file database under /var/lib/hapi-fhir/db on the data disk. H2 suits evaluation and small single-node workloads. For larger deployments, repoint HAPI at an external PostgreSQL by editing the container's SPRING_DATASOURCE_* environment variables. See the HAPI FHIR JPA Server Starter documentation.
• TLS: The server is plain HTTP on port 80. Front it with TLS (for example certbot with your own domain) and proxy / over :443.
• Storage: All FHIR state lives under /var/lib/hapi-fhir on the data disk. Back up that volume to protect your data.
• Security patches: unattended-upgrades remains enabled, so the OS continues to receive security updates automatically.

Compliance

This image ships as infrastructure: a self-hosted HAPI FHIR server behind a per-VM password. It is not a certified or HIPAA-compliant healthcare product, and nothing here implies certified compliance.

If you store, process or transmit protected health information (PHI), you are solely responsible for implementing and operating the required controls. These include encryption in transit and at rest, FHIR-level authentication and authorization, audit logging, access management, backups and any applicable regulatory obligations (HIPAA, GDPR and others).

Deploy the image inside your own secured, compliant environment. Add TLS and FHIR-level authorization before you use it with real patient data.

Support

SecureAnyCloud provides 24/7 expert support for this image. Email sales@secureanycloud.com to reach the support team.

Deploy on Azure

Launch HAPI FHIR Server R4 R5 on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com