avast/gradle-docker-compose-plugin

The dockerCompose.servicesInfos property contains metadata and information about the running containers.

Important: Because containers are started during the composeUp task, you must access servicesInfos after that task has completed. The best practice is to access this property within the doFirst block of your test or execution task.

test {
    doFirst {
        // Access container info after composeUp has run
        def info = dockerCompose.servicesInfos
        println info
    }
}

You can install the plugin using the Gradle Plugin Portal or via Maven Central.

Option 1: Gradle Plugin Portal (Recommended) Add the plugin to your plugins block:

Option 2: Maven Central Use the buildscript block in your build.gradle file:

Note: Versions prior to 0.14.2 were published to JCenter, which is now decommissioned and unavailable.

// Option 1: Gradle Plugin Portal
plugins {
  id "com.avast.gradle.docker-compose" version "$versionHere"
}

// Option 2: Maven Central
buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "com.avast.gradle:gradle-docker-compose-plugin:$versionHere"
    }
}

apply plugin: 'docker-compose'

You can integrate Docker Compose with your existing Gradle task graph using several methods:

1. Requirement Check: Use dockerCompose.isRequiredBy(anyTask) to indicate that a specific task (like a custom integrationTest task) requires the Docker Compose environment to be running.
2. Artifact Dependencies: If a Dockerfile requires an artifact generated by a Gradle task, declare the dependency using standard Gradle syntax. For example, to ensure a distribution task runs before the containers are started, use composeUp.dependsOn project(':my-app').distTar.

// Example: making a custom task depend on the compose environment
dockerCompose.isRequiredBy(integrationTest)

// Example: ensuring an artifact is built before composeUp
composeUp.dependsOn project(':my-app').distTar

To ensure Docker Compose services are started before a specific Gradle task (like test), use the isRequiredBy method. This ensures docker-compose up is executed in the project directory using your docker-compose.yml file.

When the target task executes a new process, the plugin automatically provides environment variables and Java system properties containing the host and TCP port information for the services, even if ports are assigned randomly by Docker.

dockerCompose.isRequiredBy(test)

You can pass environment variables to the Docker Compose process using the environment map within the dockerCompose configuration block. This is useful for setting the Docker host or service hostnames.

Common use cases:

• DOCKER_HOST: Set the Docker host (e.g., for docker-machine).
• SERVICES_HOST: Set the hostname where services are expected to be listening (useful for remote hosts like CirceCI 2.0).

dockerCompose {
    environment.put 'DOCKER_HOST', '192.168.64.9'
    environment.put 'SERVICES_HOST', 'some-remote-host'
}

By default, the plugin may forcibly delete containers if the composeUp task fails. To keep containers alive for manual inspection and troubleshooting, set retainContainersOnStartupFailure to true.

Note: This setting does not affect the removeContainers behavior; running ComposeDown will still remove the containers.

dockerCompose {
    retainContainersOnStartupFailure = true
}

The plugin supports the Gradle Kotlin DSL. Use the ComposeExtension type to configure the plugin.

import com.avast.gradle.dockercompose.ComposeExtension

apply(plugin = "docker-compose")

configure<ComposeExtension> {
    includeDependencies.set(true)
    createNested("local").apply {
        setProjectName("foo")
        environment.putAll(mapOf("TAGS" to "feature-test,local"))
        startedServices.set(listOf("foo-api", "foo-integration"))
        upAdditionalArgs.set(listOf("--no-deps"))
    }
}