Skip to content
javahacks.dev
Spring Boot

How to Use Docker Compose Support in Spring Boot 4

Use Spring Boot Docker Compose support to start compose.yaml services automatically in development, wire connections and control lifecycle.

6 min read
Summarize in AI
Flat illustration of a start button surrounded by Spring Boot starters, with the Spring Boot, Gradle and Spring logos.

Running a database and a broker for local development usually means starting Docker Compose in another terminal, remembering to do it, and copying the mapped port into application.properties. Spring Boot can take over all three: when the application starts, so do the services, and the connection settings are worked out from the running containers. The feature arrived in Boot 3.1 and the examples here use Boot 4 with PostgreSQL 17 and Redis 7.

Add the dependency

XML
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-docker-compose</artifactId>
  <scope>runtime</scope>
  <optional>true</optional>
</dependency>

With Gradle the line is developmentOnly("org.springframework.boot:spring-boot-docker-compose"). Marking it as development-only matters, because a production artifact has no business starting containers. The docker CLI with the Compose v2 plugin must be installed on the machine that runs the application.

A compose file that Boot can use

compose.yamlYAML
services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: shop
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: secret
    ports:
      - "5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop"]
      interval: 2s
      timeout: 2s
      retries: 15

  redis:
    image: redis:7
    ports:
      - "6379"

Boot looks in the working directory for compose.yaml, compose.yml, docker-compose.yaml and docker-compose.yml, in that order. The ports entries list only the container port. Docker then picks a free host port, so two projects that both use PostgreSQL never collide on 5432, and Boot reads the real mapping from the running container. The health check is optional but worth writing: it is what lets Boot wait until the database accepts connections rather than racing it.

What happens when you run the application

Start the app from the IDE or with ./mvnw spring-boot:run. Boot runs docker compose up, waits for the services to be ready, then registers connection details for each one it recognises. With the JDBC starter and the PostgreSQL driver on the classpath you set no spring.datasource.url, no username and no password. Boot reads the image name, the mapped port and the POSTGRES_* variables and builds the connection from them. The same applies to Redis, MongoDB, Kafka, RabbitMQ, Elasticsearch and other images Boot knows. The log shows the compose commands it ran, which is the first place to look when something does not start. For a broader look at Compose for Java projects see local development with Compose.

Control the lifecycle

application.propertiesproperties
spring.docker.compose.lifecycle-management=start-and-stop
ValueBehaviour
start-and-stop (default)up at startup, stop at shutdown
start-onlyup at startup, leave running when the app exits
noneDo nothing

start-only makes restarts quicker, because the containers are already warm when the next run begins, and that is a real saving when you restart the application twenty times an hour. stop keeps containers and volumes, so data survives in both modes. Only docker compose down -v, which you run yourself, deletes it. To make shutdown use down instead, set spring.docker.compose.stop.command=down, which gives you a clean database on every run at the price of recreating it.

Choose which services Boot wires

Boot recognises a service from its image name. A custom image, such as an internal build of PostgreSQL, is not recognised, and a label fixes that:

YAML
services:
  postgres:
    image: registry.example.test/team/postgres-with-extensions:17
    labels:
      org.springframework.boot.service-connection: postgres

To keep Boot away from a service it should not touch, such as a tool container, mark it:

YAML
  mailpit:
    image: axllent/mailpit
    labels:
      org.springframework.boot.ignore: true

Profiles select groups of services, which suits a large compose file:

properties
spring.docker.compose.profiles.active=dev

When the compose file is not in the project root

Platform teams often keep infrastructure files elsewhere:

properties
spring.docker.compose.file=../infra/compose.yaml
spring.docker.compose.working-directory=../infra

The working directory matters when the compose file uses relative paths for bind mounts or env files.

A worked first run

Suppose the project has the compose file above and a Spring Data repository that talks to PostgreSQL. With the dependency added and nothing else changed, the first start pulls the two images, which takes a while, and then every later start reuses them. If the application fails on the first run with a connection error although the log shows the containers starting, the health check is the usual cause: without one, Boot considers a container ready as soon as it is running, and PostgreSQL needs another second or two to accept connections. Add the health check from the file above and the error goes away. If a second project on the same machine also uses PostgreSQL, start it as well and notice that nothing collides, because each one received a different host port from Docker.

Schema creation is the next question. Compose support only starts the database, so something still has to create the tables. Use Flyway or Liquibase for anything you want in production, and spring.jpa.hibernate.ddl-auto=update only for throwaway experiments. The pairing of an auto-started database with versioned migrations means a new colleague runs one command and gets a working schema with no manual steps.

Tests and production

By default the support does nothing when tests run (spring.docker.compose.skip.in-tests=true). Tests should not depend on whatever is running on a developer's machine. Use Testcontainers, which starts what each test run needs and removes it afterwards; see Testcontainers at development time, and Testcontainers errors for when Docker cannot be found. For production, keep the dependency out of the artifact and also set spring.docker.compose.enabled=false in the production profile as a second guard.

Troubleshooting

SymptomLikely cause and fix
docker compose not foundInstall Compose v2, or point spring.docker.compose.command at the binary
Slow or flaky startAdd health checks, or use start-only
Authentication failedDetected credentials come from the container environment, so keep the variables in the compose file
Port already in useRemove the host port and publish only the container port
Boot ignores a serviceThe image is not recognised, so add the service-connection label

Keeping the compose file honest

The compose file now serves two audiences: Boot and the people who start the stack by hand. Pin image tags to the versions production runs, avoid latest, and add health checks to every service the application needs. Comment why a service is there, since a service listed without a consumer is deleted by the next tidy-up. Keep credentials in the file simple and clearly fake, as the earlier examples do, and never copy a production secret into a development compose file. If the file grows services that the application does not use, split them into a second file or a profile.

When not to use it

CI pipelines that already provision their services some other way should switch it off, as should anything running in a managed environment with no Docker daemon. It also adds a hard dependency on a running Docker daemon to a plain mvn spring-boot:run, which surprises a new colleague on a machine without Docker. Say so in the README. The behaviour and every property are documented under Docker Compose support in the Spring Boot reference, and the file format is the Compose specification.

Also inDevOps
Taggedhow to
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.