Docker Plugin

The Docker Gradle plugin is a Gradle plugin that helps to centralize your project's configuration by allowing you to generate a Dockerfile via a Kotlin DSL.

Setting Up

First, add the Docker Gradle plugin to your build.gradle.kts.

            plugins {
                id("dev.kordex.gradle.docker") version "1.4.2"
            }
        

Then configure it as explained below.

            import dev.kordex.gradle.plugins.docker.file.*
            import dev.kordex.gradle.plugins.docker.file.commands.*

            docker {
                // Settings go here.

                file(rootProject.file("Dockerfile"))

                commands {
                    from("openjdk:21-jdk-slim")

                    // ...
                }
            }
        

Configuration

All settings must be provided within the docker { } builder.

Basic Settings

The following settings are set directly within the docker { } builder.

Property	Default	Description
Required Properties
`target`		A `File` object representing the Dockerfile to be generated.
Optional Properties
`generateOnBuild`	`true`	Whether to automatically generate the Dockerfile at build time, by adding the `createDockerfile` task as a finalizer for the `build` task.

Commands

To add commands, call their respective functions within the commands { } builder. Each command has its own function and configuration.

Non-Command Functions

There are several functions which don't directly map to Dockerfile commands:

comment(text)
emptyLine()

ADD Command

This section corresponds with the relevant Dockerfile reference section.

Functions

add(sources, target) { }

Usage

Within the builder, you may use the option function to add the following command options:

Checksum(checksum)
Chmod(perms)
Chown(user, group)
Exclude(path)
KeepGitDir
Link

ARG Command

This section corresponds with the relevant Dockerfile reference section.

Functions

arg(key, value)

CMD Command

This section corresponds with the relevant Dockerfile reference section.

Functions

cmdExec(instruction, ...)
cmdShell(instructions)

Usage

This command supports both the exec-style and shell-style command formats, supplied via the corresponding functions.

COPY Command

This section corresponds with the relevant Dockerfile reference section.

Functions

copy(source, target) { }
copy(sources, target) { }

Usage

Within the builder, you may use the option function to add the following command options:

Chmod(perms)
Chown(user, group)
Exclude(path)
From(source)
Link
Parents

ENTRYPOINT Command

This section corresponds with the relevant Dockerfile reference section.

Functions

entryPointExec(instruction, ...)
entryPointShell(instructions)

Usage

This command supports both the exec-style and shell-style command formats, supplied via the corresponding functions.

ENV Command

This section corresponds with the relevant Dockerfile reference section.

Functions

env(variables)
env { add(key, value) }

Usage

This command supports directly passing a map or using a builder, which provides an add(key, value) function you can use.

EXPOSE Command

This section corresponds with the relevant Dockerfile reference section.

Functions

expose(port, protocol?, comment?)

Usage

The protocol parameter takes an instance of the Protocol sealed class:

TCP
UDP

FROM Command

This section corresponds with the relevant Dockerfile reference section.

Functions

from(image, alias?, platform?)

HEALTHCHECK Command

This section corresponds with the relevant Dockerfile reference section.

Functions

healthcheck { }

Usage

Within the builder, you must call either check { } or none() to define the health-check command.

The check { } builder provides the cmdExec and cmdShell functions to define the health-check command, and you may use the option function to add the following command options:

Interval(duration)
Timeout(duration)
StartPeriod(duration)
StartInterval(duration)
Retries(number)

LABEL Command

This section corresponds with the relevant Dockerfile reference section.

Functions

label { }

Usage

Within the builder, you may use the label(key, value) function to define labels.

ONBUILD Command

This section corresponds with the relevant Dockerfile reference section.

Functions

onBuild { }

Usage

Within the builder, you may use the other command functions documented in this section to add on-build commands, with the following restrictions:

copy commands must not have the From option supplied.
You may not add from commands.
You may not add other onBuild commands.

RUN Command

This section corresponds with the relevant Dockerfile reference section.

Functions

runExec(command, ...) { }
runShell(command) { }

Usage

This command supports both the exec-style and shell-style command formats, supplied via the corresponding functions.

The following builders are available to configure the command:

bindMount { }
Required Settings:
- from
- target
Optional Settings:
- readWrite = false
- source = null
cacheMount { }
Required Settings:
- from
- target
Optional Settings:
- gid = 0
- id = null
- mode = "0755"
- readOnly = false
- sharing = Sharing.Shared (Locked, Private or Shared)
- source = null
- uid = 0
tmpfsMount { }
Required Settings:
- size
- target
secretMount { }
Optional Settings:
- gid = 0
- id = null
- mode = "0400"
- required = false
- target = null
- uid = 0
sshMount { }
Required Settings:
- target
Optional Settings:
- gid = 0
- id = null
- mode = "0600"
- required = false
- uid = 0

The following functions are available to configure the command options:

networkType(NetworkType) (Default, Host or None)
securityType(SecurityType) (Insecure or Sandbox)

SHELL Command

This section corresponds with the relevant Dockerfile reference section.

Functions

shell(command, ...)

STOPSIGNAL Command

This section corresponds with the relevant Dockerfile reference section.

Functions

stopSignal(signal)

USER Command

This section corresponds with the relevant Dockerfile reference section.

Functions

user(user, group?)

VOLUME Command

This section corresponds with the relevant Dockerfile reference section.

Functions

volume(volume, ...)

WORKDIR Command

This section corresponds with the relevant Dockerfile reference section.

Functions

workdir(dir)

Directives

If you want to add parser directives, call the directive function with the name and value of the directive.

                docker {
                    directive("escape", "\\")
                }
            

To learn more about directives, see the Dockerfile reference documentation.

Last modified: 03 September 2024