Professional Environment Setup

A reproducible workstation is a set of agreeing versions, not a collection of installed icons. This course deliberately targets Java 21 and the Spring Boot 3.5 maintenance line. Java 21 is a long-term-support release and the course target; it is not the newest LTS. Spring Boot 3.5 requires at least Java 17 and supports newer releases, but using one target across the terminal, IDE, wrapper, and CI removes an entire class of false debugging leads.

Use a trusted JDK distribution from your operating-system package manager or a vendor such as Eclipse Temurin, Microsoft, Oracle, or Amazon Corretto. Follow that vendor’s OS-specific instructions instead of pasting a remote script into a shell. After installation, open a new terminal so PATH changes take effect.

1
2
3
4
5
6
7
8

java --version
javac --version

# macOS and Linux
echo "$JAVA_HOME"

# Windows PowerShell
$env:JAVA_HOME

openjdk 21.x ...\njavac 21.x

java selects the runtime and javac selects the compiler. Both must resolve to a JDK 21 installation. JAVA_HOME should point to the JDK directory, not its bin folder. If the versions disagree, inspect PATH ordering before reinstalling anything. The Maven wrapper prints the JVM it actually uses, which is the decisive build-time check.

IntelliJ IDEA, VS Code, and other Java-capable editors can all complete the course. IntelliJ IDEA Ultimate includes deeper Spring tooling; Community Edition can still edit, compile, test, debug, and run Maven applications. Treat Spring-specific visual assistance as convenience rather than a prerequisite. The application must remain buildable from a plain terminal because CI does not use your IDE configuration.

1
2
3

git --version
./mvnw --version
./mvnw clean verify

Commit .mvn/wrapper, mvnw, and mvnw.cmd. The wrapper pins the Maven distribution used by contributors and CI, while the POM pins the project model. A globally installed mvn can be useful for administration, but course commands use ./mvnw so the repository remains the source of truth.

Docker Desktop is common on macOS and Windows; Docker Engine is common on Linux. Install it from the official Docker documentation, start the daemon, and verify that the client can reach it. Then run PostgreSQL as a disposable course dependency. This check proves the database boundary without assuming a Spring application exists.

1
2
3
4
5
6
7
8
9

docker version
docker run --name course-postgres \
  -e POSTGRES_PASSWORD=course \
  -e POSTGRES_DB=tasks \
  -p 5432:5432 \
  -d postgres:17-alpine

docker exec course-postgres \
  psql -U postgres -d tasks -c "select current_database(), version();"

current_database | version\n-----------------+------------------------------\ntasks            | PostgreSQL 17.x ...

If port 5432 is already occupied, stop the existing database or map a different host port such as -p 5433:5432. Keep credentials local to the exercise and never reuse course passwords for a real environment. The container can be stopped and started without losing its writable layer, or removed after the lesson when you deliberately want a clean database.

One of the most frequent errors when adopting modern Spring Boot is bytecode version incompatibility between the compiler and the target runtime environment.

1
2

# Compiled on Java 21, then executed under an older Java 17 runtime:
java -jar target/task-service-0.0.1-SNAPSHOT.jar

Exception in thread "main" java.lang.UnsupportedClassVersionError: com/example/TaskApplication 
has been compiled by a more recent version of the Java Runtime (class file version 65.0), 
this version of the Java Runtime only recognizes class file versions up to 61.0

When you see UnsupportedClassVersionError, never guess or blindly reinstall. Identify the two numbers in the error: the compiled version (65 = Java 21) and the executing runtime version (61 = Java 17). Align your shell JAVA_HOME or Docker base image to match Java 21.

Run the commands below from the repository root and save the output with secrets removed. This report turns “it does not work on my machine” into a comparison of concrete versions and reachable services. The HTTP check uses Python only as a temporary static server, so it does not pretend that a Spring Actuator endpoint already exists.

1
2
3
4
5
6
7
8
9
10
11

java --version
javac --version
./mvnw --version
git --version
docker version
docker compose version

# Optional independent HTTP smoke test:
python3 -m http.server 8080
# In a second terminal:
curl -i http://localhost:8080/