dev.jeka.core.api.tooling.docker

Class JkDockerBuild

java.lang.Object

dev.jeka.core.api.tooling.docker.JkDockerBuild

Direct Known Subclasses:

JkDockerJvmBuild, JkDockerNativeBuild

public class JkDockerBuild
extends java.lang.Object

Docker Builder assistant for defining and creating Docker images.

This class facilitates the programmatic construction of a Docker build context directory and the execution of the docker build command using that context.

Key Features

• Configuring the base image
• Adding a non-root user to the image
• Customizing the build process with additional steps in the generated Dockerfile

Docker Image Build Process

1. A static template of the Dockerfile is generated. This template may include tokens such as ${baseImage}, allowing flexibility when the base image or user creation steps need to be determined dynamically.
2. Tokens in the static template are resolved dynamically to produce the final Dockerfile.
3. The build context directory is created. The generated Dockerfile and any specified files are copied into this directory.
4. The docker build command is executed using the generated build context directory. This operation requires Docker CLI (e.g., Docker Desktop) installed on the host machine.

Default Dockerfile Template

The default Dockerfile template is as follows:

 FROM ${baseImage}
 ${addNonRootUser}
 

Users can customize this template by adding steps to the dockerFileTemplate field. Custom tokens (e.g., ${myToken}) can also be defined, and their resolution logic specified using the #addTokenResolver(String, Supplier<String>) method.

Importing Files

Files can be imported into the build context using:

• #addFsOperation()
• dockerFileTemplate#addCopy(fileSystemPath, containerPath)

Building and Pushing Images

Once the Docker build is configured, the image can be generated using the buildImage(String imageName) method. The resulting image will be automatically pushed to the Docker registry.

Intermediate Steps

Intermediate steps such as dockerFileTemplate.render(), renderDockerFile(), or generateContextDir() can be used to aid in the configuration of the Docker build process.

Extensibility

This class can be extended to provide a specific default template and additional convenience methods.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JkDockerBuild.AddUserStatement
class	JkDockerBuild.DockerfileTemplate
static class	JkDockerBuild.NonRootMode Defines the modes for creating a nonroot user in a Docker image.

Field Summary

Fields

Modifier and Type	Field and Description
JkDockerBuild.DockerfileTemplate	dockerfileTemplate

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	JkDockerBuild()

Method Summary

Modifier and Type	Method and Description
JkDockerBuild	addFsOperation(java.util.function.Consumer<java.nio.file.Path> fsOperation) Adds an operation to be executed immediately after the build context directory is created.
JkDockerBuild	addTokenResolver(java.lang.String token, java.util.function.Supplier<java.lang.Object> valueSupplier) Specifies how to resolve the given token.
void	buildImage(java.nio.file.Path buildContextDir, java.lang.String imageName) Builds the Docker image with the specified image name.
java.nio.file.Path	buildImageInTemp(java.lang.String imageName) Similar to buildImage(Path, String), but without requiring a context directory to be specified.
protected java.lang.String	computeImportedFileRelativePath(java.nio.file.Path fileToCopy, java.lang.String targetDirRelPath)
void	generateContextDir(java.nio.file.Path buildContextDir) Generates the build context directory without building the Docker image.
java.lang.String	getBaseImage()
java.util.List<java.lang.Integer>	getExposedPorts() Returns an unmodifiable list of exposed ports in the Docker image.
protected java.lang.String	getPortMappingArgs() Returns a string representation of the command line arguments for port mapping in the Docker image.
boolean	hasNonRootUserCreation() Checks whether the image includes a step to create a non-root user.
static JkDockerBuild	of() Creates a instannce.
java.lang.String	renderDockerfile() Render the final Dockerfile.
java.lang.String	renderInfo() Renders a human-readable string representation of the information used to build the image.
JkDockerBuild	setAddUserStatement(JkDockerBuild.AddUserStatement addUserTemplate)
JkDockerBuild	setAddUserStatement(java.lang.String addUserTemplate) Sets the Docker statement for adding a 'nonroot' user. The placeholders "${UID}" and "${GID}" will be replaced with the user ID and group ID configured for this instance, respectively.
JkDockerBuild	setBaseImage(java.lang.String baseImage) Sets the base image name to use a s the base image in the docker file.
JkDockerBuild	setExposedPorts(java.lang.Integer... ports) Adds a port to be exposed by the container.
JkDockerBuild	setGroupId(int groupId) Sets the group ID for the 'nonroot' user.
JkDockerBuild	setNonRootUserCreationMode(JkDockerBuild.NonRootMode nonRootUserCreationMode)
JkDockerBuild	setUserId(int userId) Sets the user ID for the 'nonroot' user.
protected static java.lang.String	toDoubleQuotedArgs(java.util.List<java.lang.String> args)
protected static java.lang.String	toDoubleQuotedArgs(java.lang.String... args) Transform a list as [a,b,c] in a string as "a", "b", "c"

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dockerfileTemplate

