gradle-docker-plugin

The Gradle Docker plugin allows you to manage Docker images and containers via the Docker remote API. It leverages the docker-java library to handle the communication logic between the Docker client and the daemon.

Key Benefits:

• Seamless integration with Gradle's DSL.
• Simplifies complex Docker workflows.
• Provides sensible conventions to minimize build script setup.

Limitations:

• Not all Docker operations are exposed; some task types may not provide every possible option available in the underlying API.
• No Docker Compose support: This plugin does not support building multi-container applications via Docker Compose. For that, use the Avast Docker Compose plugin.
• No Swarm/Stack support: Managing Docker Swarm or Stacks is not supported.

The Gradle Docker plugin provides a way to manage Docker images and containers directly from your Gradle builds. It uses the Docker remote API to perform operations, with the underlying communication handled by the docker-java library.

Because it relies on docker-java, the plugin's capabilities and supported Docker server versions are tied to the features provided by that library. For detailed information on specific Docker client API support, refer to the docker-java documentation.

The com.bmuschko.docker-spring-boot-application plugin is designed for projects already using the Spring Boot Gradle plugin. It provides preconfigured tasks to automate the creation and pushing of Docker images specifically for Spring Boot applications.

Key Requirements & Behavior:

• Spring Boot Version: The plugin only supports projects using a 2.x version of the Spring Boot plugin.
• Plugin Reactivity: It automatically reacts to the presence of either the java or war plugin to configure itself.
• Configuration: It provides an exposed extension to tweak the default preconfigured Docker tasks.

The com.bmuschko.docker-remote-api plugin enables interaction with Docker via its remote API.

By default, if no specific configuration is provided in your build script, the plugin attempts to resolve and use Docker registry authentication credentials from previous login operations, typically found in $HOME/.docker/config.json.

The plugin distribution provides three distinct plugins depending on your requirements. Choose the one that matches your application type or interaction method:

1. com.bmuschko.docker-remote-api: Use this if you need custom tasks to interact directly with the Docker Remote API.
2. com.bmuschko.docker-java-application: Use this for standard Java applications. It automatically applies the com.bmuschko.docker-remote-api plugin and provides tasks to create and push Docker images for Java applications.
3. com.bmuschko.docker-spring-boot-application: Use this for Spring Boot applications. It automatically applies the com.bmuschko.docker-remote-api plugin and provides tasks to create and push Docker images specifically for Spring Boot applications.

The plugin provides a springBootApplication extension nested under the docker namespace. This extension is designed to automate the creation of Docker images for Spring Boot applications.

By default, the plugin automatically discovers the main class by scanning the classpath for a class annotated with org.springframework.boot.autoconfigure.SpringBootApplication that contains a public static void main(String[]) method. If your project contains multiple main classes, you must explicitly configure the mainClassName property.

The plugin implements Reactive Streams as optional closures for all tasks. This allows users to hook into the lifecycle of a task's execution.

Currently, only three reactive methods are supported:

1. onError: Triggered when an exception occurs. Handling it here prevents the exception from propagating and failing the build.
2. onNext: Triggered for every item in an iterative response (e.g., log lines or image lists).
3. onComplete: Triggered only upon successful completion of the task.

You can apply the plugin using the traditional buildscript block. This is one of the standard ways to include the plugin in your Gradle build.

Groovy DSL

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.bmuschko:gradle-docker-plugin:10.0.0'
    }
}

apply plugin: 'com.bmuschko.docker'

Kotlin DSL

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("com.bmuschko:gradle-docker-plugin:10.0.0")
    }
}

apply(plugin = "com.bmuschko.docker")

include::{samplesCodeDir}/remote-api-plugin/apply-plugin-buildscript/groovy/build.gradle[]

include::{samplesCodeDir}/remote-api-plugin/apply-plugin-buildscript/kotlin/build.gradle.kts[]

If you are applying the plugin from a script plugin (e.g., a .gradle file included via apply from:), you must use the fully-qualified class name due to a known Gradle core bug. Note that the plugin DSL cannot be used to apply a binary plugin from within a script plugin.

Recommendation for Kotlin DSL users: It is recommended to move your implementation into the buildSrc project instead of using script plugins.

Example script plugin (gradle/docker.gradle)

// Content of the script plugin

Example build file (build.gradle)

apply from: 'gradle/docker.gradle'

include::{samplesCodeDir}/remote-api-plugin/apply-plugin-from-script-plugin/groovy/gradle/docker.gradle[]

include::{samplesCodeDir}/remote-api-plugin/apply-plugin-from-script-plugin/groovy/build.gradle[]

To release a new version of the plugin, you must first update RELEASE_NOTES.md with the planned version and commit all changes in your local working copy. Then, execute the release command using the ./gradlew release task.

You must specify the release stage and the version scope using Gradle properties. The scope determines which part of the semantic version <major>.<minor>.<patch> is incremented.

./gradlew release -Prelease.stage=final -Prelease.scope=[SCOPE]