Add a 'Docker Compose Support' section to the reference docs

Update the reference documentation with details about the recently
introduced Docker Compose Support.

Closes gh-35026

spring-boot-project/spring-boot-docs/build.gradle

@@ -49,6 +49,7 @@ dependencies {
 	asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure"))
 	asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-autoconfigure"))
 	asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-devtools"))
+	asciidoctorExtensions(project(path: ":spring-boot-project:spring-boot-docker-compose"))
 
 	autoConfiguration(project(path: ":spring-boot-project:spring-boot-autoconfigure", configuration: "autoConfigurationMetadata"))
 	autoConfiguration(project(path: ":spring-boot-project:spring-boot-actuator-autoconfigure", configuration: "autoConfigurationMetadata"))

spring-boot-project/spring-boot-docs/src/docs/asciidoc/features.adoc

@@ -26,6 +26,8 @@ include::features/task-execution-and-scheduling.adoc[]
 
 include::features/testing.adoc[]
 
+include::features/docker-compose.adoc[]
+
 include::features/developing-auto-configuration.adoc[]
 
 include::features/kotlin.adoc[]

spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/docker-compose.adoc

@@ -0,0 +1,210 @@
+[[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.
+
+To help with this workflow, the `spring-boot-docker-compose` module can be used. When this modules is included as a dependency Spring Boot will do the following:
+
+* Search for a `compose.yml` and other common compose filenames in your application directory
+* Call `docker compose up` with the discovered `compose.yml`
+* Create service connection beans for each supported container
+* Call `docker compose down` when the application is shutdown
+
+NOTE: The `docker compose` or `docker-compose` CLI application needs to be on your path in order for Spring Boot’s support to work correctly.
+
+
+
+[[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 my 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
+
+| `ElasticsearchConnectionDetails`
+| Containers named "elasticsearch"
+
+| `JdbcConnectionDetails`
+| Containers named "mariadb", "mysql" or "postgres"
+
+| `MongoConnectionDetails`
+| Containers named "mongo"
+
+| `R2dbcConnectionDetails`
+| Containers named "mariadb", "mysql" or "postgres"
+
+| `RabbitConnectionDetails`
+| Containers named "rabbitmq"
+
+| `RedisConnectionDetails`
+| Containers named "redis"
+
+| `ZipkinConnectionDetails`
+| Containers named "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 add 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[].
+
+TIP: You can also provide your own `ServiceReadinessCheck` implementations and register them in the `spring.factories` file.
+
+
+
+[[features.docker-compose.lifecycle]]
+=== Controlling the Docker Compose Lifecycle
+By default Spring Boot calls `docker compose up` when your application starts and `docker compose down` when it's shutdown.
+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 on application startup and leave it running
+* `start-and-stop` - Start Docker Compose on application startup and stop it on application shutdown
+
+In addition you can use the configprop:spring.docker.compose.startup.command[] property to change if `docker up` or `docker start` is used.
+The configprop:spring.docker.compose.shutdown.command[] allows you to configure if `docker down` or `docker 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
+	      startup:
+	        command: start
+	      shutdown:
+	        command: stop
+	        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"
+----