Gradle plugin series - dockerCompose

For the past 5 years, I have been mostly working on Gradle. And in these years, I have also noticed a lot of interesting Gradle plugins. So I thought why not create a series of blog posts and share what I’ve done with them?

Gradleizing things is something I’ve started to like. Thanks to all the Gradle projects and Gradle lovers who worked with me!

In this first blog post of the series, I would like to introduce the plugin — dockerCompose.

Introduction

The Docker Compose Gradle plugin simplifies the integration of Docker Compose into the Gradle build lifecycle. By leveraging this plugin, developers can define and manage Docker Compose services directly within their Gradle build scripts. The plugin automates the container orchestration process, making it an invaluable asset for projects relying on containerized architectures.

Using the plugin

To integrate the Docker Compose plugin into a Gradle project, developers typically add the plugin to their build.gradle file:

plugins {
    id 'com.avast.gradle.docker-compose' version 'x.y.z'
}

This snippet declares the Docker Compose plugin as a dependency, allowing developers to utilise its functionality within their Gradle build.

Start an AWS service in Localstack

To show how this plugin works, I’ll use it to start an AWS service in Localstack. We have the localstack added to a docker-compose file in our codebase as below -

version: "3.9"
services:
  localstack: 
    build:
      dockerfile: _docker/localstack/Dockerfile
      context: .
    ports:
      - "4566:4566" 
    container_name: localstack
    environment:
      SERVICES: s3, dynamodb, cloudformation
      AWS_DEFAULT_REGION: us-west-1

Now that we have a docker-compose.yml file and the Docker Compose plugin in our build.gradle file, we have to wire up the location of the docker-compose.yml file to the plugin. To do this, we have to specify the location in the dockerCompose settings as shown below in the build.gradle file

dockerCompose {
    useComposeFiles = ["${rootDir}/docker-compose.yml"]
}

In the above snippet, we have specified the location of the docker-compose file which is in the root directory of the project structure. The above configuration starts all the services in the docker-compose.ymlfile. We could also provide a nested configuration just in case you have multiple docker-compose files and you would like to start only a few from each. We can change our dockerCompose settings with a nested configuration as below -

dockerCompose {
    localstack {
        useComposeFiles = ["${rootDir}/docker-compose.yml"]
        startedServices = ['localstack']
    }
}

With this, the plugin creates localstackComposeUp, localstackComposeBuild, localstackComposePull, localstackComposeDown, localstackComposeDownForced and localstackComposePush tasks.

So now, all we have to do to run localstack through gradle is to use the Gradle command(s)-

./gradlew dockerComposeUp
./gradlew dockerComposeDown

Integrating with Other Gradle Tasks

Integrate Docker Compose tasks with your existing Gradle tasks. For example, you might want to start Docker Compose services before running integration tests and stop them afterward.

test.dependsOn dockerComposeUp
test.finalizedBy dockerComposeDown

This configuration ensures that Docker Compose services are started before running tests and stopped afterward as shown below -

> Task :localstackComposeUp
Container localstack  Creating
Container localstack  Created
Container localstack  Starting
Container localstack  Started
Will use localhost as host of localstack
More forwarded TCP ports for service 'localstack:4566 [[HostIp:0.0.0.0, HostPort:4566], [HostIp:::, HostPort:4566]]'. Will use the first one.
Waiting for localstack to become healthy (it's starting)
Waiting for localstack to become healthy (it's starting)
localstack health state reported as 'healthy' - continuing...
Probing TCP socket on localhost:4566 of 'localstack'
TCP socket on localhost:4566 of 'localstack' is ready
+------------+----------------+----------------+
| Name       | Container Port | Mapping        |
+------------+----------------+----------------+
| localstack | 4566           | localhost:4566 |
+------------+----------------+----------------+

> Task :test PASSED

> Task :localstackComposeDown
Container localstack  Stopping
Container localstack  Stopped
Going to remove localstack
Container localstack  Removing
Container localstack  Removed

We could even configure it better and there are lot more options you can try. But I would leave it for 🫵 to figure out! You could read more about the plugin from here.

Hope this helps you. See you again with another plugin 👋