Skip to content
Abyxon Abyxon

Getting Started

This guide will get you from zero to a running FHIR server in about 5 minutes.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose (recommended for quick start)
  • OR: Rust 1.75+ and PostgreSQL 14+

Quick Start with Docker Compose

Section titled “Quick Start with Docker Compose”

  1. Clone the repository

    Terminal window
    git clone https://github.com/octofhir/server-rs.git
    cd server-rs

  2. Start the database

    Terminal window
    docker compose up -d

    This starts PostgreSQL on port 5450 and Redis on port 6380.

  3. Run the server

    Terminal window
    # Download latest release
    curl -LO https://github.com/octofhir/server-rs/releases/latest/download/octofhir-server
    chmod +x octofhir-server
    ./octofhir-server

  4. Verify it’s running

    Terminal window
    curl http://localhost:8888/healthz
    # {"status":"ok"}

Your First FHIR Requests

Section titled “Your First FHIR Requests”

Get the CapabilityStatement

Section titled “Get the CapabilityStatement”
Terminal window
curl -s http://localhost:8888/fhir/metadata | jq '.fhirVersion'
# "4.0.1"

Authenticate

Section titled “Authenticate”

OctoFHIR uses OAuth 2.0. Get an access token with the default admin credentials:

Terminal window
TOKEN=$(curl -s -X POST http://localhost:8888/auth/token \
  -d "grant_type=password&username=admin&password=admin123" \
  | jq -r '.access_token')


echo $TOKEN

Create a Patient

Section titled “Create a Patient”
Terminal window
curl -s -X POST http://localhost:8888/fhir/Patient \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "name": [{"given": ["John"], "family": "Doe"}],
    "birthDate": "1990-01-15",
    "gender": "male"
  }' | jq '.id'
# "550e8400-e29b-41d4-a716-446655440000"

Search for Patients

Section titled “Search for Patients”
Terminal window
curl -s "http://localhost:8888/fhir/Patient?name=John&_count=10" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.entry[].resource.name'

Read a Patient

Section titled “Read a Patient”
Terminal window
curl -s "http://localhost:8888/fhir/Patient/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.'

Configuration

Section titled “Configuration”

The server is configured via octofhir.toml. Key options:

[server]
host = "0.0.0.0"
port = 8888


[storage.postgres]
host = "localhost"
port = 5450
database = "octofhir"


[fhir]
version = "R4"  # R4, R4B, R5, or R6


[bootstrap.admin_user]
username = "admin"
password = "admin123"

Override any option via environment variables:

Terminal window
OCTOFHIR__SERVER__PORT=9000 ./octofhir-server
OCTOFHIR__FHIR__VERSION=R5 ./octofhir-server

Development Setup

Section titled “Development Setup”

For active development with hot reload:

Terminal window
# Install cargo-watch
cargo install cargo-watch


# Run with auto-reload
cargo watch -x 'run --bin octofhir-server'


# Or use just
just dev

Web Console

Section titled “Web Console”

OctoFHIR includes a built-in web console at http://localhost:8888/ui with:

  • Resource browser
  • FHIR search playground
  • SQL console for direct database queries
  • GraphQL playground

Next Steps

Section titled “Next Steps”