[[features.docker-compose]]
== 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
[source,xml,indent=0,subs="verbatim"]
----
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-docker-compose</artifactId>
			<optional>true</optional>
		</dependency>
	</dependencies>
----

.Gradle
[source,gradle,indent=0,subs="verbatim"]
----
	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].



[[features.docker-compose.prerequisites]]
=== 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.



[[features.docker-compose.service-connections]]
=== 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".
|===



[[features.docker-compose.custom-images]]
=== 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:

[source,yaml,indent=0]
----
	services:
	  redis:
	    image: 'mycompany/mycustomredis:7.0'
	    ports:
	      - '6379'
	    labels:
	      org.springframework.boot.service-connection: redis
----



[[features.docker-compose.skipping]]
=== 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:

[source,yaml,indent=0]
----
	services:
	  redis:
	    image: 'redis:7.0'
	    ports:
	      - '6379'
	    labels:
	      org.springframework.boot.ignore: true
----



[[features.docker-compose.specific-file]]
=== 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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  docker:
	    compose:
	      file: "../my-compose.yml"
----



[[features.docker-compose.readiness]]
=== 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:

[source,yaml,indent=0]
----
	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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  docker:
	    compose:
	      readiness:
	        tcp:
	          connect-timeout: 10s
	          read-timeout: 5s
----

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



[[features.docker-compose.lifecycle]]
=== 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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  docker:
	    compose:
	      lifecycle-management: start-and-stop
	      start:
	        command: start
	      stop:
	        command: down
	        timeout: 1m
----



[[features.docker-compose.profiles]]
=== 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:

[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
	spring:
	  docker:
	    compose:
	      profiles:
	        active: "myprofile"
----



[[features.docker-compose.tests]]
=== 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
[source,gradle,indent=0,subs="verbatim"]
----
	dependencies {
		testAndDevelopmentOnly("org.springframework.boot:spring-boot-docker-compose")
	}
----

