Shipping it: Docker and GitHub Actions

The library API runs on your laptop. To run it on a server, the server needs the right version of Java, the right settings, a database, and the same steps you followed, in the same order. Miss one and you hear the oldest excuse in software: “it works on my machine”. This lesson packs the app and everything it needs into a container, runs a database next to it with one command, and sets up GitHub to build and test the code on every push, so a broken change is caught before anyone ships it.

Images and containers#

A container image is a packed, read-only bundle: a small Linux file system with everything a program needs (here a Java runtime and your JAR) plus the command that starts it. A containeris that image running, in its own walled-off space on a machine. The same image runs the same way on your laptop, a colleague's laptop and a server, because everything the program relies on is inside it. Docker is the tool most people use to build and run them, and images are shared through a registry such as Docker Hub, the way libraries are shared through Maven Central.

Step 1: one JAR that runs on its own#

Spring Boot's Maven plugin, already in the generated pom.xml, turns mvn package into a fat JAR with Tomcat and every library inside, like the Shade plugin in packaging. Check that it runs before putting it in a container:

The JAR in target is 54,107,012 bytes, about 54 megabytes, and it starts with nothing but Java. (-DskipTests skips the tests to save time here; the CI workflow below runs them.) That one file is what the container will run.

Step 2: a Dockerfile#

To use Docker, install Docker Desktop (on Windows or macOS) or Docker Engine (on Linux) from docs.docker.com. Then put a file called Dockerfile, with no extension, in the project's top folder:

• FROM starts from an existing image. eclipse-temurin:25-jdk is Linux with the Temurin JDK 25 that this course has used throughout; :25-jre has only the runtime, which is smaller.
• WORKDIR picks the folder inside the image, COPY copies files in from your project, and RUN runs a command while the image is built.
• The first stage is only a workshop: it downloads the libraries, then compiles and packages. The second stage starts fresh and copies just the finished JAR across with COPY --from=build. The JDK, Maven's downloads and the source code stay behind, so the final image is much smaller and holds nothing it does not need. This is a multi-stage build.
• Copying pom.xml and fetching the libraries before copying src is a speed trick. Docker reuses unchanged steps from the last build, so after a code change it skips the download and only recompiles.
• EXPOSE 8080 documents the port the app listens on, and ENTRYPOINT is the command a container runs when it starts.

Building and running the image#

docker build -t library . follows the Dockerfile in the current folder (.) and names the result library. The first build takes a while, because it downloads the base images and the libraries. docker run starts a container from the image, and you see the same Spring Boot log as before, now from inside the container. -p 8080:8080 connects port 8080 on your machine to port 8080 in the container; without it the app runs but nothing outside can reach it. Then curl http://localhost:8080/books answers exactly as it did without Docker.

A few more commands cover daily use: docker ps lists running containers with their ids, docker logs followed by an id shows a container's output, docker stop with an id stops it, and docker run -d starts a container in the background instead of taking over the terminal.

Key idea

An image carries the program and everything it needs. If it runs in a container on your machine, it runs the same way on any machine that has Docker.

Step 3: a real database next to the app, with Docker Compose#

The H2 database lives inside the app and forgets everything on restart. A real deployment uses a database server such as PostgreSQL. Docker Compose starts several containers that work together, from one file, compose.yaml. First give the app PostgreSQL's JDBC driver in pom.xml:

• Two services: db runs the official postgres:18 image, and app is built from your Dockerfile.
• Inside Compose, each service is reachable by its name, so the app finds the database at db:5432, the standard PostgreSQL port.
• Spring Boot reads settings from environment variables as well as from application.properties: SPRING_DATASOURCE_URL becomes spring.datasource.url. The same image can then point at a test database or a production one without being rebuilt.
• The db-data volume keeps the database's files outside the container, so the books survive docker compose down and up again.

docker compose up --buildbuilds the app's image and starts both containers, with both logs in one terminal; docker compose down stops and removes them. One command now starts the whole system on any machine with Docker.

Step 4: build and test every push with GitHub Actions#

Continuous integration (CI) means every change is built and tested automatically, as soon as it is pushed, on a clean machine that knows nothing about your laptop. GitHub Actions runs it for repositories on GitHub. A workflow is a YAML file in the folder .github/workflows:

• on says when it runs: on every push to main and on every pull request.
• runs-on: ubuntu-latest asks GitHub for a fresh Linux machine. Each run starts from nothing, which is the point: if the build only works because of something on your laptop, it fails here.
• Each step either uses a published action or runs a command. actions/checkout fetches your code; actions/setup-java installs Temurin JDK 25 and keeps Maven's downloads between runs (cache: maven).
• ./mvnw --batch-mode verify compiles, runs every test and packages the JAR. --batch-mode keeps the log free of progress bars. If any test fails, the command fails and so does the run.

Commit the file and push. The repository's Actions tab lists every run with its log, and each commit and pull request gets a green tick or a red cross. With branch protection turned on in the repository's settings, a pull request with a red cross cannot be merged, so broken code never reaches main. Adding a step that builds the Docker image, or deploys it, turns CI into continuous delivery.

Further reading#

• Getting started, from the Docker documentation
• Multi-stage builds, from the Docker documentation
• Docker Compose, from the Docker documentation
• Building and testing Java with Maven, from the GitHub Actions documentation