duality72 / gradle-docker-plugin

Gradle plugin for managing Docker images and containers.

Gradle Docker plugin

Gradle plugin for managing Docker images and containers using via its remote API. The heavy lifting of communicating with the Docker remote API is handled by the Docker Java library. Currently, version 0.10.3 is used which assumes Docker’s client API v1.13.1.

Usage

To use the plugin, include in your build script:

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath 'com.bmuschko:gradle-docker-plugin:0.4'
    }
}

apply plugin: 'com.bmuschko.docker-remote-api'

Custom task types

Misc

The plugin provides the following general-purpose custom task types:

Type	Description
DockerInfo	Displays system-wide information.
DockerVersion	Show the docker version information.

Images

The plugin provides the following custom task types for managing images:

Type	Description
Dockerfile	Creates a Dockerfile based on the provided instructions.
DockerBuildImage	Builds an image from a Dockerfile.
DockerCommitImage	Creates a new image from a container’s changes.
DockerInspectImage	Returns low-level information on the image.
DockerListImages	Lists images in registry.
DockerPullImage	Pulls an image from the registry.
DockerPushImage	Pushes an image to a registry.
DockerRemoveImage	Removes an image from the filesystem.
DockerTagImage	Tags an image in registry.

Containers

The plugin provides the following custom task types for managing containers:

Type	Description
DockerCreateContainer	Creates a container.
DockerKillContainer	Kills the container for a given id.
DockerRemoveContainer	Removes the container for a given id from the filesystem.
DockerRestartContainer	Restarts the container for a given id.
DockerStartContainer	Starts the container for a given id.
DockerStopContainer	Stops the container for a given id.
DockerWaitContainer	Blocks until container for a given id stops, then returns the exit code.

Extension properties

The plugin defines the following extension properties in the docker closure:

Property name	Type	Default value	Description
serverUrl	String	null	The server URL to connect to via Docker’s remote API.

For pushing an image to the Docker Hub registry or to a self-hosted one, you will also need to provide credentials in the credentials closure:

Property name	Type	Default value	Description
username	String	null	The registry username.
password	String	null	The registry password.
email	String	null	The registry email address.

Example

The following example code demonstrates how to build a Docker image from a Dockerfile, starts up a container for this image and exercises functional tests agains the running container. At the end of this operation, the container is stopped.

import com.bmuschko.gradle.docker.tasks.container.*
import com.bmuschko.gradle.docker.tasks.image.*

docker {
    serverUrl = 'http://remote.docker.com:2375'

    credentials {
        username = 'bmuschko'
        password = 'pwd'
        email = '[e-mail]'
    }
}

task buildMyAppImage(type: DockerBuildImage) {
    inputDir = file('docker/myapp')
    tag = 'test/myapp'
}

task createMyAppContainer(type: DockerCreateContainer) {
    dependsOn buildMyAppImage
    targetImageId { buildMyAppImage.getImageId() }
}

task startMyAppContainer(type: DockerStartContainer) {
    dependsOn createMyAppContainer
    targetContainerId { createMyAppContainer.getContainerId() }
}

task stopMyAppContainer(type: DockerStopContainer) {
    targetContainerId { createMyAppContainer.getContainerId() }
}

task functionalTestMyApp(type: Test) {
    dependsOn startMyAppContainer
    finalizedBy stopMyAppContainer
}