Prerequisites

Required

Java 21

The app requires Java 21 or later. Spring Boot 3.x requires Java 17 as a minimum; Java 21 is recommended as it is the current LTS release and enables Java records, pattern matching, and virtual threads used throughout the codebase.

Check version

    java -version
    # java version "21.0.x" ...

Install — macOS (Homebrew)

    brew install openjdk@21
    echo 'export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc

Install — Ubuntu/Debian

    sudo apt update
    sudo apt install openjdk-21-jdk

Install — Windows (winget)

    winget install Microsoft.OpenJDK.21

Install — SDKMAN (cross-platform)

    sdk install java 21.0.5-tem
    sdk use java 21.0.5-tem

---

Maven 3.9+

Maven is the build tool. Spring Boot 3.3.x requires Maven 3.6.3 or later; Maven 3.9+ is recommended.

Check version

    mvn -version
    # Apache Maven 3.9.x ...

Install — macOS

    brew install maven

Install — Ubuntu/Debian

    sudo apt install maven

Install — Windows

Download from maven.apache.org and add bin/ to your PATH.

Maven wrapper

The project includes mvnw / mvnw.cmd — Maven wrapper scripts that download the correct Maven version automatically. You can use ./mvnw instead of mvn if you prefer not to install Maven globally.

---

Git

git --version
# git version 2.x.x

Install via your OS package manager, git-scm.com, or GitHub Desktop.

---

Optional but recommended

An IDE

Any modern Java IDE works. The two most popular:

IntelliJ IDEA

The recommended IDE for Spring Boot development.

• Download: jetbrains.com/idea
• Community Edition is free and sufficient
• Install the Spring Boot and Thymeleaf plugins for full support
• Open the project by selecting pom.xml

VS Code

Lightweight alternative with good Java support via extensions.

• Install the Extension Pack for Java from Microsoft
• Install the Spring Boot Extension Pack
• Open the project folder

---

Docker (for Redis session clustering)

Required only for production clustering with Redis-backed sessions. Not needed for development or sandbox testing.

docker --version
# Docker version 24.x.x

---

For Epic sandbox testing

A web browser

The SMART EHR launch flow redirects your browser through Epic's authorisation page. Any modern browser works — Chrome, Firefox, Safari, Edge.

An Epic developer account (free)

Required only for testing against Epic's non-production sandbox (the -Pepic profile). Not required for the SMART Health IT sandbox tests which run without any account.

See Epic Registration → for the full setup guide.

The account is free and takes about 10 minutes to set up at fhir.epic.com.

---

Network requirements

The app makes outbound HTTPS requests to:

Endpoint	Purpose	When
launch.smarthealthit.org	SMART Health IT sandbox discovery + auth	-Psmartprofile
fhir.epic.com	Epic sandbox discovery, auth + FHIR API	-Pepic profile
Any hospital's Epic FHIR URL	Production FHIR calls	Production only

If you are behind a corporate proxy or firewall, ensure outbound HTTPS (port 443) to these hosts is permitted.

---

Dependency overview

The following are pulled in automatically by Maven — you do not need to install them separately:

Dependency	Version	Purpose
Spring Boot	3.3.5	Application framework
Spring Security	6.x	Security filter chain, CSRF
Spring Boot OAuth2 Client	6.x	PKCE helpers, token client
HAPI FHIR Client	7.4.5	FHIR R4 API calls
HAPI FHIR Structures R4	7.4.5	Patient, Condition, MedicationRequest models
Thymeleaf	3.x	Server-side HTML templates
WireMock	3.6.0	HTTP mocking in tests
Jackson	2.x	JSON parsing (token responses, discovery docs)

---

Checklist

Before moving to the Quick Start:

• java -version shows Java 21+
• mvn -version shows Maven 3.6.3+
• git --version works
• Outbound HTTPS to launch.smarthealthit.org is accessible (for SMART sandbox)
• Browser available for the OAuth2 redirect

Quick Start →