Skip to main content

First Run

Fire Arrow Server is distributed as a pre-built Docker image from the Evoleen Public ACR (Azure Container Registry):

evoleenpublicacr.azurecr.io/fire-arrow-server-azure

Images are tagged with the release version (e.g. 0.0.60) and latest.

License​

Fire Arrow Server requires a valid license. Contact Evoleen to obtain one for your deployment.

The simplest way to inject a license into the Docker container is via environment variables:

docker run -p 8080:8080 \
  -e FIRE_ARROW_LICENSE_SOURCE=inline \
  -e FIRE_ARROW_LICENSE_CONTENT="<your-license-string>" \
  -e FIRE_ARROW_LICENSE_DEPLOYMENT_ID="<your-deployment-id>" \
  -e FIRE_ARROW_LICENSE_RUNTIME_ENVIRONMENT=nonprod \
  evoleenpublicacr.azurecr.io/fire-arrow-server-azure:latest

Alternatively, you can configure the license in your application.yaml (see Licensing for all options).

Running the Default Image​

The default image ships with an in-memory H2 database, so you can start exploring immediately without any external dependencies beyond the license:

docker run -p 8080:8080 \
  -e FIRE_ARROW_LICENSE_SOURCE=inline \
  -e FIRE_ARROW_LICENSE_CONTENT="<your-license-string>" \
  -e FIRE_ARROW_LICENSE_DEPLOYMENT_ID="<your-deployment-id>" \
  -e FIRE_ARROW_LICENSE_RUNTIME_ENVIRONMENT=nonprod \
  evoleenpublicacr.azurecr.io/fire-arrow-server-azure:latest

This starts Fire Arrow Server on port 8080 with REST and GraphQL enabled. When the server is ready you'll see:

A FHIR has been lit on this server
note

The in-memory database is ephemeral — all data is lost when the container stops. For persistent storage, set up PostgreSQL as described below.

Setting Up PostgreSQL​

Fire Arrow Server uses PostgreSQL as its primary data store in production. Any recent version (14+) is supported.

Installing PostgreSQL​

macOS (Homebrew)
brew install postgresql@16
brew services start postgresql@16
Ubuntu / Debian
sudo apt update
sudo apt install -y postgresql
sudo systemctl enable --now postgresql
Windows

Download and run the installer from the official PostgreSQL site. The installer includes pgAdmin and a command-line shell.

You can also use a managed PostgreSQL service (e.g. Azure Database for PostgreSQL, AWS RDS, or Google Cloud SQL) — just note the host, port, and credentials for the next step.

Creating the Database​

Connect to your PostgreSQL instance as a superuser (e.g. postgres) and run:

CREATE USER hapi WITH PASSWORD 'hapi';
CREATE DATABASE hapi OWNER hapi;
\c hapi
GRANT ALL ON SCHEMA public TO hapi;

This creates a user hapi with password hapi, a database hapi owned by that user, and grants the necessary permissions on the public schema.

tip

On PostgreSQL 15+ the default privileges on the public schema were tightened. The explicit GRANT ALL ON SCHEMA public TO hapi; ensures Fire Arrow Server can create and manage its tables.

Configuring the Datasource​

Point Fire Arrow Server at your PostgreSQL instance by passing environment variables to the container:

docker run -p 8080:8080 \
  -e FIRE_ARROW_LICENSE_SOURCE=inline \
  -e FIRE_ARROW_LICENSE_CONTENT="<your-license-string>" \
  -e FIRE_ARROW_LICENSE_DEPLOYMENT_ID="<your-deployment-id>" \
  -e FIRE_ARROW_LICENSE_RUNTIME_ENVIRONMENT=nonprod \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/hapi \
  -e SPRING_DATASOURCE_USERNAME=hapi \
  -e SPRING_DATASOURCE_PASSWORD=hapi \
  -e SPRING_DATASOURCE_DRIVER_CLASS_NAME=org.postgresql.Driver \
  evoleenpublicacr.azurecr.io/fire-arrow-server-azure:latest

Alternatively, create an application.yaml file and mount it into the container (see Custom Configuration below):

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/hapi
    username: hapi
    password: hapi
    driver-class-name: org.postgresql.Driver
note

When running the Docker container with --network host or docker-compose, localhost refers to the container itself. Use host.docker.internal (macOS/Windows) or the host's IP address to reach a PostgreSQL instance running on the Docker host.

Custom Configuration​

The image supports two mechanisms for overriding the bundled defaults, listed from highest to lowest precedence:

  1. Environment variables — use Spring Boot's relaxed binding (dots become underscores, uppercase), e.g. SPRING_DATASOURCE_URL
  2. External config file — mount or copy a YAML file to /config/application.yaml

Mounting a Configuration File​

You can mount a local configuration file into the container:

docker run -p 8080:8080 \
  -v ./my-application.yaml:/config/application.yaml:ro \
  evoleenpublicacr.azurecr.io/fire-arrow-server-azure:latest

Building a Derived Image​

For production deployments, build a derived image that bakes in your configuration:

FROM evoleenpublicacr.azurecr.io/fire-arrow-server-azure:0.0.60

COPY application.yaml /config/application.yaml

This lets you pin a specific version and bundle environment-specific settings (authentication providers, database connection, authorization rules, etc.) directly into the image. Build args and environment variables can be used for values that differ between environments:

FROM evoleenpublicacr.azurecr.io/fire-arrow-server-azure:0.0.60

ARG MY_OIDC_URI
ENV MY_OIDC_URI=${MY_OIDC_URI}

COPY application.yaml /config/application.yaml

Explore the Server​

Once the server is up, you have three interfaces available:

Swagger UI​

Browse and test every FHIR REST endpoint interactively. See the FHIR REST API overview for details.

http://localhost:8080/fhir/swagger-ui/index.html

GraphQL​

Send GraphQL queries via POST. See GraphQL API overview for query types and patterns.

POST http://localhost:8080/fhir/$graphql

You can use any HTTP client, or the built-in GraphQL explorer in the admin UI (see below).

Admin Web UI​

Manage and inspect your FHIR server through a browser-based administration interface. See the Web UI overview for a full walkthrough.

http://localhost:8080/admin/

The admin UI provides a GraphQL explorer, resource browser, and configuration overview.

Next Steps​

Now that the server is running, head to Minimal Configuration to learn how to configure authentication, authorization, and other features. You may also want to review: