What upgrades and support involve for HAPI FHIR
HAPI FHIR is an Apache 2.0 Java library and server that your organization runs itself, so upgrades and day-to-day support fall to your team or to a partner you hire. Upgrades are usually triggered by a new HAPI FHIR release, a change in the Java runtime that release requires (for example, 8.2.0 requires JDK 17), a database or security issue, a need for a newer FHIR version, or a decision to end support for your current release line. Review the release notes and the versions page for each target before you schedule any work.
Routine maintenance is the part most teams keep in-house: rebuilding the starter image or WAR, applying minor patches, rotating credentials, reviewing logs and tracking security advisories. The short answer is that many teams keep routine patching in-house and bring in a partner for upgrades that touch custom interceptors, schema changes or regulated environments. Custom AuthorizationInterceptor rules and consent logic can change behavior across releases without an obvious failure, and JPA schema changes on PostgreSQL or Microsoft SQL Server need a tested migration path and a rollback plan.
Commercial support is available from Smile CDR, which the HAPI FHIR README points to. DeployOpen is a separate provider and has no partnership with Smile CDR or the HAPI FHIR project. When you compare options, ask each provider which releases they cover, how they test custom interceptors before a change reaches production, who owns the regression suite and what happens to your deployment after the engagement ends. Get those answers in writing before you sign.
What the work includes
Each deliverable below is listed in the written scope agreed before work starts, so the exact set, depth and order can vary by deployment. Every item is a document, plan or tested artifact your team keeps.
Release and compatibility assessment
A written comparison of your running HAPI FHIR version, its JDK and container base, and its dependencies against the target release, such as 8.8.2 or the version agreed in scope. It lists breaking changes, deprecated server settings and FHIR version behavior that affect your resources and clients. Check that every item is tied to a line in your own deployment, not only to release notes.
Java and container runtime plan
A plan for the JDK the target release requires, for example JDK 17 for HAPI FHIR 8.2.0, along with the base image, Tomcat, Jetty or Spring Boot version, and JVM options. It states how the runtime is built, scanned and rolled out in your container platform. Confirm the required JDK for the exact target version before approving the plan.
Reviewed database schema change plan
A schema migration plan for PostgreSQL or Microsoft SQL Server that lists each DDL and data change the new release applies, its estimated lock and runtime impact, and the order of steps. It includes a dry run against a copy of production data and a review by your database owners. Ask who approves the plan and who can stop the migration.
Custom interceptor and provider inventory
A list of every custom interceptor, resource provider, validation rule and configuration property in your server, with the owner, the HAPI FHIR class each one depends on, and its upgrade risk. Components that rely on internal APIs are flagged for rewrite. Keep this inventory under version control so later changes are visible.
Regression suite for custom code
Automated tests that exercise each custom interceptor, provider and configuration path against the current and target releases, using representative FHIR requests and expected responses. The suite runs in CI and covers search parameters, validation, authorization and audit side effects. Confirm with your clinical and security owners which scenarios count as acceptance criteria.
Upgrade run book with rollback
A step-by-step procedure covering pre-checks, backup and restore points, the deployment order, post-upgrade verification and a timed rollback path. It names the trigger conditions for rollback and the database restore method for each scenario. Rehearse the run book in a non-production environment before the production window is booked.
Support model with named responsibilities
A responsibility matrix that assigns each upgrade task, incident type and escalation path to a named role on your team, on DeployOpen, or on a third party such as Smile CDR if you buy commercial support. It records who owns patching, database operations, on-call and vendor contact. Agree this model in writing so that no task is left without an owner after handover.
What drives effort and cost
This table lists the factors that most change the size of a HAPI FHIR upgrade and how to reduce each one before work starts.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Version jumps | Each release between your current and target version can carry API, configuration and schema changes, so skipping releases multiplies the review and test work. | Read the release notes for every intermediate version, record the breaking changes, and ask the partner to quote the path explicitly rather than assuming a single step. |
| Java runtime change | HAPI FHIR 8.2.0 requires JDK 17, so an older JDK on the server, container base image or build pipeline forces a runtime upgrade before the library upgrade. | Confirm the JDK requirement for your exact target version in the HAPI FHIR versions documentation, then check the base image, Tomcat or Spring Boot version and build tooling together. |
| Database schema and migration size | The JPA server applies schema changes between versions, and large tables or long-running migrations extend the outage window and the rollback risk. | Measure table sizes and row counts in a copy of production, rehearse the migration on that copy, and agree a rollback point with the database owner. |
| Custom interceptors and operation overrides | Interceptors and overridden operations depend on internal APIs that may change, and each one needs its own regression tests after the upgrade. | Inventory every interceptor and override, document its purpose, and keep them in a separate module with automated tests so the regression scope is known in advance. |
| Starter customization or custom WAR build | A heavily modified jpaserver starter or a custom WAR diverges from the upstream project, so merging upstream changes becomes a manual task each release. | Keep customizations as thin extensions on the starter where possible, and record every deviation from upstream in a short change log. |
| Number of environments | Development, test, staging and production each need the same upgrade sequence, configuration review and verification, and drift between them causes surprises. | Automate deployment with infrastructure-as-code or Helm values, upgrade lower environments first, and compare configuration between environments before each promotion. |
| FHIR version and terminology or MDM features in use | Enabled features such as terminology services, validation profiles, MDM or partitioning add more code paths and data to check after each change. | Turn off features you do not use, list the enabled modules in the upgrade plan, and test each one against representative data. |
| Compliance evidence for change control | Regulated organizations often need approvals, test records, rollback plans and traceable change tickets before each production change, which adds documentation work. | Agree the evidence list at scoping, generate test reports and deployment logs as part of the pipeline, and confirm with your assessor which records they expect. |
| Production data volume | Larger datasets increase migration duration, reindexing time and the cost of the test copies needed to rehearse the upgrade. | Ask for a data-volume estimate in the quote, use a representative subset only if your change board accepts it, and schedule the production run in a defined maintenance window. |
Project phases and outputs
The sequence moves from an inventory of the running server to a documented, supported target version, with a recorded output at every phase.
Inventory the running version and build
Record the deployed HAPI FHIR version, whether the server is built from the JPA server starter or a custom build, the Java runtime, the database engine and version, and every custom interceptor, configuration file and deployment artifact. The output is a written inventory that the rest of the project checks against. It is complete when the client team has reviewed and signed off on it.
Assess compatibility against the target release
Compare the inventory with the release notes for the target HAPI FHIR version and the HAPI FHIR versions page, including the required JDK, supported database engines and any changed APIs your code calls. The output is a compatibility report listing each blocker, each change to make and each item to confirm with the vendor. Confirm the target release and the timing against your change calendar before work continues.
Build a test environment from production schema
Stand up a non-production environment on the target runtime with a copy of the production database schema, sanitized where health data rules require it. The output is a running test server that starts cleanly, passes a smoke check of core FHIR operations and reports its schema version. Record the copy date so later results can be traced to the same data state.
Run regression tests on interceptors and custom code
Exercise every custom interceptor, the AuthorizationInterceptor rules, search narrowing, validation settings and any custom operations against the target version, using scripted FHIR requests and expected responses. The output is a test log with pass and fail results, and a fix list for each failure. Phase closes when all failures are resolved or formally accepted by the owner of the affected function.
Rehearse the migration with schema change timing and rollback
Run the full upgrade on a staging copy, including the database schema migration, and time each step to set the production window. Test the rollback path by restoring the pre-upgrade backup and confirming the prior version starts and serves data. The output is a rehearsal runbook with step timings, the schema change order, a verified backup and rollback procedure, and the go or no-go criteria. Confirm the production window against your change calendar.
Cut over to production with monitoring
Execute the approved runbook during the agreed window, taking a fresh backup first, then applying the schema migration and the new build, followed by post-deployment FHIR checks. Monitor server logs, database health, error rates and response times for the agreed period. The output is a cutover record with timestamps, check results and any deviations, and confirmation that the rollback point remains available until the owner signs off.
Hand over with a support runbook
Transfer operational knowledge to your team through a support runbook covering the deployed version, configuration, backup and restore steps, upgrade procedure, monitoring alerts, known issues and escalation contacts, followed by a walkthrough with your engineers. The output is the signed runbook and a record of the handover session. It is complete when your team has performed or observed each documented procedure, including the rollback.
What teams keep in-house and what they outsource
This table shows who usually owns each upgrade and support activity for a HAPI FHIR server, the skills each one needs, and where a fixed-scope partner typically takes over versus where the client team must keep control.
| Activity | Usual owner under fixed scope | Skills needed and what stays with the client |
|---|---|---|
| Reading release notes and choosing the target version | Shared: partner drafts the assessment, client approves the target | FHIR and clinical data model knowledge for the client; Java and HAPI FHIR upgrade experience for the partner. Client owns the decision to accept a version against its own clinical and regulatory needs. |
| Java runtime and container patching | Partner, within agreed scope | JDK and base image hardening, rebuild and test of the image. Confirm the JDK version each target HAPI FHIR release requires, such as JDK 17 for 8.2.0 per the HAPI FHIR versions page. |
| Database backup and schema review | Shared: partner runs schema migration review, client owns data and backups | PostgreSQL or SQL Server administration and restore testing. Client keeps the data itself, retention rules and the sign-off on any schema change that affects stored health records. |
| Interceptor and custom code regression testing | Partner builds and runs the test suite; client defines expected behavior | Java development against HAPI FHIR interceptor APIs. Client keeps the business rules, consent logic and clinical expectations that the tests must prove. |
| Security patch triage | Partner monitors and triages; client approves risk acceptance | Vulnerability assessment and dependency analysis. Client decides which risks it accepts and how they affect its security and compliance records. |
| Kubernetes or WAR deployment changes | Partner, within agreed scope | Helm, Kubernetes or Tomcat, Jetty or Wildfly administration. Confirm which deployment path the client runs before scoping. |
| Change control evidence | Shared: partner prepares records, client approves and files them | Documentation of test results, approvals and rollback plans. Client owns its change advisory process and any evidence its assessors expect. |
| On-call response | Usually client, with partner escalation under a retainer | Incident response, log analysis and database recovery. Confirm response hours, escalation paths and who holds production access before scoping a support arrangement. |
What usually goes wrong and how to prevent it
Most HAPI FHIR upgrade problems trace back to a few decisions made before the upgrade starts. Each card names a failure pattern and the check that prevents it.
Java runtime change deferred
HAPI FHIR releases declare the JDK they need, and HAPI FHIR 8.2.0 requires JDK 17. Teams that leave the application server, container base image or build tooling on an older Java runtime usually find out when the new WAR or container fails to start. Check the release notes for the required JDK before choosing a target version, and upgrade the runtime in a non-production environment first.
Schema changes without a rehearsed rollback
Schema changes applied during an upgrade can alter PostgreSQL or Microsoft SQL Server tables in ways a container rollback cannot undo. Take a verified database backup, run the migration against a copy of production-sized data, record how long it takes, and restore the backup to confirm the rollback works. Agree the rollback point and the decision owner before the change window opens.
Custom interceptors break silently
Custom interceptors, such as those enforcing consent, search narrowing or audit behavior, run inside the server and can fail without an error after an upgrade changes the interceptor API or request flow. Without a regression suite, the first sign is often a wrong search result or a missing audit entry. Write automated allow and deny tests for each interceptor and run them against every candidate version.
Embedded H2 kept in production
The JPA server starter defaults to an embedded H2 database, while its documented production options are PostgreSQL and Microsoft SQL Server. MySQL is not supported. Confirm the production datasource is configured and tested before any clinical data is loaded, and check that the default H2 settings were removed from the deployed configuration.
Starter and custom build drift
Teams often start from the hapiproject/hapi image or the starter, then add custom code and configuration in a separate build. Over time the two diverge as properties, interceptors and dependency versions change in one place and not the other. Keep one documented baseline, track each deviation in version control, and compare the starter's configuration with your build during every upgrade.
Unclear ownership of security patches
HAPI FHIR provides security building blocks, not a complete security layer, so the operating team owns the Java runtime, base image, database engine, application server and HAPI FHIR version. When no one is named for each layer, patches wait between teams. Assign an owner and a patch window for each component, and record who approves an out-of-cycle fix.
How the work changes by starting point
A starter deployment from the hapiproject/hapi image, Docker Compose or the Helm chart is the simplest starting point, because the server runs as a packaged image with its configuration held in environment settings and chart values. The plan centers on image versioning and configuration drift.
- Confirm which image tag and chart version you run, and whether your configuration is set through environment variables or a values file.
- Plan to rebuild or re-pull the image for each target release and retest the same configuration against it.
- Check whether the database is still the embedded H2 default, which the starter uses by default, before any production move.
- Include a database backup and a rollback image tag in the change plan.
- Ask the vendor or your team which Java runtime each image release bundles, so JDK changes are not a surprise.
A WAR deployed on an application server means the application server version, its Java runtime and the WAR itself all move together. Upgrades touch the servlet container as well as HAPI FHIR, and the plan has to cover both.
- Record the current application server version, the JDK version and any container-level settings such as connectors, heap sizes and TLS configuration.
- Confirm that the target HAPI FHIR release supports your application server and JDK combination before scheduling changes.
- Plan a staged test on the same container version the production node uses, not a developer instance.
- Re-check any container-specific logging or security configuration that may be overwritten during redeployment.
- Ask whether a rolling redeployment is possible across your nodes, or whether a maintenance window is required.
A Spring Boot custom build, especially one with many interceptors, makes the code your responsibility as well as the platform. Each interceptor is a potential breaking point when HAPI FHIR internals or interfaces change between releases.
- Inventory every custom interceptor, provider and configuration class, and note which HAPI FHIR APIs each one calls.
- Read the release notes for the target version and mark any changed interfaces, deprecated classes or altered defaults.
- Build a regression suite that exercises each interceptor against representative FHIR requests, including failure paths.
- Plan dependency updates for Spring and other libraries together with the HAPI FHIR upgrade, since they are often pinned to each other.
- Ask who owns interceptor code after handover, because the upgrade effort recurs with each release.
The database choice changes the schema migration, backup and tuning work. The starter supports PostgreSQL and Microsoft SQL Server for production, and the upgrade must be checked against whichever one you run.
- For PostgreSQL, plan the schema migration on a restored copy, and confirm the PostgreSQL major version against the target release documentation.
- For Microsoft SQL Server, confirm the supported SQL Server version and collation requirements in the target release notes, and test the migration on a copy.
- Schedule a full backup and a tested restore before the schema change, and time the restore on realistic data volumes.
- Review database roles and privileges, since schema migrations may require rights that the runtime account does not hold.
- Ask your DBA team which maintenance window and rollback point they require.
An older version several releases behind usually means more than one schema change and more accumulated behavior changes to review. The plan shifts from a single upgrade to a sequence of intermediate steps, or a rebuild on a current base.
- Read the release notes for every version between your current release and the target, not only the final one.
- Check the Java requirement at each step, because required JDK versions change across releases; for example, HAPI FHIR 8.2.0 requires JDK 17.
- Determine whether the upgrade must pass through intermediate releases, based on the upgrade guidance in the official documentation.
- Plan a full regression pass for resource behavior, search parameters and validation, since defaults may have changed.
- Ask the vendor or your partner for a written list of breaking changes covering your version range.
In an air-gapped environment, the release artifacts, container images, Helm charts and dependency libraries must be mirrored into your internal registries and repositories before any upgrade can start. The mirror process becomes a planned step with its own verification.
- Identify every artifact the target release needs, including the server image, chart, Maven or Gradle dependencies and any base images.
- Set up an internal artifact repository and container registry, and mirror the exact versions you intend to deploy.
- Verify checksums or signatures of mirrored artifacts against the originals as your security policy requires.
- Plan how security patches reach the environment, including the review and transfer process across the air gap.
- Ask whether the target release has external calls at startup or runtime, such as terminology or validation resources, and plan for them to be served internally.
What you need to provide
Before an upgrade or support engagement starts, the client supplies the materials that let the work be planned against their real server. Start with access to the current deployment and its configuration files: the JPA server starter or WAR settings, application properties, Docker Compose or Helm values, and any Spring Boot overrides. Without these, the team cannot confirm which HAPI FHIR version, Java runtime and database driver are in use today. Your platform or integration engineers should provide them, along with a read-only view of the running environment.
A copy or sample of the database, used for rehearsal, is the input that most affects schedule risk. HAPI FHIR upgrades can change the database schema, so the upgrade must be rehearsed against data that resembles production. The data owner and privacy or security lead should approve the handling rules in writing before any copy leaves the production boundary, including masking, retention, where rehearsal copies live and who can access them. Confirm whether the database is PostgreSQL or Microsoft SQL Server, since the migration path differs.
Source code and build files for custom interceptors, providers and any forked code are needed for regression testing. Interceptors that enforce authorization, consent or search narrowing are the first things to break after a version change, so the team needs the exact code that runs in production, not the version in a repository branch. Your development lead should supply the repository, build scripts and dependency lock information. Also provide a list of integrations and clients, such as EHR connectors, terminology services, bulk data consumers and reporting tools, with the FHIR operations each one uses. Integration owners should confirm this list, because it defines the regression suite.
Next, state the target FHIR version and the features in use, including which resource profiles, terminology services, validation rules, MDM or partitioning you rely on. The product lead and clinical informatics lead should agree on this. Name owners for change approval and for security decisions. These people sign off the upgrade plan, the rollback criteria and any change to authentication or audit logging. Business users should provide test cases or sample resources that reflect real workflows, such as patient lookup, order submission and result retrieval. Finally, share the change calendar and maintenance windows, including freeze periods, so the rehearsal and cutover dates fit around clinical operations.
Frequently asked questions
How much does a HAPI FHIR upgrade cost and how long does it take?
Cost and timing both depend on the distance between your current release and the target, the amount of custom code, and how much testing your FHIR data and workflows need. Cost drivers: the number of custom interceptors, plugins and JPA changes, the database and environment, and the regression scope. Timing drivers: the release notes for each version in the path, your change calendar, and how quickly your team can review test results. DeployOpen does not publish a price list, and fixed-scope work is priced from a written scope. Ask for a quote that separates assessment, code changes, testing, deployment and handover, and states which items recur.
Can our team upgrade HAPI FHIR without a partner?
Yes, a team with Java build skills, database administration experience and automated tests for its FHIR behavior can upgrade HAPI FHIR itself. HAPI FHIR is licensed under the Apache Software License 2.0, so the software does not require a commercial agreement. Your team will need to read the release notes and the versions page for the target release, rebuild and test custom code, plan the database and runtime changes, and keep a tested rollback path. Confirm who will own sign-off and whether you have a non-production environment that matches production.
What does Smile CDR commercial support cover compared with a fixed-scope upgrade?
Smile CDR commercial support is a support relationship with the vendor for the product, which the HAPI FHIR README points to for commercial support. A fixed-scope upgrade from DeployOpen is a defined project: the assessment, the code changes you have agreed in writing, testing, deployment in your infrastructure, and handover. Ask Smile CDR what its support terms include, including response expectations and which versions it covers. Ask DeployOpen to state its deliverables, test evidence and exclusions in the written scope before work starts.
Do custom interceptors need retesting after a HAPI FHIR upgrade?
Yes, custom interceptors should be retested after every upgrade, because interceptor hooks, request handling and related APIs can change between releases. Check the release notes for changes that affect the interceptor types you use, then run automated tests covering each interceptor's allow, deny and modify paths. Authorization, consent and audit interceptors need the most attention, since errors there affect access to health data. Keep fixtures for representative FHIR requests so you can compare results before and after the change.
How do database schema changes and Java version changes affect an upgrade?
Schema changes depend on the target release, so confirm in its release notes whether migrations run automatically or need a documented step. Take a full database backup and test the migration on a copy of realistic production data before cutover. Java requirements also change between releases: HAPI FHIR 8.2.0 requires JDK 17, so an older runtime needs a planned change alongside the library upgrade. Check the versions page for the JDK your target release requires, then confirm your application server, build tooling and custom libraries support it.
How DeployOpen scopes, delivers and supports upgrades
DeployOpen plans HAPI FHIR upgrades as written, fixed-scope work inside infrastructure you control, with the release, Java, database and custom code changes agreed before anything is changed. Ongoing support is available as a retainer once the upgrade is complete.
How we scope
- Inventory your current HAPI FHIR version, JDK, server deployment method and database engine before estimating the work.
- Map each target release and its Java requirement, for example the JDK 17 requirement of HAPI FHIR 8.2.0, against your runtime.
- List every custom interceptor, provider, partition setting and JPA customization that must be re-tested after the change.
- Agree deliverables, environments, acceptance criteria and timelines in writing before the upgrade work starts.
How we build
- Rebuild the upgrade in a non-production environment that mirrors your deployment method, database and identity setup.
- Review the database schema migration steps and confirm the rollback path with a restored backup before production.
- Run regression tests on FHIR operations, validation, terminology and each custom interceptor against the target release.
- Record configuration changes in version control so each environment can be reproduced from the same source.
How we hand over
- Deliver an upgrade runbook with pre-checks, cutover steps, verification queries and the tested rollback procedure.
- Document each custom interceptor, its test cases and the release it was validated against for your future maintainers.
- Walk your platform and Java engineers through the runbook and the regression suite so they can repeat the process.
- Provide a list of open items, deferred changes and any compatibility decisions that your team needs to own.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer, with the scope written before it begins.
- Plan the next upgrade review around new HAPI FHIR releases, so each move is scoped rather than handled as an emergency.
- Confirm with your team whether commercial support from Smile CDR, which the HAPI FHIR README points to, fits your requirements.
