Getting Started with FhirHub
#Part 3 of the FhirHub Series*
In Part 2, we examined the architecture. Now let's get FhirHub running on your machine.
Prerequisites
You'll need:
- Docker Desktop (or Docker Engine + Compose) -- for running the infrastructure
- Node.js 20+ -- for the frontend
- Git -- to clone the repository
That's it. No .NET SDK needed locally since the API runs in Docker.
Clone and Start
# Clone the repository
git clone https://github.com/david-le/FhirHub.git
cd FhirHub
# Start the backend infrastructure
cd FhirHubServer
docker-compose up -d
# Start the frontend (in a separate terminal)
cd frontend
npm install
npm run devDocker Compose will pull and start five services:
- PostgreSQL (HAPI FHIR database)
- HAPI FHIR R4 server
- PostgreSQL (Keycloak database)
- Keycloak 26 identity provider
- FhirHub API (.NET 8 gateway)
Verify the Services
Once everything is running, verify each service:
HAPI FHIR Server
curl http://localhost:8080/fhir/metadata | jq '.fhirVersion'
# Expected: "4.0.1"The /fhir/metadata endpoint returns the server's CapabilityStatement. If you see FHIR version 4.0.1, the server is ready.
Keycloak
Open http://localhost:8180 in your browser. You should see the Keycloak admin console. Log in with:
- Username: admin
- Password: admin
Navigate to the fhirhub realm to see the pre-configured clients and roles.
FhirHub API
curl http://localhost:5197/api/dashboard/metricsThe API should return dashboard metrics (or a 401 if authentication is enforced). You can also check the Swagger UI at http://localhost:5197/swagger.
Frontend
Open http://localhost:7002 in your browser. You'll be redirected to the Keycloak login page.
First Login
Log in with one of the pre-configured test accounts. The available roles determine what you can see and do:
| Role | Capabilities |
|---|---|
| admin | Full access to all features including user management and audit logs |
| practitioner | Read/write patients, vitals, conditions, medications, labs, exports |
| nurse | Read patients/vitals/conditions/medications/labs, write vitals, manage alerts |
| front_desk | Read patient demographics only |
| patient | Read own data (vitals, conditions, medications, labs) |
After logging in, you'll land on the dashboard:
Exploring the Application
Dashboard
The dashboard provides an overview of the system:
- Metrics row -- Patient count, observation count, and other aggregate stats
- Recent patients -- Quick access to recently viewed patients
- Activity feed -- Latest clinical events across the system
- Alerts panel -- Clinical alerts for abnormal values
- System status -- Health of backend services
Patient List
Navigate to the patients page to see a searchable, filterable list of all patients:
The patient list supports:
- Text search by name or identifier
- Grid and table view toggle
- Pagination
Patient Detail
Click a patient to see their full clinical record:
The patient detail page is organized into tabs:
- Overview -- Demographics and summary
- Vitals -- Chart and table of vital signs
- Conditions -- Active and resolved diagnoses
- Medications -- Current and discontinued medications
- Labs -- Lab panels with reference ranges
- Timeline -- Chronological view of all events
Project Structure
FhirHub/
├── frontend/ # Next.js 16 frontend
│ ├── src/
│ │ ├── app/ # App Router pages
│ │ │ ├── (auth)/ # Login, register routes
│ │ │ └── (dashboard)/ # Protected dashboard routes
│ │ ├── components/ # React components (60+)
│ │ ├── hooks/ # Custom React hooks
│ │ ├── lib/ # Utilities, clinical rules
│ │ ├── repositories/ # API client layer
│ │ ├── services/ # Business logic
│ │ └── types/ # TypeScript types and DTOs
│ └── package.json
│
├── FhirHubServer/ # Backend infrastructure
│ ├── docker-compose.yml # 5-service orchestration
│ ├── keycloak/
│ │ └── realm-export.json # Pre-configured realm
│ └── src/
│ ├── FhirHubServer.Api/ # API gateway project
│ │ ├── Controllers/ # REST endpoints
│ │ ├── Authorization/ # RBAC policies
│ │ ├── Middleware/ # Security, error handling
│ │ └── Repositories/ # HAPI FHIR data access
│ └── FhirHubServer.Core/ # Shared domain logic
│ ├── DTOs/ # Data transfer objects
│ └── Services/ # Business services
│
└── blog/ # This blog seriesTroubleshooting
Services not starting? Check Docker logs:
cd FhirHubServer
docker-compose logs -fHAPI FHIR takes a while? The HAPI FHIR container has a start_period of 60 seconds. It needs time to run database migrations on first boot.
Keycloak login redirect fails? Make sure the frontend is running on port 7002 -- the Keycloak realm is pre-configured to redirect to http://localhost:7002.
API returns 401? Your Keycloak token may have expired. Refresh the page to trigger a new login flow.
What's Next
In Part 4, we'll dive deep into the SMART on FHIR authentication flow, examining how Keycloak is configured for OIDC with PKCE and how roles are mapped to authorization policies.