gradle-dcompose-plugin

When working with Gradle projects, there has always been a "technology break" when using Docker. First you would need to run a build like gradle assemble and afterwards docker-compose up in order to test your code locally.

This plugin aims at fully integrating the Docker container management into the Gradle build itself thus eleminating the need for docker-compose. It uses Gradle's UP-TO-DATE checks in order to determine whether a container should be recreated.

Prerequisites

This plugin requires:

• Gradle >= 3.3 (older versions possibly working, but not tested)
• Docker (host) >= 1.12.0 (older versions possibly working, but not tested)
• Please note: Docker for Mac (native) currently doesn't support redirecting standard streams to/from a container.

However, you don't need the Docker commandline tools nor the docker-compose command to be installed, as this plugin talks directly to the Docker host effectively replacing them.

Documentation

For the full documentation head over to the wiki!

Example

An example project says more than a thousand words: https://github.com/chrisgahlert/gradle-dcompose-sample

Quickstart

Make sure that you have Docker installed. Also make sure that the environment variable DOCKER_HOST is correctly populated if using either a remote Docker daemon or something like Docker toolbox.

Tip: If you are using Docker for Win/Mac and have trouble authenticating against a private registry: Try disabling the option to store password in the OS' keychain (via Settings -> General)!

Next, add the following to your build.gradle file:

buildscript {
    repositories {
        // The root-Project's buildscript must have a Repo (or Mirror) defined for Maven Central
        mavenCentral()
    }
}

plugins {
  // check for latest version in the release tab as this doesn't get updated regularly
  id "com.chrisgahlert.gradle-dcompose-plugin" version "0.17.0" 
}

dcompose {
  web {
    image = 'nginx:latest'
    portBindings = ['8080:80']
  }
}

Now launch the build with gradle startWebContainer and head over to http://localhost:8080

Advanced example

src/main/docker/Dockerfile

FROM 'nginx:latest'
COPY index.html /www/

build.gradle

dcompose {
  networks {
    frontend
    backend
  }
  
  dbData {
    image = 'mongo:latest'
    volumes = ['/var/lib/mongodb']
    preserveVolumes = true
    deploy = false
  }
  db {
    image = 'mongo:latest'
    volumesFrom = [dbData]
    networks = [backend]
    aliases = ['mongo_db']
  }
  cache {
    image = 'redis:latest'
    networks = [backend]
  }
  web {
    buildFiles = project.copySpec {
      from 'src/main/www/' // Contains index.html
      from 'src/main/docker/'
    }
    env = ['MONGO_HOST=mongo_db', 'REDIS_HOST=cache']
    repository = 'someuser/mywebimage:latest'
    networks = [frontend, backend]
  }
  
  testDb {
    image = 'mongo:latest'
    portBindings = ['27017']
    deploy = false
  }
}

test {
  dependsOn dcompose.testDb
  doFirst {
    // The host port is only availble after launching the container, therefore it needs to be added in the doFirst 
    systemProperty 'mongo.url', "mongodb://${dcompose.dockerHost}:${dcompose.testDb.findHostPort(27017)}/mydb" 
  }
  doLast { 
    // If we don't remove the property in the doLast, Gradle's UP-TO-DATE checks will be broken
    systemProperties.remove 'mongo.url' 
  }
}

Running

Launch the build by running gradle startWebContainer. This should automatically pull/create/start all required containers. Whenever something changes, you just need to re-run this build and everything, that needs to be recreated will be.

Mentions

• Blog entry Using a containerized database for testing Spring Boot applications by Daniel Sanchez
• Blog entry Don't use In-Memory Databases (like H2) for Tests by Philipp Hauer
• Talk TESTUMGEBUNGEN VERSCHIFFEN - DOCKER FÜR INTEGRATIONSTESTS by Stefan Hildebrandt