1. Introduction

Participation in this course requires a local development environment. Since competence using Java is a prerequisite for taking the course, much of the content here is likely already installed in your environment.

Software versions do not have to be latest-and-greatest. For the most part, the firm requirement is that

  • your JDK must be at least Java 21

  • the code you submit must be compliant with Java 21 environments

You must manually download and install some of the software locally (e.g., IDE). Some software installations (e.g., MongoDB) have simple Docker options. The remaining set will download automatically and run within Maven. Some software is needed day 1. Others can wait.

Rather than repeat detailed software installation procedures for the various environments, I will list each one, describe its purpose in the class, and direct you to one or more options to obtain. Please make use of the course newsgroup if you run into trouble or have questions.

1.1. Goals

The student will:

  • setup required tooling in local development environment and be ready to work with the course examples

1.2. Objectives

At the conclusion of these instructions, the student will have:

  1. installed Java JDK 21

  2. installed Maven 3

  3. installed a Git Client and checked out the course examples repository

  4. installed a Java IDE (IntelliJ IDEA Community Edition, Eclipse Enterprise, or Eclipse/STS)

  5. installed a Web API Client tool

  6. optionally installed Docker

  7. conditionally installed Mongo

2. Software Setup

2.1. Java JDK (immediately)

You will need a JDK 21 compiler and its accompanying JRE environment immediately in class. Everything we do will revolve around a JVM.

  • For Mac and Unix-like platforms, SDKMan is a good source for many of the modern JDK images.

$ sdk list java | grep 21 | grep ora
               | >>> | 21.0.8       | oracle  | installed  | 21.0.8-oracle
               |     | 21.0.7       | oracle  |            | 21.0.7-oracle
               |     | 21.0.6       | oracle  |            | 21.0.6-oracle
...
Example sdkman JDK install
$ sdk install java 21.0.8-oracle

After installing and placing the bin directory in your PATH, you should be able to execute the following commands and output a version 21.x of the JRE and compiler.

Example Java Version Check
$ java --version
java 21.0.8 2025-07-15 LTS
Java(TM) SE Runtime Environment (build 21.0.8+12-LTS-250)
Java HotSpot(TM) 64-Bit Server VM (build 21.0.8+12-LTS-250, mixed mode, sharing)

$ javac --version
javac 21.0.8

2.2. Git Client (immediately)

You will need a Git client immediately in class. Note that most IDEs have a built-in/internal Git client capability, so the command line client shown here may not be absolutely necessary. If you chose to use your built-in IDE Git client, just translate any command-line instructions to GUI commands. If you have git already installed, it is highly unlikely you need to upgrade.

Download and install a Git Client.

I have git installed through brew on macOS and recently updated using the following brew command.

$ brew upgrade git
If you already have git installed and working — no need for upgrade to latest.
Example git Version Check
$ git version
git version 2.51.0

Checkout the course baseline.

$ git clone https://gitlab.com/ejava-javaee/ejava-springboot.git
...

$ ls | sort
...
assignment-starter
assignment-support
build
common
...
pom.xml

Each week you will want to update your copy of the examples as I updated and release changes.

$ git checkout main   # switches to main branch
$ git pull            # merges in changes from origin
Updating Changes to Modified Directory

If you have modified the source tree, you can save your changes to a new branch using the following:

$ git status           #show me which files I changed
$ git diff             #show me what the changes were
$ git checkout -b new-branch        #create new branch
$ git commit -am "saving my stuff"  #commit my changes to new branch
$ git checkout main    #switch back to course baseline
$ git pull             #get latest course examples/corrections
Saving Modifications to an Existing Branch

If you have made modifications to the source tree while in the wrong branch, you can save your changes in an existing branch using the following:

$ git stash            #save my changes in a temporary area
$ git checkout existing-branch      #go to existing branch
$ git commit -am "saving my stuff"  #commit my changes to existing branch
$ git checkout main    #switch back to course baseline
$ git pull             #get latest course examples/corrections

2.3. Maven 3 (immediately)

You will need Maven immediately in class. We use Maven to create repeatable and portable builds in class. This software build system is rivaled by Gradle. However, everything presented in this course is based on Maven and there is no feasible way to make that optional.

Download and install Maven 3.

Place the $MAVEN_HOME/bin directory in your $PATH so that the mvn command can be found.

Example Maven Version Check
$ mvn --version
Apache Maven 3.9.11 (3e54c93a704957b63ee3494413a2b544fd3d825b)
Maven home: /usr/local/Cellar/maven/3.9.11/libexec
Java version: 21.0.8, vendor: Oracle Corporation, runtime: .../.sdkman/candidates/java/21.0.8-oracle
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "15.6.1", arch: "aarch64", family: "mac"

Setup any custom settings in $HOME/.m2/settings.xml. This is an area where you and I can define environment-specific values referenced by the build.

<?xml version="1.0"?>
<settings xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">

<!-- keep as default
    <localRepository>somewhere_else</localRepository>
