docker-compose.adoc

Docker Compose Support

Docker Compose is a popular technology that can be used to define and manage multiple containers for services that your application needs. A compose.yml file is typically created next to your application which defines and configures service containers.

A typical workflow with Docker Compose is to run docker compose up, work on your application with it connecting to started services, then run docker compose down when you are finished.

The spring-boot-docker-compose module can be included in a project to provide support for working with containers using Docker Compose. Add the module dependency to your build, as shown in the following listings for Maven and Gradle:

Maven

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

Gradle

dependencies {
	developmentOnly("org.springframework.boot:spring-boot-docker-compose")
}

When this module is included as a dependency Spring Boot will do the following:

• Search for a compose.yml and other common compose filenames in your working directory

• Call docker compose up with the discovered compose.yml

• Create service connection beans for each supported container

• Call docker compose stop when the application is shutdown

If the Docker Compose services are already running when starting the application, Spring Boot will only create the service connection beans for each supported container. It will not call docker compose up again and it will not call docker compose stop when the application is shutdown.

Tip

Repackaged archives do not contain Spring Boot’s Docker Compose by default. If you want to use this support, you need to include it. When using the Maven plugin, set the excludeDockerCompose property to false. When using the Gradle plugin, {spring-boot-gradle-plugin-docs}#packaging-executable-configuring-including-development-only-dependencies[configure the task’s classpath to include the developmentOnly configuration].

Prerequisites

You need to have the docker and docker compose (or docker-compose) CLI applications on your path. The minimum supported Docker Compose version is 2.2.0.

Service Connections

A service connection is a connection to any remote service. Spring Boot’s auto-configuration can consume the details of a service connection and use them to establish a connection to a remote service. When doing so, the connection details take precedence over any connection-related configuration properties.

When using Spring Boot’s Docker Compose support, service connections are established to the port mapped by the container.

Note

Docker compose is usually used in such a way that the ports inside the container are mapped to ephemeral ports on your computer. For example, a Postgres server may run inside the container using port 5432 but be mapped to a totally different port locally. The service connection will always discover and use the locally mapped port.

Service connections are established by using the image name of the container. The following service connections are currently supported:

Connection Details	Matched on
ActiveMQConnectionDetails	Containers named "symptoma/activemq"
CassandraConnectionDetails	Containers named "cassandra"
ElasticsearchConnectionDetails	Containers named "elasticsearch"
JdbcConnectionDetails	Containers named "gvenzl/oracle-free", "gvenzl/oracle-xe", "mariadb", "mssql/server", "mysql", or "postgres"
MongoConnectionDetails	Containers named "mongo"
Neo4jConnectionDetails	Containers named "neo4j"
OtlpMetricsConnectionDetails	Containers named "otel/opentelemetry-collector-contrib"
OtlpTracingConnectionDetails	Containers named "otel/opentelemetry-collector-contrib"
PulsarConnectionDetails	Containers named "apachepulsar/pulsar"
R2dbcConnectionDetails	Containers named "gvenzl/oracle-free", "gvenzl/oracle-xe", "mariadb", "mssql/server", "mysql", or "postgres"
RabbitConnectionDetails	Containers named "rabbitmq"
RedisConnectionDetails	Containers named "redis"
ZipkinConnectionDetails	Containers named "openzipkin/zipkin".

Custom Images

Sometimes you may need to use your own version of an image to provide a service. You can use any custom image as long as it behaves in the same way as the standard image. Specifically, any environment variables that the standard image supports must also be used in your custom image.

If your image uses a different name, you can use a label in your compose.yml file so that Spring Boot can provide a service connection. Use a label named org.springframework.boot.service-connection to provide the service name.

For example:

services:
  redis:
    image: 'mycompany/mycustomredis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.service-connection: redis

Skipping Specific Containers

If you have a container image defined in your compose.yml that you don’t want connected to your application you can use a label to ignore it. Any container with labeled with org.springframework.boot.ignore will be ignored by Spring Boot.

For example:

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.ignore: true

Using a Specific Compose File

If your compose file is not in the same directory as your application, or if it’s named differently, you can use configprop:spring.docker.compose.file[] in your application.properties or application.yaml to point to a different file. Properties can be defined as an exact path or a path that’s relative to your application.

For example:

spring:
  docker:
    compose:
      file: "../my-compose.yml"

Waiting for Container Readiness

Containers started by Docker Compose may take some time to become fully ready. The recommended way of checking for readiness is to add a healthcheck section under the service definition in your compose.yml file.

Since it’s not uncommon for healthcheck configuration to be omitted from compose.yml files, Spring Boot also checks directly for service readiness. By default, a container is considered ready when a TCP/IP connection can be established to its mapped port.

You can disable this on a per-container basis by adding a org.springframework.boot.readiness-check.tcp.disable label in your compose.yml file.

For example:

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.readiness-check.tcp.disable: true

You can also change timeout values in your application.properties or application.yaml file:

spring:
  docker:
    compose:
      readiness:
        tcp:
          connect-timeout: 10s
          read-timeout: 5s

The overall timeout can be configured using configprop:spring.docker.compose.readiness.timeout[].

Controlling the Docker Compose Lifecycle

By default Spring Boot calls docker compose up when your application starts and docker compose stop when it’s shut down. If you prefer to have different lifecycle management you can use the configprop:spring.docker.compose.lifecycle-management[] property.

The following values are supported:

• none - Do not start or stop Docker Compose

• start-only - Start Docker Compose when the application starts and leave it running

• start-and-stop - Start Docker Compose when the application starts and stop it when the JVM exits

In addition you can use the configprop:spring.docker.compose.start.command[] property to change whether docker compose up or docker compose start is used. The configprop:spring.docker.compose.stop.command[] allows you to configure if docker compose down or docker compose stop is used.

The following example shows how lifecycle management can be configured:

spring:
  docker:
    compose:
      lifecycle-management: start-and-stop
      start:
        command: start
      stop:
        command: down
        timeout: 1m

Activating Docker Compose Profiles

Docker Compose profiles are similar to Spring profiles in that they let you adjust your Docker Compose configuration for specific environments. If you want to activate a specific Docker Compose profile you can use the configprop:spring.docker.compose.profiles.active[] property in your application.properties or application.yaml file:

spring:
  docker:
    compose:
      profiles:
        active: "myprofile"

Using Docker Compose in Tests

By default, Spring Boot’s Docker Compose support is disabled when running tests.

To enable Docker Compose support in tests, set configprop:spring.docker.compose.skip.in-tests[] to false.

When using Gradle, you also need to change the configuration of the spring-boot-docker-compose dependency from developmentOnly to testAndDevelopmentOnly:

Gradle

dependencies {
	testAndDevelopmentOnly("org.springframework.boot:spring-boot-docker-compose")
}