Spring Boot is a popular framework for building microservices in Java. Spring Boot helps make building REST services faster because of a lot of auto configurations and in-build dev tools. Even the simplest Spring Boot REST application comes with an inbuilt Tomcat server to host the service, which implies faster local testing and validation.
However, sometimes, there is a need to test a containerized (or multi-instance) arrangement for a REST service for specific use cases early in the development life cycle e.g. before pushing the service to higher test environments. Also, while a test environment could support containerization (e.g. in PaaS), the same may not be easily possible on a developer’s machine – whether for technical proving (single container, multiple containers) or for replicating more complicated scenarios on local (e.g. service talking to a real database that’s generally only possible in an integration test environment).
That is where a containerization tool can come handy to provide a similar experience to a developer, e.g. by allowing the REST service to run in a container on the developer machine, without the overhead of additional hardware, operating system etc. Once a REST service runs in a container platform locally, it is possible to load additional services (like other REST services or DB etc.) in additional containers like an ecosystem. Docker is one of the containerization platforms that makes this possible.
This article intents to share a simple use case of running a Spring Boot REST service with Docker on a developer’s machine, which should be easily replicable. This is the Part 1 of this article series. Next parts shall bring in more details around multiple-container scenarios however to start with here, we shall cover a single container use case.
Pre-requisites:
To experience the journey as outlined in the article, it is recommended to have the pre-requisites in place before getting on with the technical steps.
- Reading: Basic awareness about Containerization & Docker
- Tool: Installed Docker Desktop – contains multiple Docker services
- Tool: Familiarity with Java (preferably 8 onwards), Spring Boot 3.4.x
- Tool: Installed JDK 17 & Maven (build tool)
- Hardware: Recommended to have at least 08 GB RAM (more the merrier)
Steps:
Create Service
We need to have a REST service that spans up fast and can be verified quickly. To do so, the first step is to create a new skeleton Spring boot service (using Spring Initializer) or as an even faster alternative, please download an already prepared Spring Boot REST service from https://github.com/shitijbhatnagar/tower (unusual name ‘tower’, I know).
As we download and setup the code (e.g. using IntelliJ), let’s have a look at the main Rest Controller (TowerController.java) and note that all it does is to provide a happy path response to the HTTP GET call and log a message (by default goes to console).
Build and Execute Service (on local)
We need to build/compile the service first, using the command mvn clean install. Once successfully through, the Spring Boot executable jar file should be created in the ‘target’ folder. The next step is to run the service using the command mvn spring-boot:run post which, the REST service should start successfully and we should see an output as below.
Verify Service (on local)
The REST service should be accessible (via curl/Postman/browser) by hitting the application URL http://localhost:8085/tower
Also, note that when the application URL is accessed, a new log message should be visible in the Spring boot application log (aka console) as below:
Thus far, we have setup the simple REST service and proven that it works on developer machine, so the next step is to focus on Docker. In preparation, let us create a new folder/directory (we can call it ‘tower’ folder) and copy the Spring Boot executable jar file there. Additional files and artefacts will also be kept in the same folder for easy reference.
Prepare Dockerfile (for a Docker image)
A docker image is a blueprint (via metadata) of what component or service a Docker container will execute. This meta data is captured inside a file called the ‘Dockerfile’ and the docker image is later created using this Dockerfile.
Below are the contents of a Dockerfile that mentions the specific JDK to be used, which port the service will be exposed on, the executable Spring Boot JAR (aka REST service) and how it will be executed inside the container. Please create/save the Dockerfile in the tower folder.
Prepare Docker image
Once the Dockerfile is ready, it can be used to create a docker image using the following command on the command prompt:
docker build -t sb-tower-service:V1 .
Let’s break down the command below
docker build -t is the command to build a new docker/container image with a name:tag
sb-tower-service is the name of the docker image
V1 is the tag associated with the docker image
Please ensure the Docker Desktop tool/service is running prior to building a docker image, otherwise, the image creation will not succeed. Now, once the previous command is executed, an output similar to below should be seen on the command prompt/console.
The newly created docker should also be visible in the Docker Desktop tool (Dashboard -> Images).
An alternative method to check about docker image creation is to execute the command ‘docker images’ on command prompt and it should show the newly created image (i.e. ‘sb-tower-service’) along with other images.
Start Docker container
Once the docker image is created (built and available), it can be used to then create a container (that hosts a running instance of the ‘tower’ REST service). Execute the following command on the command prompt:
docker run -p 8085:8085 sb-tower-service:V1
Let’s break down the command below
docker run – this instructs docker to run a new container with an indicated image
-p indicates port mapping (host port to container port)
8085:8085 - indicates that requests on the host port 8085 (where you can traffic) should be sent to the container’s port 8085 (where container is listening) for servicing
sb-tower-service:V1 – this is the docker image with its tag that was created previously
After executing the command, we should see an output similar to below:
The container (provided a random name by Docker) should be visible in Docker Desktop also, similar to below:
Verify the REST service (running in Docker)
Try hitting the application URL again via CURL/Postman/browser (http://localhost:8085/tower) and we should see an output like below; the only difference is that this time, the service response is coming from the service instance inside Docker container.
Additionally, let’s observe the logs generated by the application by clicking on the container name (in Docker Desktop) and go to Logs tab:
We should be able to see the message “Tower Service is Up” in the container logs.
Summary
We saw how a simple Spring Boot REST service can be containerized using Docker on a developer desktop – no super heavy hardware requirements, no new equipment - with minimum setup. In the Part 2 of the article series, we shall try to cover additional use cases like multi-instances (of same service) and more.
It is also worth nothing that this article focussed more on ‘running commands’ for a closer understanding/experience while there are plug-ins and utilities that can automate some of this.
Would appreciate any feedback for improvement on the approach and content.
Top comments (0)