Docker Compose Support in Spring Boot

1. Overview

Spring Boot 3 has new features like building our application as a GraalVM native image or the Java 17 baseline. However, another relevant support is the one for Docker Compose.

In this tutorial, we’ll see how to integrate a Docker Compose workflow with Spring Boot 3.

2. What Does Spring Boot 3 Docker Compose Support Provide?

Typically, we’d run docker-compose up to start and docker-compose down to stop our containers based on a docker-compose.yml. We can now delegate those Docker Compose commands to Spring Boot 3. While the Spring Boot application starts or stops, it’ll also manage our containers.

Furthermore, it has in-built management for multiple services, such as SQL databases, MongoDB, Cassandra, etc. Therefore, we might not need configuration classes or properties to duplicate in our application resource file.

Finally, we’ll see that we can use this support with custom Docker images and Docker Compose profiles.

3. Setup

We need Docker Compose and Spring Boot 3 to explore this new support.

3.1. Docker Compose

Docker Compose requires the Docker engine already installed. They are easy to install, although there might be differences depending on the OS.

Docker runs as a service in our host. From Docker images, we can run containers as lightweight processes in our system. We can see an image as a layer of multiple images on top of a minimal Linux kernel.

3.2. Spring Boot 3

There are a few ways to set up a Spring Boot 3 project. For example, we can use the Spring initializer from version 3.1.0. However, we always need Spring Boot 3 starter libraries for the dependencies we include in a project.

To start, we add a parent POM:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <relativePath />
</parent>

We want to use REST endpoints for our application, so we need the web dependency;

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

We’ll connect to an example database. There are multiple supports out of the box. We’ll use MongoDB:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>

To check that our application is up and running, we’ll do a check with the Spring Boot Actuator:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Finally, we’ll add the Docker Compose dependency. We may add the optional tag set to true if we want to use other project features but exclude the Docker Compose support:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-docker-compose</artifactId>
    <version>3.1.1</version>
</dependency>

We might look at the Spring Boot Gradle Plugin for BOM-like dependency management if we use Gradle.

4. Spring Boot 3 With Docker Compose Application Kick-Start

We’ll make a Spring Boot 3 application using a MongoDB database. Once we have our spring-boot-docker-compose dependency at startup, our application spins up all the services in the docker-compose.yml file.

4.1. Docker Compose File

First, let’s create a docker-compose.yml file:

version: '3.8'
services:
  db:
    image: mongo:latest
    ports:
      - '27017:27017'
    volumes:
      - db:/data/db
volumes:
  db:
    driver:
      local

4.2. Spring Profile

We need to tell Spring Boot 3 the name of the Docker Compose file and the path to it. We can add this in an application-{profile} properties or YAML file. We’ll use a docker-compose Spring profile. Therefore, we’ll create an application-docker-compose.yml configuration file:

spring:
  docker:
    compose:
      enabled: true
      file: docker-compose.yml

4.3. Database Configuration

We don’t need a database configuration. The Docker Compose Support will create a default one. However, we can still add our MongoDB configuration using a profile, for example:

@Profile("!docker-compose")

This way, we can choose whether to use the Docker Compose support. If we don’t go with a profile, the application will expect a database already running.

4.4. Model

Then, we create a simple Document class for a generic item:

@Document("item")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Item {

    @Id
    private String id;
    private String name;
    private int quantity;
    private String category;
}

4.5. REST Controller

Finally, let’s define a controller with some CRUD operations:

@RestController
@RequestMapping("/item")
@RequiredArgsConstructor
public class ItemController {
    ....
    @PostMapping(consumes = APPLICATION_JSON_VALUE)
    public ResponseEntity<Item> save(final @RequestBody Item item) {
        return ResponseEntity.ok(itemRepository.save(item));
    }
    // other endpoints
}

5. Application Test

We can start the application by launching the main Spring Boot 3 class from our favorite IDE or the command line.

5.1. Application Start

Let’s remember to mention a Spring profile. For example, from the command line, we can use the Spring Boot maven plugin:

mvn spring-boot:run -Pdocker-compose -Dspring-boot.run.profiles=docker-compose

We are also adding a dedicated Maven build profile (-Pdocker-compose) in case others exist.

Now, if we execute docker ps, we’ll see our MongoDb container running:

CONTAINER ID   IMAGE             COMMAND                  CREATED        STATUS            PORTS                                           NAMES
77a9667b291a   mongo:latest      "docker-entrypoint.s…"   21 hours ago   Up 10 minutes     0.0.0.0:27017->27017/tcp, :::27017->27017/tcp   classes-db-1

We can now do some live testing with our application.

5.2. Application Check

We can check that our application is up and running using the actuator endpoint:

curl --location 'http://localhost:8080/actuator/health'

If everything is ok, we should get a 200 status:

{
    "status": "UP"
}

For a database check, let’s add some items with a POST invocation at the endpoint http://localhost:8080/item. For example, let’s see a curl Post request:

curl --location 'http://localhost:8080/item' \
--header 'Content-Type: application/json' \
--data '{
    "name" : "Tennis Ball",
    "quantity" : 5,
    "category" : "sport"
}'

We’ll get a response with the item id generated:

{
    "id": "64b117b6a805f7296d8412d9",
    "name": "Tennis Ball",
    "quantity": 5,
    "category": "sport"
}

5.3. Application Shutdown

Finally, shutting down the Spring Boot 3 application will also stop our container. We can see that by executing docker ps -a:

CONTAINER ID   IMAGE             COMMAND                  CREATED        STATUS                     PORTS     NAMES
77a9667b291a   mongo:latest      "docker-entrypoint.s…"   22 hours ago   Exited (0) 5 seconds ago             classes-db-1

6. Docker Compose Support Features

Let’s quickly illustrate the most relevant Docker Compose support features.

6.1. Service Connections

There are several services that this support will automatically discover at startup. We have seen MongoDB. However, there are others like Redis or ElasticSearch. The service connection will find and use the locally mapped port. We can skip configuration classes or properties. This is done by Spring Boot using the ConnectionDetails abstraction.

6.2. Custom Images

We can use custom Docker images by applying a label:

version: '3.8'
services:
  db:
    image: our-custom-mongo-image
    ports:
      - '27017:27017'
    volumes:
      - db:/data/db
    labels:
      org.springframework.boot.service-connection: mongo
volumes:
  db:
    driver:
      local

6.3. Waiting for Container Readiness

Interestingly, Spring Boot 3 will automatically check for container readiness. Containers can take some time to become fully ready. Therefore, this feature frees us to use the healthcheck command to see whether a container is ready.

6.4. Activating Docker Compose Profiles

We can switch at runtime between different Docker Compose profiles. Our service definition can be complex, so we might want to choose which profile to enable, for example, if we are in a debug or production environment. We can achieve this by using a configuration property:

spring.docker.compose.profiles.active=myprofile

7. Benefits of Docker Compose Support

In a production environment, our docker services can spread across different instances. Therefore, in that case, we might not need this support. However, we can activate a Spring profile that loads from a docker-compose.yml definition for local development only.

This support integrates nicely with our IDE, and we won’t jump back and forth on a command line to start and stop the Docker services.

The support just started with version 3.1. Overall, there are already good features, such as a multiple service connection, a default check for service readiness, and the possibility to use Docker Compose profiles.

8. Conclusion

In this article, we learned about the new Docker Compose support in Spring Boot 3.1.0. We saw how to set up and create a Spring Boot 3 application with it.

Following Spring Boot’s ease of development, this support is handy and already has good features. While starting and stopping an application, Spring Boot 3 manages the lifecycle of our Docker services.