Getting started with Docker Compose integration in Spring Boot 3.1

Getting started with Docker Compose integration in Spring Boot 3.1

Spring Boot 3.1 has Docker Compose support. This feature enhances the development experience and removes the overhead of managing containers and ports. With the 3.1 release, Spring Boot automatically detects the random port numbers assigned by the Docker host and sets them in the application at runtime without any configuration or code changes. This article covers getting started with Docker Compose integration Spring Boot 3.1.

Add Spring Boot Docker Compose integration

The first step to use Docker Compose in Spring Boot 3.1 is to add the dependency as follows:


Make sure your project is using Spring Boot 3.1 or above. Otherwise, you cannot use this feature.

The next step is to add a standard docker-compose.yml file to the root directory of your project. For this article, we opted for Elasticsearch:

    image: elasticsearch:8.11.3
    container_name: elasticsearch
      # Map the 9200 port to a random port on host
      - "9200"
      - discovery.type=single-node
      # Since ES 8, SSL is on by default, disabling on local

Note that we do not need to set the host port. It should be left empty to get the maximum benefit of the feature since Spring Boot automatically finds out the port and overrides the application property at the run time. Of course, one can set the port, but that reduces the flexibility.

Supported containers

Spring Boot supports a limited set of containers. For example, if your project uses Kafka, you cannot fully utilize Spring Boot Docker Compose integration out-of-the-box. At the time of writing this article, Spring Boot supports the following Docker containers:

Custom Docker Compose file

If a project has multiple docker-compose files and we want Spring Boot to use a specific file, we can achieve that by setting spring.docker.compose.file property in the application.yml or as follows:


Additionally, we can disable the Docker Compose with setting the following property to false:


When we start the application, we can see in the logs that Spring Boot reads the docker-compose file and then starts the containers. Finally, the application is started and ready to serve. The reverse of it happens when shutting down the application. When using the Docker Compose integration, the application starts up/shutdowns take longer.


In this article, we covered getting Started with Docker Compose integration in Spring Boot 3.1 to ease software development. As always, the fully functional demo is available on GitHub.

Inline/featured images credits