What a HAPI FHIR implementation involves
A HAPI FHIR implementation starts with a set of decisions, not with installation. HAPI FHIR is a Java API for HL7 FHIR clients and servers, licensed under the Apache Software License 2.0, so the license cost is zero but every other part of a working server is your responsibility. The JPA server starter gives you a complete RESTful FHIR server backed by a database, and it can be deployed as a Docker image, with Docker Compose, with Spring Boot, as a WAR on Tomcat, Jetty or Wildfly, or on Kubernetes with a Helm chart. Choosing among these packaging options, and deciding whether a custom build is needed instead, is the first scoping question.
The core decisions are the FHIR version, the profiles you must conform to, the database, hosting and security. The JPA server documentation covers DSTU2, DSTU3, R4, R4B and R5, so confirm which versions your trading partners, registries or internal consumers actually send and expect before choosing. Profiles, such as national or regional implementation guides, determine validation rules and custom resources. The starter defaults to an embedded H2 database, supports PostgreSQL and Microsoft SQL Server for production, and does not support MySQL. Confirm the database your organization can operate, back up and patch, and confirm the JDK version the chosen release requires (HAPI FHIR 8.2.0 requires JDK 17).
Several situations usually trigger this work: a new clinical data platform, the replacement of a closed or legacy FHIR server, or a regional data exchange where several organizations share records. Each has a different starting point. A replacement project often inherits data and integrations that shape the version and profile choices, while a regional exchange raises partitioning and access questions early. Security is the area most often underestimated. HAPI FHIR does not provide a single security layer, so authentication, authorization, consent, audit logging and network controls must be designed and built around it.
Most teams decide between in-house and partner delivery by looking at Java and FHIR skills. If your engineers already run Java services on Spring or Tomcat and understand FHIR resources, profiles and search, an internal build is realistic. If those skills are thin, a fixed-scope partner engagement with a written list of decisions, deliverables and acceptance tests usually costs less risk than learning on a clinical system. Either way, write down the FHIR version, profiles, database, hosting model and security design before asking for a quote, because those choices drive most of the effort.
What the implementation includes
A typical engagement moves through six work packages, each ending in a named deliverable you keep. The cards show what each package decides and what you receive at the end.
Requirements and FHIR version selection
Scope the resource types, interactions and interfaces the server must expose, then choose the FHIR version: DSTU2, DSTU3, R4, R4B or R5, all covered by the JPA server documentation. Confirm which version your partner systems and certification targets use. You receive a signed decision record with the version, resource scope and open questions.
Profile and terminology design
Define the StructureDefinitions, implementation guide structure and ValueSets your data must conform to, and decide which code systems the terminology services will host. Each profile is tested against sample resources before it is loaded. You receive the profile and terminology package in version control, with a note on which items come from published guides and which are local.
Deployment on the chosen runtime
Build the server on the runtime your operations team already runs: the hapiproject/hapi Docker image, Docker Compose, Spring Boot, a WAR on Tomcat, Jetty or Wildfly, or Kubernetes with the Helm chart. Confirm the JDK version against the release you pick, since HAPI FHIR 8.2.0 requires JDK 17. You receive a deployed non-production environment and the configuration as code that rebuilds it.
Database setup on PostgreSQL or SQL Server
The starter defaults to an embedded H2 database, which is not a production choice. Set up PostgreSQL or Microsoft SQL Server, with schema initialization, connection pooling, backups and service accounts defined for your platform. MySQL is not supported by the starter. You receive provisioning scripts, the connection configuration and a documented backup and restore procedure.
Security design for health data
HAPI FHIR does not ship a single security layer. Design the authentication interceptors, AuthorizationInterceptor rules, CORS policy, consent and search narrowing, and BALP audit logging around your identity provider and data sensitivity. Decide which operations and the testing UI stay enabled in each environment. You receive a security design document with an authorization matrix and open risks.
Validation, testing and handover
Test the server against FHIR conformance expectations, your profiles and the integration flows it serves, then repeat those tests after each configuration change. Write the runbook covering start-up, monitoring, backups and incident steps. You receive test evidence, the runbook and a handover session with the operators who will run the service.
What drives cost and duration
This table lists the decisions and conditions that move HAPI FHIR implementation effort, why each one matters, and how to keep it manageable, so you can compare quotes against the same scope.
| Driver | Why it moves effort | How to keep it down |
|---|---|---|
| Number and complexity of FHIR resource types and profiles | Each resource type and profile needs mapping rules, validation profiles, search parameters and test cases. Custom profiles with extensions and slicing take longer to specify and verify than base resources. | Start with the resource types your first use cases need. Reuse published base or implementation guide profiles where they fit, and defer custom extensions until a use case requires them. |
| FHIR version (DSTU2, DSTU3, R4, R4B or R5) | The version sets the resource structures, search behavior and the implementation guides you can use. Clients and partner systems that speak different versions add translation and test work. | Confirm the version your partners and regulators expect before design starts. Avoid mixing versions in one server without a written reason. |
| JPA starter versus custom build | The JPA server starter covers much of the standard server behavior, so effort goes into configuration and extensions. A custom build means owning server behavior, persistence and upgrade paths, which raises build and maintenance work. | Use the starter as the base and limit changes to interceptors and configuration. Record every departure from the starter so upgrades can be tested against a known list. |
| Custom operations or interceptors | Custom operations, interceptors and providers each need design, code review, tests and regression checks on every HAPI FHIR upgrade. Business rules placed in interceptors are often the largest source of unplanned work. | Write down each custom behavior as a requirement before coding. Keep the count small, keep interceptors single-purpose, and build automated tests for each one. |
| Terminology and validation requirements | Code system loading, value set expansion, external terminology services and strict profile validation add configuration, data loading and performance testing. Validation rules that reject real partner data can drive rework late in the project. | Agree which code systems and value sets are required and where they come from. Test validation against real sample messages from each partner early. |
| MDM and partitioning needs | Master data management matching and partition design change the data model, search behavior and testing scope. Partitioning for tenants, data sources or regions must be designed before data is loaded, and changing it later is costly. | Decide whether MDM and partitioning are needed for the first release. If they are, design partition keys and matching rules in a written design document and test them with representative data. |
| Identity integration | Authentication through your identity provider, authorization rules and consent handling each need separate design and testing. HAPI FHIR does not supply a complete security layer, so identity work is custom work. | Use one identity provider for all clients and document the scopes or roles each client needs. Limit the authorization rules to the resource types and operations in scope. |
| Number of environments | Each environment needs its own database, configuration, certificates, data subsets and deployment pipeline. Test, validation and production environments often multiply setup and maintenance work. | Keep environments consistent through infrastructure as code and a single container image. Limit the number of non-production environments to those that are used for specific tests. |
| Hosting model (cloud, data center or air-gapped) | Air-gapped and data center hosting means you supply the container images, packages, certificates and time sources offline, and some tooling needs manual handling. Cloud hosting shifts work to managed services but adds network and key management design. | Confirm the hosting model and its constraints before scoping. Prepare an internal artifact repository for images and dependencies if the environment is isolated. |
| Data volume and performance targets | Search performance, indexing and database sizing depend on resource counts, search patterns and concurrency. Performance tests and tuning cycles grow with the targets set and the data volume loaded. | State expected volumes, the top search patterns and response targets in the scope. Test with data at realistic volume early so tuning does not happen at the end of the project. |
| Compliance evidence requirements | Assessors look for documented controls, access records, audit logs, change records and test results. Producing this evidence for a FHIR server adds documentation, logging configuration and test work that many teams underestimate. | Ask which controls and evidence your auditor or certification body expects before scope is written. Plan audit logging and change records from the start, and confirm with your assessor what counts as sufficient evidence. |
Project phases and outputs
The sequence moves from agreed requirements to a tested, documented HAPI FHIR server handed over with a production runbook.
Run discovery and agree requirements
We review your clinical use cases, the FHIR version and profiles you need, data volumes, integrating systems and hosting constraints with your clinical informatics and security leads. The output is a set of signed-off requirements listing in-scope resources, interfaces and operational expectations. The step closes when your sponsor signs the document.
Scope the build and fix the timeline
We turn the requirements into a written scope covering the HAPI FHIR release and JDK version, profile and terminology work, the server approach, and the deliverables for each phase. Durations for every phase are set in that written scope, so the timeline is agreed before work starts. The step closes when the scope is accepted in writing.
Decide architecture and database
We compare the JPA server starter with a custom build, choose the deployment model and select PostgreSQL or Microsoft SQL Server with the reasons recorded. The output is an architecture decision record covering hosting, database, partitioning needs and integration points. The step closes when your architecture owner approves the record.
Build the server and profiles
We configure or build the server, load the chosen FHIR version and profiles, and set up terminology and validation behavior. Custom interceptors and operations are built here if the scope includes them. The output is a deployed non-production environment that your team can query, with build and configuration committed to version control.
Design and configure security
We design authentication, the AuthorizationInterceptor rules, TLS, network placement, secrets handling and audit logging using the building blocks HAPI FHIR provides. Controls are mapped to your policy and configured in the non-production environment. The step closes with a security design document reviewed by your security team.
Test functionality and performance
We run conformance and functional tests against the signed-off requirements, then load tests at the volumes agreed in discovery. Failures are logged, fixed and retested. The output is a test report listing results, open defects and accepted risks, which your sponsor reviews before go-live.
Deploy to production and hand over
We deploy to production in the environment you control, run a cutover checklist and confirm monitoring and backups work. We then deliver a production runbook covering start-up, upgrades, backups, restores and escalation, and train your operators on it. The step closes when your team signs the handover checklist.
What teams keep in-house and what they outsource
This table compares the clinical and governance work that informatics teams usually keep with the engineering work often outsourced, along with the skills each part needs, so you can see where your own staff are essential and where a partner or vendor support may fit.
| Work area | Usually kept in-house | Often outsourced | Skills each side needs |
|---|---|---|---|
| Clinical content | Choosing which FHIR resources and data elements the organization uses, and agreeing what clinical meaning they carry | Not usually outsourced, though an implementer may advise on how resources map to source data | Clinical informatics, FHIR modeling, knowledge of your source systems |
| Profile ownership | Owning StructureDefinitions, implementation guides and version decisions after go-live | Initial profile authoring and validation setup, handed over with documentation | FHIR modeling, FHIR profiling and validation tooling, Java for custom validators |
| Business rules and access policy | Deciding who may read or write which data, consent rules and retention periods | Coding the authorization and consent interceptors that enforce those decisions | Privacy and security policy, Java and Spring, HAPI FHIR interceptor APIs |
| Data stewardship and sign-off | Approving data quality thresholds, reconciliation results and go-live readiness | Building reconciliation scripts and reporting that produce the evidence for sign-off | Data governance, SQL, FHIR resource validation |
| Server build and Java configuration | Setting requirements and reviewing the design and version choice | Building the JPA server from the starter or a custom project and configuring it for your needs | Java and Spring, the HAPI FHIR JPA server, JDK 17 for HAPI FHIR 8.2.0 and later |
| Database setup | Approving the database engine, backup targets and recovery objectives | Provisioning PostgreSQL or Microsoft SQL Server, schema setup and tuning | PostgreSQL or SQL Server administration, backup and point-in-time recovery |
| Deployment automation | Owning the target platform, change approval and production access | Writing Docker, Helm or WAR deployment pipelines and environment configuration | Kubernetes, Docker, Helm, CI/CD tooling |
| Security configuration and audit | Defining the threat model, audit retention and who reviews BALP audit logs | Configuring TLS, identity integration, audit logging and locking down the testing UI | Identity and access management, TLS, audit logging, security testing |
| Test automation and support | Acceptance criteria and clinical test cases, plus decisions on upgrades | Regression suites for custom interceptors and upgrade testing, with commercial support from Smile CDR as an option to evaluate | Test automation, Java, HAPI FHIR release notes, and a vendor support comparison |
What usually goes wrong
Most HAPI FHIR problems trace back to decisions made early, before data, clinical requirements and environment limits are understood. Each risk below has a prevention step you can write into the scope.
Fixing the FHIR version too early
Teams often pick FHIR DSTU3, R4, R4B or R5 and a profile set before the clinical data and exchange partners are known. HAPI FHIR's JPA server covers several versions, but the choice shapes resource models, validation and what partners can send. Require a written requirements review that confirms version and profiles before the build starts.
Keeping the H2 default in production
The JPA server starter defaults to an embedded H2 database, which is suited to testing rather than live clinical traffic. Production needs PostgreSQL or Microsoft SQL Server, and MySQL is not supported. Require the scope to name the production database, its sizing, backups and a documented migration off H2 before go-live.
Treating HAPI FHIR as a complete security layer
HAPI FHIR states it does not provide one security layer. It supplies building blocks such as authentication interceptors, AuthorizationInterceptor rules, consent and search narrowing, CORS and BALP audit logging. Require a security design that maps each control to a requirement, with an identity provider, authorization rules and audit coverage all in scope.
Underestimating terminology and validation work
Code systems, value sets, profile validation and terminology services often take more effort than the server installation itself. Load errors and rejected resources usually come from unmapped codes or profiles that were never loaded. Ask for an inventory of code systems and profiles, the sources they come from, and a named owner for each.
Unclear partition design
JPA partitioning assigns each resource to a partition, which can separate tenants, data sources or regions. Choosing partitions after data is loaded makes access rules and reporting harder to change. Require a partition model written before build, covering the partition key, how requests select a partition and how cross-partition queries are handled.
Skipping performance tests on realistic volumes
A server that responds well with sample data can slow sharply under production resource counts, search patterns and concurrent clients. Database indexing and search parameters both affect response times. Require load tests using data volumes and query mixes agreed in the scope, with results recorded before the go-live decision.
How the work changes by starting point
A greenfield server for one application has a narrow scope and few inherited constraints. The work centers on fixing the FHIR version, the resources and profiles the application needs, and the deployment path.
- Scope: one FHIR version, one set of profiles and one consuming application, recorded in a written interface specification.
- Database: PostgreSQL or Microsoft SQL Server for production. The embedded H2 default suits evaluation only, so confirm the engine before the build starts.
- Security: design authentication in front of the server and select the AuthorizationInterceptor rules. HAPI FHIR supplies building blocks, so the access model is your design work.
- Testing: conformance checks against the agreed profiles and load tests sized to the application's read and write pattern.
- Decide first: the FHIR version, the JDK version required by the release you select (the versions page lists JDK 17 for 8.2.0), and the database engine.
Replacing a legacy or closed FHIR server adds scope, because the existing server defines the data, clients and behavior you must match or deliberately change. Undocumented search behavior and custom operations are the most common surprises.
- Scope: an inventory of resources in use, search parameters, operations, clients and interfaces, including behavior that clients depend on without documentation.
- Database: the source data volume and structure shape the migration load path. Choose PostgreSQL or SQL Server for the target and plan the load separately from the build.
- Security: map the source access model to HAPI FHIR building blocks and confirm audit logging requirements before cutover.
- Testing: run old and new servers in parallel with replayed client traffic, and reconcile resource counts and sampled content.
- Decide first: whether the new API must match the old one exactly, the cutover and rollback approach, and who signs off on clinical data reconciliation.
Partitioning places each resource in a partition, which can separate tenants, data sources or regions. The central decision is the partition model and whether one database or several meets your data residency rules.
- Scope: define the partition key (tenant, region or source), the resources each partition holds, and which cross-partition searches are required.
- Database: a shared database with partitions or separate data sources per region. Confirm the choice against your residency requirements and the configurations the partitioning documentation supports.
- Security: partition boundaries must be enforced in every request path, and tests must prove that one tenant cannot read another tenant's data.
- Testing: cross-tenant access tests, regional failover tests and backup restores per partition.
- Decide first: the partition model, residency rules for each region, and how identities map to tenants.
The JPA server starter can run on Kubernetes using a Helm chart. Much of the operational work moves to the platform: cluster administration, ingress, secrets and upgrades of both the chart and the cluster.
- Scope: who owns the cluster, the ingress and TLS termination, and the Helm values that the team will maintain under version control.
- Database: run PostgreSQL or SQL Server outside the chart, through a managed service or an operator, with backups you have tested. Do not use the embedded H2 default for production.
- Security: secrets held in the cluster secret store, network policies, pod security settings and no public exposure of the testing UI.
- Testing: chart upgrade tests in a non-production cluster, rolling restart tests and database restore tests.
- Decide first: the cluster distribution and its owner, the database hosting model, and the policy for pinning image and chart versions.
Air-gapped hosting changes how software and dependencies arrive. Container images, Java dependencies, build tooling and any content the server loads must be mirrored in, verified and approved before use.
- Scope: the artifact transfer process, internal repository mirrors and a release process that works with no internet access. Confirm whether the server fetches any external resources at runtime.
- Database: an on-premises PostgreSQL or SQL Server instance with backups stored on site. Confirm licensing and patch sources for the engine you select.
- Security: no calls to external identity services, certificates issued by your internal authority, offline vulnerability scanning and checksum verification of every bundle.
- Testing: install from the offline bundle on a clean host and run the full test suite without network access.
- Decide first: which runtime the data center supports (Docker, a WAR on Tomcat or Kubernetes), and how updates are transferred and approved.
What you need to provide
Before a HAPI FHIR scope can be fixed, the client has to name owners who can make decisions. Assign a clinical owner and a business owner for requirements and profiles, since they decide which resources, extensions and search parameters the server must support. Also name the people who choose the FHIR version and edition. The supplied facts cover DSTU2, DSTU3, R4, R4B and R5, and the choice drives profile design, validation and client compatibility, so it should be settled early.
Supply a representative sample of data and the use cases that will run against it. Include example messages or extracts from the source systems, the queries clinicians and applications actually issue, and the volumes you expect. Also provide hosting access and a network design: the target cloud account, data center or air-gapped network, ingress path, and which systems are allowed to reach the FHIR endpoint. Confirm whether an existing database or identity service must be used, because that decides whether the team runs PostgreSQL or Microsoft SQL Server and how authentication is wired in.
Provide your security and privacy policy, along with the compliance obligations that apply to the data, such as health privacy rules, retention periods and audit expectations. These documents set the requirements for authorization rules, audit logging and data separation. Confirm also that a dedicated test environment exists, with non-production data and the same database engine as production. Without it, validation and regression testing cannot be run safely.
Settle ownership before handover. Confirm in writing who owns the server, its configuration, its database and its code, and who holds the keys and credentials. Also decide who will run Java and framework upgrades, database schema changes and on-call support after go-live. Ask the implementation partner to document these responsibilities in the handover pack so that the internal team knows what it inherits.
Frequently asked questions
How much does a HAPI FHIR implementation cost and what drives the quote?
The quote follows from a written scope, so cost depends on the decisions made before the build starts. The main drivers are the FHIR versions and profiles in use, whether the JPA server starter covers your needs or a custom build is required, the number of custom interceptors and integrations, the database and hosting platform, security design including identity integration and audit logging, and the volume of data to migrate. DeployOpen does not publish a price list. Ask for the quote to separate one-time work such as scoping, build, testing and handover from recurring work such as support and upgrades.
Can our team build a HAPI FHIR server alone using the open-source packages?
Yes, the packages are licensed under the Apache Software License 2.0, so the software itself carries no license fee. The work is still substantial: Java engineering on the JDK version the release requires (HAPI FHIR 8.2.0 requires JDK 17), database operations, TLS, identity integration, audit logging, regression testing and ongoing upgrades. Check whether your team has these skills in-house and how many people can maintain the server over time. The HAPI FHIR README also points to Smile CDR for commercial support if you want a vendor for that part.
Should we choose PostgreSQL or SQL Server for HAPI FHIR, and why not MySQL?
Choose PostgreSQL or Microsoft SQL Server. The JPA server starter supports both for production use, and MySQL is not supported. Base the choice on the database your organization already operates and can back up, patch and restore, along with the skills your DBAs have. The starter defaults to an embedded H2 database, so plan the production database build, high availability, backup and restore testing as part of the scope from the start.
Which FHIR version should we pick: DSTU2, DSTU3, R4, R4B or R5?
Pick the version that your partner systems, implementation guides and sector requirements use, and confirm it before scoping. The HAPI FHIR JPA server documentation covers DSTU2, DSTU3, R4, R4B and R5. Start by listing the systems you must exchange data with, the profiles they expect and any national or regulatory requirements that apply to you. Supporting more than one version is possible, but it adds mapping, validation and testing effort, which will show up in the quote.
Is the JPA server starter enough, or do we need a custom build?
The starter is enough when your needs fit its standard server: FHIR REST operations, a supported production database, and the built-in terminology, validation and partitioning features that match your use case. A custom build is usually needed when you require bespoke operations, custom interceptors, unusual authorization or consent logic, or packaging inside your own Spring Boot application. Deployment shape is a separate decision, since the starter can run as a Docker image, with Docker Compose, with Spring Boot, as a WAR or on Kubernetes with Helm. List every custom interceptor and integration before choosing.
Does the work include security certification for our environment?
No. DeployOpen does not issue certifications, audit reports or attestations. Within scope, DeployOpen can prepare the controls, configurations and evidence that an assessment will examine, such as access control design, TLS settings, audit logging and backup records. HAPI FHIR provides building blocks rather than a complete security layer, so that design has to be planned explicitly. Independent auditors and certification bodies perform the assessment and issue any attestation. Ask your assessor which control IDs and evidence they expect, and include that list in the written scope.
How DeployOpen scopes and delivers HAPI FHIR work
DeployOpen plans and builds HAPI FHIR servers inside your own infrastructure, starting from written decisions on FHIR version, profiles, database and security. Each stage ends with documented choices your team can review before the next one begins.
How we scope
- Confirm the FHIR version, resource types and profiles the server must support before any build starts.
- Choose between the JPA server starter and a custom build, and record the reasons in writing.
- Agree on PostgreSQL or Microsoft SQL Server as the production database, with the H2 default excluded from production use.
- Define the written scope, deliverables and timeline in a fixed-scope agreement before work begins.
How we build
- Set up the chosen deployment method, such as Docker, Spring Boot, a WAR on Tomcat, Jetty or Wildfly, or Kubernetes with Helm.
- Design the security layer from HAPI FHIR building blocks, including authentication interceptors, AuthorizationInterceptor rules and audit logging.
- Plan partitioning if data must be separated by tenant, source system or region, and test those boundaries.
- Test the server against agreed FHIR conformance checks, custom interceptors and representative clinical data loads.
How we hand over
- Deliver architecture decisions, configuration records and deployment runbooks that your engineers can follow.
- Document the Java version, database schema, interceptor logic and upgrade constraints for the running release.
- Run a handover session with your platform, security and integration teams to confirm ownership of each component.
- Provide test evidence and control documentation so your compliance team and external auditors can review the system.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after the initial build is accepted.
- Plan upgrades across HAPI FHIR releases and Java requirements, with regression testing for custom interceptors.
- Confirm with your team whether commercial support from Smile CDR is needed alongside a DeployOpen retainer.
- Review security configuration and audit logs on a schedule agreed in the retainer scope.