-->
    <offline>false</offline>

    <mirrors>
        <!-- uncomment when JHU VPN unavailable
        <mirror>
            <id>ejava-nexus</id>
            <mirrorOf>ejava-nexus,ejava-nexus-snapshots,ejava-nexus-releases</mirrorOf>
            <url>file://${user.home}/.m2/repository/</url>
        </mirror>
        --> (1) (2)
    </mirrors>

    <profiles>
    </profiles>

    <activeProfiles>
      <!-- activate Docker modules when published
      <activeProfile>docker</activeProfile>
      -->
    </activeProfiles>

</settings>
1 make sure your ejava-springboot repository:main branch is up to date and installed (i.e., mvn clean install -f ./build; mvn clean install) prior to using local mirror
2 the URL in the mirror must be consistent with the localRepository value. The value shown here assumes the default, $HOME/.m2/repository value.

Attempt to build the source tree. Report any issues to the course newsgroup.

$ pwd
.../ejava-springboot
$ mvn install -f build
...
[INFO] ----------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------

$ mvn clean install
...
[INFO] ----------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------

2.4. Java IDE (immediately)

You will realistically need a Java IDE very early in class. If you are a die-hard vi, emacs, or text editor user — you can do a lot with your current toolset and Maven. However, when it comes to code refactoring, inspecting framework API classes, and debugging, there is no substitute for a good IDE. I have used Eclipse/STS for many years and some students in previous semester have used Eclipse installations from a previous Java-development course or work experience. They are free and work well. I will actively be using IntelliJ IDEA Community Edition. The community edition is free and contains most of the needed support. The professional edition is available free for 1 year (plus renewals) to anyone supplying a .edu e-mail.

It is up to you what IDE you use. Using something familiar is always the best first choice.

Download and install an IDE for Java development.

Load an attempt to run the examples in

  • app/app-build/java-app-example

2.5. Web API Client tool (not immediately)

Within the first month of the course, it will be helpful for you to have a client that can issue POST, PUT, and DELETE commands in addition to GET commands over HTTP. This will not be necessary until a few weeks into the semester.

Some options include:

  • curl - command line tool popular in Unix environments and likely available for Windows. All of my Web API call examples are done using curl.

  • Postman API Client - a UI-based tool for issuing and viewing web requests/responses. I personally do not like how "enterprisey" Postman has become. It used to be a simple browser plugin tool. However, the free version works and seems to only require a sign-up login.

curl example
$ curl -v -X GET https://ep.jhu.edu/
<!DOCTYPE html>
<html class="no-js" lang="en">
        <head>
...
<title>Johns Hopkins Engineering | Part-Time &amp; Online Graduate Education</title>
...

2.6. Install Docker (not immediately)

We will cover and make use of Docker since it is highly likely that anything you develop professionally will be deployed with Docker or will leverage it in some way. Spring/Spring Boot has also embraced Docker and Testcontainers as their preferred integration environment. There will be time-savings setup of backend databases as well as options in assignments where Docker desired. Once the initial investment of installing Docker has been tackled — software deployments, installation, and executions become very portable and easy to achieve.

I have made Docker optional for the students who cannot install. Let me know where you stand on this installation.

Docker can serve three purposes in class:

  1. automates example database and JMS resource setup

  2. provides a popular example deployment packaging

  3. provides an integration test platform option with Maven plugins or with Testcontainers

Without Docker installation, you will

  1. need to manually install MongoDB native to your environment

  2. be limited to conceptual coverage of deployment and testing options in class

Download and install Docker (called "Docker Desktop" these days).

Example Docker Version Check
$ docker -v
Docker version 28.3.2, build 578ccf6
$ docker-compose -v
Docker Compose version v2.39.1-desktop.1
The Docker Compose capability is now included with Docker via a Docker plugin and executed using docker compose versus requiring a separate docker-compose wrapper. Functionally they are the same. The docker-compose script is only required for some legacy cases.
Legacy docker-compose Wrapper
$ docker compose --help
Usage:  docker compose [OPTIONS] COMMAND
Define and run multi-container applications with Docker
...

$ docker-compose --help
Usage:  docker compose [OPTIONS] COMMAND
Define and run multi-container applications with Docker
...

2.6.1. docker-compose Test Drive

With the course baseline checked out, you should be able to perform the following. Your results for the first execution will also include the download of images.

Start up database resources
$ docker compose -p ejava up -d mongodb postgres (1)(2)
Creating ejava_postgres_1 ... done
Creating ejava_mongodb_1  ... done
1 -p option sets the project name to a well-known value (directory name is default)
2 up starts services and -d runs them all in the background
Shutdown database resources
$ docker compose -p ejava stop mongodb postgres (1)
Stopping ejava_mongodb_1  ... done
Stopping ejava_postgres_1 ... done
$ docker compose -p ejava rm -f mongodb postgres (2)
Going to remove ejava_mongodb_1, ejava_postgres_1
Removing ejava_mongodb_1  ... done
Removing ejava_postgres_1 ... done
1 stop pauses the running container
2 rm removes state assigned to the stopped container. -f does not request confirmation.

2.7. MongoDB (later)

You will need MongoDB in the later 1/3 of the course. It is somewhat easy to install locally, but a mindless snap — configured exactly the way we need it to be — if we use Docker. Feel free to activate a free Atlas account if you wish, but what gets turned in for grading should either use a standard local URL (using Flapdoodle (via Maven), Docker, or Testcontainers).

If you have not and will not be installing Docker, you will need to install and set up a local instance of Mongo.