public final JkDockerBuild.DockerfileTemplate dockerfileTemplate

Constructor Detail

JkDockerBuild

protected JkDockerBuild()

Method Detail

of

public static JkDockerBuild of()

Creates a instannce.

setBaseImage

public final JkDockerBuild setBaseImage(java.lang.String baseImage)

Sets the base image name to use a s the base image in the docker file.

getBaseImage

public java.lang.String getBaseImage()

setNonRootUserCreationMode

public final JkDockerBuild setNonRootUserCreationMode(JkDockerBuild.NonRootMode nonRootUserCreationMode)

hasNonRootUserCreation

public final boolean hasNonRootUserCreation()

Checks whether the image includes a step to create a non-root user.

Returns:

true if a non-root user creation step is present, false otherwise.

setAddUserStatement

public final JkDockerBuild setAddUserStatement(java.lang.String addUserTemplate)

Sets the Docker statement for adding a 'nonroot' user.
The placeholders "${UID}" and "${GID}" will be replaced with the user ID and group ID configured for this instance, respectively.

setAddUserStatement

public final JkDockerBuild setAddUserStatement(JkDockerBuild.AddUserStatement addUserTemplate)

See Also:

setAddUserStatement(String)

setUserId

public final JkDockerBuild setUserId(int userId)

Sets the user ID for the 'nonroot' user.

Parameters:

userId - the user ID to assign.

setGroupId

public final JkDockerBuild setGroupId(int groupId)

Sets the group ID for the 'nonroot' user.

Parameters:

groupId - the group ID to assign.

setExposedPorts

public final JkDockerBuild setExposedPorts(java.lang.Integer... ports)

Adds a port to be exposed by the container.

getExposedPorts

public final java.util.List<java.lang.Integer> getExposedPorts()

Returns an unmodifiable list of exposed ports in the Docker image.

getPortMappingArgs

protected final java.lang.String getPortMappingArgs()

Returns a string representation of the command line arguments for port mapping in the Docker image.

addTokenResolver

public JkDockerBuild addTokenResolver(java.lang.String token,
                                      java.util.function.Supplier<java.lang.Object> valueSupplier)

Specifies how to resolve the given token. The value supplier can return any type of object, which will be converted to a String using the Object.toString() method.

addFsOperation

public JkDockerBuild addFsOperation(java.util.function.Consumer<java.nio.file.Path> fsOperation)

Adds an operation to be executed immediately after the build context directory is created.

This is typically used to import files or directories into the context directory.

Parameters:

fsOperation - a Consumer that accepts the path to the build context directory.

renderDockerfile

public java.lang.String renderDockerfile()

Render the final Dockerfile.

buildImage

public void buildImage(java.nio.file.Path buildContextDir,
                       java.lang.String imageName)

Builds the Docker image with the specified image name.

Parameters:

buildContextDir - the directory where the Dockerfile will be generated and from which COPY paths will be resolved.

imageName - the name of the image to build. It may include a tag name.

buildImageInTemp

public java.nio.file.Path buildImageInTemp(java.lang.String imageName)

Similar to buildImage(Path, String), but without requiring a context directory to be specified.

A temporary context directory will be created in a random location.

Returns:

the path of the created context directory.

generateContextDir

public void generateContextDir(java.nio.file.Path buildContextDir)

Generates the build context directory without building the Docker image. This can be useful for debugging purposes.

This method is automatically called when buildImage(Path, String) is invoked.

renderInfo

public java.lang.String renderInfo()

Renders a human-readable string representation of the information used to build the image.

computeImportedFileRelativePath

protected java.lang.String computeImportedFileRelativePath(java.nio.file.Path fileToCopy,
                                                           java.lang.String targetDirRelPath)

toDoubleQuotedArgs

protected static java.lang.String toDoubleQuotedArgs(java.lang.String... args)

Transform a list as [a,b,c] in a string as "a", "b", "c"

toDoubleQuotedArgs

protected static java.lang.String toDoubleQuotedArgs(java.util.List<java.lang.String> args)

See Also:

toDoubleQuotedArgs(String...)