/gradle-docker-plugin

Gradle plugin for managing Docker images and containers.

Primary LanguageGroovyApache License 2.0Apache-2.0

Gradle Docker plugin

Docker Logo

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 2.1.1. Please refer to the library’s documentation for more information on the supported Docker’s client API and Docker server version.

Build Image

Usage

To use the plugin, include in your build script:

buildscript {
    repositories {
        jcenter()
    }

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

Provided plugins

The JAR file comes with two plugins:

Plugin Id Automatically applies Type Description

com.bmuschko.docker-remote-api

-

DockerRemoteApiPlugin

Provides custom tasks for interacting with Docker via its remote API.

com.bmuschko.docker-java-application

com.bmuschko.docker-remote-api

DockerJavaApplicationPlugin

Creates and pushes a Docker image for a Java application.

Remote API plugin

The plugin com.bmuschko.docker-remote-api allows for interacting with Docker via its remote API. You can model any workflow imaginable by creating enhanced task of the custom task provided by the plugin. To use the plugin, include the following code snippet in your build script:

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

The plugin automatically resolves the Docker Java library with the pre-configured version under the covers. The only configuration you will have to provide in your build script is the repository hosting the library and its transitive dependencies. One repository that hosts them all is Maven Central.

repositories {
    mavenCentral()
}

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

DockerCopyFileFromContainer

Copies a path from the container as a tar file on to the host.

DockerCreateContainer

Creates a container.

DockerInspectContainer

Returns low-level information on the 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

url

String

http://localhost:2375

The server URL to connect to via Docker’s remote API.

certPath

File

null

The path to certificates for communicating with Docker over SSL.

Image pull or push operations against the public Docker Hub registry or a private registry may require authentication. You can provide those credentials in the registryCredentials closure:

Property name Type Default value Description

url

String

https://index.docker.io/v1

The registry URL.

username

String

null

The registry username.

password

String

null

The registry password.

email

String

null

The registry email address.

Extension examples

Working with a TLS-enabled Docker instance

Starting with Docker version 1.3, TLS is enabled by default. Please consult the Docker documentation "Running Docker with https" to set up your certificate. The following example demonstrates how to configure the plugin to use those certificates. Additionally, this code snippet shows how to set the user credentials.

docker {
    url = 'https://192.168.59.103:2376'
    certPath = new File(System.properties['user.home'], '.boot2docker/certs/boot2docker-vm')

    registryCredentials {
        url = 'https://index.docker.io/v1'
        username = 'bmuschko'
        password = 'pwd'
        email = 'benjamin.muschko@gmail.com'
    }
}
Working with a Docker instance without TLS

The following example assumes that you disabled TLS on your Docker instance. You can do so by setting DOCKER_TLS=no in the file /var/lib/boot2docker/profile. Additionally, this code snippet shows how to set the user credentials.

docker {
    url = 'http://192.168.59.103:2375'
}

Usage examples

The following usage examples demonstrate code for common use cases. More scenarios can be found in the functional tests.

Creating a Dockerfile and building an image

A Dockerfile can be created by the Dockerfile custom tasks. The Dockerfile instructions need to be declare in the correct order.

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

import com.bmuschko.gradle.docker.tasks.image.Dockerfile
import com.bmuschko.gradle.docker.tasks.image.DockerBuildImage

task createDockerfile(type: Dockerfile) {
    destFile = project.file('build/mydockerfile/Dockerfile')
    from 'ubuntu:12.04'
    maintainer 'Benjamin Muschko "benjamin.muschko@gmail.com"'
}

task buildImage(type: DockerBuildImage) {
    dependsOn createDockerfile
    inputDir = createDockerfile.destFile.parentFile
    tag = 'bmuschko/myimage'
}

Executing functional tests against a running container

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.

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

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

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

task createMyAppContainer(type: DockerCreateContainer) {
    dependsOn buildMyAppImage
    targetImageId { buildMyAppImage.getImageId() }
    portBindings = ['8080:8080']
}

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

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

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

Java application plugin

The plugin com.bmuschko.docker-java-application is a highly opinonated plugin for projects applying the application plugin. Under the covers the plugin preconfigures tasks for creating and pushing Docker images for your Java application. The default configuration is tweakable via an exposed extension. To use the plugin, include the following code snippet in your build script:

apply plugin: 'com.bmuschko.docker-java-application'

Extension properties

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

Property name Type Default value Description

baseImage

String

java

The Docker base image used for Java application.

maintainer

String

Value of user.home system property

The name and email address of the image maintainer.

port

Integer

8080

The Docker image entry point port used for the Java application.

tag

String

<project.group>/<applicationName>:<project.version>

The tag used for the Docker image.

Usage example

docker {
    javaApplication {
        baseImage = 'dockerfile/java:openjdk-7-jre'
        maintainer = 'Benjamin Muschko "benjamin.muschko@gmail.com"'
        port = 9090
        tag = 'jettyapp:1.115'
    }
}

Default tasks

The plugin provides a set of tasks for your project and preconfigures them with sensible defaults.

Task name Depends On Type Description

dockerCopyDistResources

distTar

Copy

Copies the resource files (like the Java application’s TAR file) to a temporary directory for image creation.

dockerDistTar

dockerCopyDistResources

Dockerfile

Creates the Docker image for the Java application.

dockerBuildImage

dockerDistTar

DockerBuildImage

Builds the Docker image for the Java application.

dockerPushImage

dockerBuildImage

DockerPushImage

Pushes created Docker image to the repository.

Usage examples

The following usage examples demonstrate code for common use cases. More scenarios can be found in the functional tests.

apply plugin: 'java'
apply plugin: 'application'
apply plugin: 'com.bmuschko.docker-java-application'

version = '1.0'
sourceCompatibility = 1.7

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.eclipse.jetty.aggregate:jetty-all:9.2.5.v20141112'
}

mainClassName = 'com.bmuschko.gradle.docker.application.JettyMain'

docker {
    javaApplication {
        maintainer = 'Jon Doe "jon.doe@gmail.com"'
    }
}

FAQ

Executing the plugin’s test suite with custom configuration

Integration and functional tests that are executed against a Docker instance assume a specific setup. This setup uses the Docker server URL http://localhost:2375 with TLS being disabled. The default setup can be configured with the help of system properties shown in the table below:

Description System property Default Value

Docker server URL

dockerServerUrl

http://localhost:2375

Docker cert path

dockerCertPath

null

Docker private registry URL

dockerPrivateRegistryUrl

http://localhost:5000

The following usage example demonstrates running the tests against a Docker instance using HTTPS:

./gradlew build -DdockerServerUrl=https://192.168.59.103:2376 -DdockerCertPath=/Users/ben/.boot2docker/certs/boot2docker-vm