Docker Maven Plugin

https://github.com/spotify/docker-maven-plugin
Admin
A Maven plugin for building and pushing Docker images, allowing configuration of image details...
Tokens:38,245
Snippets:296
Trust Score:8.7
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Instantiate BuildMojo with default profile

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Example of creating a BuildMojo instance with the default profile set to "production".

```java
BuildMojo mojo = new BuildMojo("production");
```

--------------------------------

### Usage example

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/dockerbuildinformation.md

Shows how to instantiate DockerBuildInformation, set the digest, and obtain JSON bytes. The comment indicates persistence via Utils.writeImageInfoFile.

```java
DockerBuildInformation info = new DockerBuildInformation("my-image:1.0", mojo.getLog());
info.setDigest("my-image@sha256:abc123");
byte[] json = info.toJsonBytes();
// persisted by Utils.writeImageInfoFile(info, tagInfoFile);
```

--------------------------------

### pushImage usage example

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/utils.md

Shows a call to `pushImage` with a sample image, tags, retry count, and timeout.

```java
Utils.pushImage(docker, "registry.example.com/app:1.0",
    Arrays.asList("latest"), log, buildInfo, 5, 10000, false);
```

--------------------------------

### Example JSON output

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/dockerbuildinformation.md

Shows the serialized JSON with all fields populated. Keys are sorted alphabetically and null fields are omitted.

```json
{"commit":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2","digest":"registry.example.com/app@sha256:5f1b...","image":"registry.example.com/app:1.0","repo":"git@github.com:example/app.git"}
```

--------------------------------

### Specify build info in the POM

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Configure the docker-maven-plugin in the POM to build an image named 'example' with base image 'java', an entry point that runs the jar, and copies the jar from the build directory into the image root.

```xml
<build>
  <plugins>
    ...
    <plugin>
      <groupId>com.spotify</groupId>
      <artifactId>docker-maven-plugin</artifactId>
      <version>VERSION GOES HERE</version>
      <configuration>
        <imageName>example</imageName>
        <baseImage>java</baseImage>
        <entryPoint>["java", "-jar", "/${project.build.finalName}.jar"]</entryPoint>
        <!-- copy the service's jar file from target into the root directory of the image --> 
        <resources>
           <resource>
             <targetPath>/</targetPath>
             <directory>${project.build.directory}</directory>
             <include>${project.build.finalName}.jar</include>
           </resource>
        </resources>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>
```

--------------------------------

### Command-line usage examples

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/removeimagemojo.md

Shows how to invoke the removeImage goal from the command line with -DimageName, either with a simple tag or a fully qualified image name.

```sh
mvn docker:removeImage -DimageName=foobar
mvn docker:removeImage -DimageName=registry.example.com/my-image:1.0
```

--------------------------------

### HOCON build profile example

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Example of a HOCON build profile named 'production' with fields like imageName, baseImage, entryPoint, cmd, env, resources, exposes, and runs. Used when the 'profile' parameter and 'defaultProfile' field are null, the default profile name is taken from docker.build.defaultProfile.

```hocon
docker.build.profiles: {
    production: {
        imageName: "${project.artifactId}"
        baseImage: busybox
        entryPoint: date
        cmd: "-u"
        env: { APP_NAME="${appName}" }
        resources: [{
            targetPath: /xml
            directory: src/test/resources
            includes: [pom-build-with-profile.xml]
        }]
        exposes: [8080, 8081]
        runs: ["ln -s /a /b"]
    }
}
```

--------------------------------

### CompositeImageName usage example

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/compositeimagename.md

Example of creating a CompositeImageName with a composite image name and additional tags, showing the resulting name and tag list.

```java
// internal usage pattern (same package)
CompositeImageName composite = CompositeImageName.create("app:1.0", Arrays.asList("latest"));
composite.getName();       // "app"
composite.getImageTags();  // ["1.0", "latest"]
```

--------------------------------

### XML server configuration with email

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

XML example showing how to declare a server in settings.xml with an email in the configuration section. This email is used by the registryAuth method to set the email field in the RegistryAuth object.

```xml
<servers>
  <server>
    <id>docker-hub</id>
    <username>foo</username>
    <password>secret-password</password>
    <configuration>
      <email>foo@foo.bar</email>
    </configuration>
  </server>
</servers>
```

--------------------------------

### Usage example for getCommitId

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/git.md

Example of using Git to get a commit ID tag and use it to name an image.

```java
Git git = new Git();
if (git.isRepository()) {
  String tag = git.getCommitId(); // e.g. "df8e8e6"
  // use `tag` to name the image: "registry.example.com/app:" + tag
}
```

--------------------------------

### Handling MojoExecutionException

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/git.md

Example of catching MojoExecutionException when Git is constructed outside a git working tree.

```java
try {
  Git git = new Git(); // constructed outside a git working tree
  String tag = git.getCommitId();
} catch (MojoExecutionException e) {
  // "Cannot tag with git commit ID because directory not a git repo"
}
```

--------------------------------

### DockerBuildInformation class declaration

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/dockerbuildinformation.md

Declares the DockerBuildInformation class in the com.spotify.docker package. This is the starting point for the class that captures build metadata.

```java
package com.spotify.docker;

// line 42
public class DockerBuildInformation {
```

--------------------------------

### Serialized toJsonBytes() output for DockerBuildInformation

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/types.md

Example serialized JSON output from toJsonBytes() for DockerBuildInformation. Shows alphabetical property ordering, non-null inclusion, and digest format as {repo}@sha256:...

```json
{"commit":"a1b2c3...","digest":"app@sha256:abc...","image":"app:1.0","repo":"git@github.com:example/app.git"}
```

--------------------------------

### Maven configuration for removing all tags

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/removeimagemojo.md

XML configuration example for the removeImage goal that removes a repository with all its local tags by setting removeAllTags to true and providing a list of imageTags.

```xml
<configuration>
  <imageName>registry.example.com/my-image</imageName>
  <imageTags>
    <imageTag>1.0</imageTag>
    <imageTag>2.0</imageTag>
  </imageTags>
  <removeAllTags>true</removeAllTags>
</configuration>
```

--------------------------------

### parseImageName usage examples

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/utils.md

Shows typical usage of `parseImageName` with a tagged image and an untagged image, including the resulting array contents.

```java
String[] parts = Utils.parseImageName("registry.example.com:5000/app:1.0");
// parts[0] = "registry.example.com:5000/app", parts[1] = "1.0"
String[] untagged = Utils.parseImageName("busybox");
// untagged[0] = "busybox", untagged[1] = null
```

--------------------------------

### Show plugin configuration options with plugin help goal

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Display a complete list of configuration options for the docker-maven-plugin. Use `-Ddetail=true` to see detailed descriptions.

```bash
mvn com.spotify:docker-maven-plugin:<version>:help -Ddetail=true
```

--------------------------------

### execute

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Lifecycle entry point that executes the mojo, skipping if skipDocker is set.

```APIDOC
## execute()

### Description
Lifecycle entry point that executes the mojo. If `skipDocker` is set, logs a message and returns. Otherwise, builds a DockerClient and delegates to the abstract goal implementation.

### Method
`public void execute() throws MojoExecutionException`

### Parameters
None.

### Returns
`void`

### Throws
- `MojoExecutionException` — if any exception occurs during execution, wrapped with message "Exception caught".

### Behavior
- If `skipDocker` is set, logs "Skipping docker goal" and returns.
- Otherwise, builds a DockerClient (auto-closed) and delegates to the abstract goal implementation.
```

--------------------------------

### buildDockerClient method - configure and build DockerClient

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Builds a DockerClient using getBuilder(), applying dockerHost and dockerCertificates if set, and a chained RegistryAuthSupplier. Throws MojoExecutionException on certificate problems.

```java
// lines 160–180
protected DockerClient buildDockerClient() throws MojoExecutionException {

  final DefaultDockerClient.Builder builder;
  try {
    builder = getBuilder();

    final String dockerHost = rawDockerHost();
    if (!isNullOrEmpty(dockerHost)) {
      builder.uri(dockerHost);
    }
    final Optional<DockerCertificatesStore> certs = dockerCertificates();
    if (certs.isPresent()) {
      builder.dockerCertificates(certs.get());
    }
  } catch (DockerCertificateException ex) {
    throw new MojoExecutionException("Cannot build DockerClient due to certificate problem", ex);
  }

  builder.registryAuthSupplier(authSupplier());

  return builder.build();
}
```

--------------------------------

### Configure imageName with registry.example.com for private registry

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

When pushing to a private registry, prefix the image name with the registry hostname and port so Docker pushes to the correct registry. Use this as the `<imageName>` value to tag the image with the full registry hostname.

```xml
<plugin>
  <groupId>com.spotify</groupId>
  <artifactId>docker-maven-plugin</artifactId>
  <configuration>
    <imageName>registry.example.com/my-image</imageName>
    ...
```

--------------------------------

### execute() lifecycle method

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Entry point for the Mojo. If skipDocker is set, logs 'Skipping docker goal' and returns. Otherwise builds a DockerClient (auto-closed) and delegates to the abstract goal implementation. Any exception is wrapped in MojoExecutionException("Exception caught", e).

```java
// lines 140–153
@Override
public void execute() throws MojoExecutionException {

  if (skipDocker) {
    getLog().info("Skipping docker goal");
    return;
  }

  try (DockerClient client = buildDockerClient()) {
    execute(client);
  } catch (Exception e) {
    throw new MojoExecutionException("Exception caught", e);
  }
}
```

--------------------------------

### Constructor DockerBuildInformation(String image, Log log)

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/dockerbuildinformation.md

Constructor that stores the image and calls updateGitInformation(log) to populate repo and commit from git. Any IOException is logged and swallowed, leaving git fields null.

```java
// lines 60–63
public DockerBuildInformation(final String image, final Log log) {
  this.image = image;
  updateGitInformation(log);
}
```

--------------------------------

### Build short name and tag to private registry with docker:tag -DpushImage

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Use this configuration to build a short-named image (`my-image`) and then tag it with the full registry hostname in the same plugin execution. The `tag` goal is bound to the `package` phase and re-tags the image to `registry.example.com/my-image`; after that, `docker:build -DpushImage` will push to the registry. Note that using `docker:push` alone will attempt to push the original short-named image unless you use the `pushImage` flag with `docker:tag`.

```xml
<plugin>
  <groupId>com.spotify</groupId>
  <artifactId>docker-maven-plugin</artifactId>
  <configuration>
    <imageName>my-image</imageName>
    ...
  </configuration>
  <executions>
    <execution>
      <id>build-image</id>
      <phase>package</phase>
      <goals>
        <goal>build</goal>
      </goals>
    </execution>
    <execution>
      <id>tag-image</id>
      <phase>package</phase>
      <goals>
        <goal>tag</goal>
      </goals>
      <configuration>
        <image>my-image</image>
        <newName>registry.example.com/my-image</newName>
      </configuration>
    </execution>
  </executions>
</plugin>
```

--------------------------------

### CompositeImageName error case

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/compositeimagename.md

Example of the error case where neither the image name nor the imageTags provide a tag, causing MojoExecutionException with the message "No tag included in imageName and no imageTags set!".

```java
// error case: neither name nor tags carry a tag
try {
  CompositeImageName.create("app", null);
} catch (MojoExecutionException e) {
  // "No tag included in imageName and no imageTags set!"
}
```

--------------------------------

### Maven plugin configuration for docker-maven-plugin

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Basic plugin configuration with shared parameters like dockerHost, dockerCertPath, serverId, registryUrl, and retry settings. Command line equivalents are -DdockerHost=..., -DdockerCertPath=..., -DskipDocker=true, -DretryPushCount=3.

```xml
<plugin>
  <groupId>com.spotify</groupId>
  <artifactId>docker-maven-plugin</artifactId>
  <version>1.2.3</version>
  <configuration>
    <!-- shared parameters inherited by every goal -->
    <dockerHost>tcp://my-docker-host:2376</dockerHost>
    <dockerCertPath>/home/me/.docker/certs</dockerCertPath>
    <serverId>docker-hub</serverId>
    <registryUrl>https://index.docker.io/v1/</registryUrl>
    <retryPushCount>3</retryPushCount>
    <retryPushTimeout>5000</retryPushTimeout>
  </configuration>
</plugin>
```

--------------------------------

### execute() lifecycle entry

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Serializes builds with a static ReentrantLock, then runs the base-class flow (skip check → client build → execute(DockerClient)). Throws MojoExecutionException as wrapped by the base class.

```java
// lines 325–332
@Override
public void execute() throws MojoExecutionException {
  try {
    LOCK.lock();
    super.execute();
  } finally {
    LOCK.unlock();
  }
}
```

--------------------------------

### Build and push Docker image with docker:build

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Use these commands to build and optionally push a Docker image via the docker-maven-plugin. `-DpushImage` pushes the built image to the configured registry; `-DpushImageTag` requires at least one `imageTag` to be present. When only specific tags are pushed with `pushImageTag`, you can still use multiple tags in the config.

```bash
mvn clean package docker:build
```

```bash
mvn clean package docker:build -DpushImage
```

```bash
mvn clean package docker:build -DpushImageTag
```

```xml
<build>
  <plugins>
    ...
    <plugin>
      <configuration>
        ...
        <imageTags>
           <imageTag>${project.version}</imageTag>
           <imageTag>latest</imageTag>
        </imageTags>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>
```

--------------------------------

### Build with user Dockerfile, extra tags, push and tar archive

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Maven configuration for a build using a user-provided Dockerfile, with extra image tags, force tags, push to registry, retry settings, build args, healthcheck, and saving to a tar archive.

```xml
<configuration>
  <imageName>registry.example.com/my-image</imageName>
  <dockerDirectory>docker</dockerDirectory>
  <imageTags>
    <imageTag>${project.version}</imageTag>
    <imageTag>latest</imageTag>
  </imageTags>
  <forceTags>true</forceTags>
  <pushImage>true</pushImage>
  <retryPushCount>5</retryPushCount>
  <retryPushTimeout>10000</retryPushTimeout>
  <saveImageToTarArchive>${project.build.directory}/image.tar</saveImageToTarArchive>
  <buildArgs>
    <VERSION>0.1</VERSION>
  </buildArgs>
  <healthcheck>
    <options>--interval=30s</options>
    <cmd>curl -f http://localhost/ || exit 1</cmd>
  </healthcheck>
</configuration>
```

--------------------------------

### Use a Dockerfile with dockerDirectory

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Configure the docker-maven-plugin to use a Dockerfile located in the 'docker' directory. When dockerDirectory is set, baseImage, maintainer, cmd, and entryPoint are ignored. The directory contents are copied to ${project.build.directory}/docker, and the resources element adds additional files like the jar.

```xml
<build>
  <plugins>
    ...
    <plugin>
      <groupId>com.spotify</groupId>
      <artifactId>docker-maven-plugin</artifactId>
      <version>VERSION GOES HERE</version>
      <configuration>
        <imageName>example</imageName>
        <dockerDirectory>docker</dockerDirectory>
        <resources>
           <resource>
             <targetPath>/</targetPath>
             <directory>${project.build.directory}</directory>
             <include>${project.build.finalName}.jar</include>
           </resource>
        </resources>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>
```

--------------------------------

### execute() (lifecycle entry)

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Serializes builds with a static ReentrantLock and runs the base-class flow.

```APIDOC
## execute() (lifecycle entry)

### Description
Serializes builds with a static `ReentrantLock` and then runs the base-class flow (skip check → client build → `execute(DockerClient)`).

### Method
`public void execute() throws MojoExecutionException`

### Throws
- **MojoExecutionException** - As wrapped by the base class (`"Exception caught"`).

```

--------------------------------

### execute(DockerClient) protected override

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Protected override that performs the main build flow: skip check, git commit ID handling, profile loading, parameter validation, image name parsing, staging, build, tag, push, save, and writing image info. Throws MojoExecutionException, DockerException, IOException, InterruptedException, GitAPIException.

```java
// lines 335–435
@Override
protected void execute(final DockerClient docker)
    throws MojoExecutionException, GitAPIException, IOException, DockerException,
           InterruptedException {
```

--------------------------------

### Git constructor

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/git.md

Constructor that builds a FileRepositoryBuilder, reads GIT_* environment variables, scans up the file system tree, and sets repo to null if no .git directory is found. Throws IOException if repository discovery fails.

```java
// lines 42–50
public Git() throws IOException {
  final FileRepositoryBuilder builder = new FileRepositoryBuilder();
  // scan environment GIT_* variables
  builder.readEnvironment();
  // scan up the file system tree
  builder.findGitDir();
  // if getGitDir is null, then we are not in a git repository
  repo = builder.getGitDir() == null ? null : builder.build();
}
```

--------------------------------

### dockerCertificates method - build certificate store from dockerCertPath

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Builds an Optional<DockerCertificatesStore> from dockerCertPath, or returns Optional.absent() when unset. Throws DockerCertificateException if the certificate path cannot be loaded.

```java
// lines 189–197
protected Optional<DockerCertificatesStore> dockerCertificates()
    throws DockerCertificateException {
  if (!isNullOrEmpty(dockerCertPath)) {
    return DockerCertificates.builder()
      .dockerCertPath(Paths.get(dockerCertPath)).build();
  } else {
    return Optional.absent();
  }
}
```

--------------------------------

### execute(DockerClient) (protected override)

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Performs the main build flow: skip check, git commit handling, profile loading, validation, staging, build, tag, push, save, and image info writing.

```APIDOC
## execute(DockerClient) (protected override)

### Description
Performs the main build flow: skip check, git commit handling, profile loading, validation, staging, build, tag, push, save, and image info writing.

### Method
`protected void execute(final DockerClient docker) throws MojoExecutionException, GitAPIException, IOException, DockerException, InterruptedException`

### Parameters
- **docker** (DockerClient) - Required - Auto-closed docker client from the base class.

### Returns
- **void**

### Throws
- **MojoExecutionException** - When `weShouldSkipDockerBuild()` is false but git info unavailable while `useGitCommitId` or `${gitShortCommitId}` in `imageName`; `useGitCommitId` with no tag and no commit; profile load/resource/expression failures.
- **DockerException**, **IOException**, **InterruptedException**, **GitAPIException** - Underlying docker build/tag/push/save operations.

### Execution Flow
1. `weShouldSkipDockerBuild()` - skip when `skipDockerBuild`, when project packaging is `pom`, or when `dockerDirectory` is set but contains no `Dockerfile`.
2. `exposesSet = Sets.newTreeSet(exposes)` - dedupe+sort exposed ports; `runList` copy of `runs`.
3. Git: `new Git().getCommitId()`; if a repository, sets Maven property `gitShortCommitId` (first 7 chars) and expands `${gitShortCommitId}` in `imageName`/`baseImage` via a `PluginParameterExpressionEvaluator`. If not a repo and `useGitCommitId` or `imageName` contains `${gitShortCommitId}` → `MojoExecutionException`.
4. `loadProfile()` - merges HOCON profile.
5. `validateParameters()` - `"Must specify baseImage if dockerDirectory is null"` when neither is set.
6. `parseImageName(imageName)` → `repo`/`tag`; if `useGitCommitId` and no explicit tag, `imageName = repo + ":" + commitId`; sets Maven property `imageName`.
7. Staging: `getDestination()` returns `Paths.get(buildDirectory, "docker")`. If `dockerDirectory == null` → `copyResources(destination)` + `createDockerFile(destination, copiedPaths)`; else adds `dockerDirectory` as a resource and copies it.
8. `buildImage(docker, destination, buildParams())` - `docker.build(Paths.get(buildDir), imageName, new AnsiProgressHandler(), buildParams)`.
9. `tagImage(docker, forceTags)` - tags `imageName` with each non-empty entry of `imageTags`.
10. If packaging is `docker` → `createImageArtifact` writes a `{artifactId}-{version}-docker.jar` containing `META-INF/docker/{groupId}/{artifactId}/image-info.json` and replaces the project artifact file.
11. If `pushImageTag` → `Utils.pushImageTag(...)`; if `pushImage` → `Utils.pushImage(...)` with retry params.
12. If `saveImageToTarArchive` → `Utils.saveImage(...)`.
13. `writeImageInfoFile(buildInfo, tagInfoFile)`.

```

--------------------------------

### Bind docker:build, tag, and push goals to Maven phases

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Bind the build, tag, and push goals to Maven phases so `mvn deploy` builds, tags, and pushes the image. This is useful for multi-module projects where a sub-module builds an image and must be triggered from the parent. The `tag` goal renames the image to `registry.example.com/my-image:${project.version}` and the `push` goal uses that image name.

```xml
<plugin>
  <groupId>com.spotify</groupId>
  <artifactId>docker-maven-plugin</artifactId>
  <version>VERSION GOES HERE</version>
  <executions>
    <execution>
      <id>build-image</id>
      <phase>package</phase>
      <goals>
        <goal>build</goal>
      </goals>
    </execution>
    <execution>
      <id>tag-image</id>
      <phase>package</phase>
      <goals>
        <goal>tag</goal>
      </goals>
      <configuration>
        <image>my-image:${project.version}</image>
        <newName>registry.example.com/my-image:${project.version}</newName>
      </configuration>
    </execution>
    <execution>
      <id>push-image</id>
      <phase>deploy</phase>
      <goals>
        <goal>push</goal>
      </goals>
      <configuration>
        <imageName>registry.example.com/my-image:${project.version}</imageName>
      </configuration>
    </execution>        
  </executions>
</plugin>
```

--------------------------------

### BuildMojo(String defaultProfile) constructor

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Sets the defaultProfile field. When not null, loadProfile() uses it if no profile parameter and no docker.build.defaultProfile HOCON value is present.

```java
// lines 278–280
public BuildMojo(final String defaultProfile) {
  this.defaultProfile = defaultProfile;
}
```

--------------------------------

### Basic generated-Dockerfile build configuration

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Maven configuration for a basic build using a generated Dockerfile. Sets image name, base image, entry point, and resources to include the built JAR.

```xml
<configuration>
  <imageName>example</imageName>
  <baseImage>java</baseImage>
  <entryPoint>["java", "-jar", "/${project.build.finalName}.jar"]</entryPoint>
  <resources>
    <resource>
      <targetPath>/</targetPath>
      <directory>${project.build.directory}</directory>
      <include>${project.build.finalName}.jar</include>
    </resource>
  </resources>
</configuration>
```

```sh
mvn clean package docker:build
```

--------------------------------

### settings.xml server entry for docker-hub

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/configuration.md

Configure Maven settings.xml with a server entry for the docker-hub serverId. The username, password (plain or {encrypted}), and optional email are mapped to RegistryAuth fields. Missing server entries only log a warning.

```xml
<servers>
  <server>
    <id>docker-hub</id>
    <username>foo</username>
    <password>secret-password</password>        <!-- or {encrypted} form -->
    <configuration>
      <email>foo@foo.bar</email>
    </configuration>
  </server>
</servers>
```

--------------------------------

### writeImageInfoFile

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/utils.md

Writes Docker build information to a JSON file, creating parent directories as needed.

```APIDOC
## writeImageInfoFile

### Description
Writes Docker build information to a JSON file, creating parent directories as needed.

### Method
writeImageInfoFile

### Signature
```java
@SuppressFBWarnings("NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE")
public static void writeImageInfoFile(final DockerBuildInformation buildInfo,
                                        final String tagInfoFile) throws IOException
```

### Parameters
- **buildInfo** (DockerBuildInformation) - Required - Data to serialize (see [types.md](../types.md) for the JSON schema).
- **tagInfoFile** (String) - Required - Output path; parent directories are created.

### Returns
void

### Throws
- **IOException** - if the file cannot be written. Unchecked `JsonProcessingException` is propagated wrapped by `Throwables.propagate` from `toJsonBytes()`.
```

--------------------------------

### isSkipDockerBuild()

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Returns the skipDockerBuild flag.

```APIDOC
## isSkipDockerBuild()

### Description
Returns the skipDockerBuild flag.

### Method
`public boolean isSkipDockerBuild()`

### Returns
- **boolean** - The `skipDockerBuild` flag.

```

--------------------------------

### getBuilder method - DefaultDockerClient.Builder from environment

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Returns a DefaultDockerClient.Builder initialized from environment variables (DOCKER_HOST, docker TLS env vars) with read timeout disabled (0). Subclasses may override.

```java
// lines 155–158
protected DefaultDockerClient.Builder getBuilder() throws DockerCertificateException {
  return DefaultDockerClient.fromEnv()
    .readTimeoutMillis(0);
}
```

--------------------------------

### writeImageInfoFile method signature

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/utils.md

Writes Docker build information to a JSON file, creating parent directories if needed. Throws IOException on write failure.

```java
@SuppressFBWarnings("NP_NULL_ON_SOME_PATH_FROM_RETURN_VALUE")
public static void writeImageInfoFile(final DockerBuildInformation buildInfo,
                                        final String tagInfoFile) throws IOException {
  final Path imageInfoPath = Paths.get(tagInfoFile);
  if (imageInfoPath.getParent() != null) {
    Files.createDirectories(imageInfoPath.getParent());
  }
  Files.write(imageInfoPath, buildInfo.toJsonBytes());
}
```

--------------------------------

### rawDockerHost method - return raw dockerHost parameter

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Returns the raw dockerHost parameter, or null if unset.

```java
// line 185
protected String rawDockerHost() {
  return dockerHost;
}
```

--------------------------------

### Reference serverId and registryUrl in pom.xml for Docker Hub authentication

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

In your project's `pom.xml`, reference the server ID defined in `settings.xml` and set the registry URL to point to Docker Hub. The plugin will use these explicitly configured credentials for authentication; note that credentials from the Docker CLI config file take priority over explicitly configured ones.

```xml
<plugin>
  <plugin>
    <groupId>com.spotify</groupId>
    <artifactId>docker-maven-plugin</artifactId>
    <version>VERSION GOES HERE</version>
    <configuration>
      [...]
      <serverId>docker-hub</serverId>
      <registryUrl>https://index.docker.io/v1/</registryUrl>
    </configuration>
  </plugin>
</plugins>
```

--------------------------------

### Release locally with Maven release plugin

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Builds and releases the plugin locally to Sonatype. Requires maintainer credentials. Commits to the master branch trigger CI release instead.

```sh
mvn release:clean
mvn release:prepare
mvn release:perform

```

--------------------------------

### CompositeImageName value container with imageTags and name

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/types.md

Package-private value container holding a list of image tags and the image name without the composite tag. Constructed via static create(String, List<String>) which can throw MojoExecutionException, and provides getName() and getImageTags() accessors. Used by Utils.pushImageTag to push exactly the listed tags.

```java
class CompositeImageName {
  private final List<String> imageTags;
  private final String name;
  // ...
}
```

--------------------------------

### Run tests with mvn clean test

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Runs the test suite for the plugin. Requires Docker daemon to be running and accessible via `docker ps`.

```sh
mvn clean test

```

--------------------------------

### BuildMojo() no-arg constructor

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Delegates to BuildMojo(null). Used by Maven when instantiating the mojo via Plexus.

```java
// line 274
public BuildMojo() {
  this(null);
}
```

--------------------------------

### registryAuth method implementation

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Java implementation of the registryAuth method. It retrieves the server from settings.xml using serverId, decrypts the password via SecDispatcher if available, and builds a RegistryAuth object. Returns null if settings or serverId are unset or the server is missing, logging a warning. Throws MojoExecutionException if password decryption fails.

```java
// lines 239–277
protected RegistryAuth registryAuth() throws MojoExecutionException {
  if (settings != null && serverId != null) {
    final Server server = settings.getServer(serverId);
    if (server != null) {
      final RegistryAuth.Builder registryAuthBuilder = RegistryAuth.builder();
      final String username = server.getUsername();
      String password = server.getPassword();
      if (secDispatcher != null) {
        try {
          password = secDispatcher.decrypt(password);
        } catch (SecDispatcherException ex) {
          throw new MojoExecutionException("Cannot decrypt password from settings", ex);
        }
      }
      final String email = getEmail(server);
      // ... set username / email / password / serverAddress if non-empty ...
      return registryAuthBuilder.build();
    } else {
      getLog().warn("No entry found in settings.xml for serverId=" + serverId
                    + ", cannot configure authentication for that registry");
    }
  }
  return null;
}
```

--------------------------------

### Check Docker daemon with docker ps

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Verifies that the Docker daemon is running and accessible; run this before `mvn clean test`.

```sh
docker ps

```

--------------------------------

### PushMojo class and execute method

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/pushmojo.md

Java source for the PushMojo class and its execute method. The class declares the @Mojo(name = "push") annotation and extends AbstractDockerMojo. The execute method delegates to Utils.pushImage with null DockerBuildInformation, and passes shared retry and skip parameters.

```java
package com.spotify.docker;

// lines 38–40
/**
 * Pushes a docker image repository to the specified docker registry.
 */
@Mojo(name = "push")
public class PushMojo extends AbstractDockerMojo {
```

```java
// lines 51–58
@Override
protected void execute(DockerClient docker)
    throws MojoExecutionException, DockerException, IOException, InterruptedException {

  pushImage(docker, imageName, imageTags, getLog(), null, getRetryPushCount(),
      getRetryPushTimeout(), isSkipDockerPush());
}
```

--------------------------------

### docker:push

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/pushmojo.md

Pushes a Docker image repository to the specified Docker registry. This goal is configured via Maven plugin configuration or command-line properties.

```APIDOC
## [POST] docker:push

### Description
Pushes a Docker image repository to the specified Docker registry. This goal is part of the Spotify docker-maven-plugin and is invoked via Maven.

### Method
Maven Goal (not an HTTP method)

### Endpoint
`docker:push`

### Parameters
#### Configuration Parameters
- **imageName** (String) - Required - Name of the image to push, e.g. `registry.example.com/my-image:1.0`.
- **imageTags** (List<String>) - Optional - Additional tags to push: each is pushed as `{imageName without tag}:{tag}`.

#### Inherited Parameters (from AbstractDockerMojo)
- **serverId** - Optional - Server ID for authentication.
- **registryUrl** - Optional - Registry URL.
- **retryPushCount** - Optional - Number of retries on push failure.
- **retryPushTimeout** - Optional - Timeout between retries in milliseconds.
- **skipDockerPush** - Optional - If set, skips the push operation.

### Request Example
```xml
<plugin>
  <groupId>com.spotify</groupId>
  <artifactId>docker-maven-plugin</artifactId>
  <version>1.2.3</version>
  <executions>
    <execution>
      <id>push-image</id>
      <phase>deploy</phase>
      <goals>
        <goal>push</goal>
      </goals>
      <configuration>
        <imageName>registry.example.com/my-image:${project.version}</imageName>
        <imageTags>
          <imageTag>latest</imageTag>
        </imageTags>
        <serverId>docker-hub</serverId>
        <registryUrl>https://index.docker.io/v1/</registryUrl>
      </configuration>
    </execution>
  </executions>
</plugin>
```

### Response
#### Success Response
- **void** - The goal completes successfully after pushing the image and tags.

#### Response Example
No response body; Maven logs progress.

### Error Handling
- **MojoExecutionException** - Thrown if `imageName` is missing when parsed.
- **DockerException** - Thrown if push fails after all retries exhausted.
- **IOException**, **InterruptedException** - Declared but not raised directly by PushMojo.

### Usage Examples
Command line:
```sh
mvn docker:push -DimageName=registry.example.com/my-image:1.0
mvn docker:push -DimageName=my-image -DdockerImageTags=latest,1.0
```

Skip push when bound to a phase:
```sh
mvn deploy -DskipDockerPush
```

Push retry behavior: on `DockerException`, retries up to `retryPushCount` times, sleeping `retryPushTimeout` ms between attempts, logging `Failed to push %s, retrying in %d seconds (%d/%d).` (`PUSH_FAIL_WARN_TEMPLATE`), then re-throws.
```

--------------------------------

### Define DockerBuildInformation data class

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/types.md

Public data class for build metadata, with fields for image, repo, commit, and digest. Fields map to JSON keys via @JsonProperty; image is required constructor arg, others nullable until set. Used by Utils.pushImage, Utils.writeImageInfoFile, and build/tag mojos.

```java
public class DockerBuildInformation {
  @JsonProperty("image")
  private final String image;

  @JsonProperty("repo")
  private String repo;

  @JsonProperty("commit")
  private String commit;

  @JsonProperty("digest")
  private String digest;
  // ...
}
```

--------------------------------

### Maven execution configuration for tagging an image

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/tagmojo.md

Configure the `tag` goal in a Maven execution to tag an image with a new name and optionally push it. The `image` and `newName` parameters use `${project.version}`. Set `pushImage` to `true` to push after tagging.

```xml
<execution>
  <id>tag-image</id>
  <phase>package</phase>
  <goals>
    <goal>tag</goal>
  </goals>
  <configuration>
    <image>my-image:${project.version}</image>
    <newName>registry.example.com/my-image:${project.version}</newName>
    <pushImage>true</pushImage>
  </configuration>
</execution>
```

--------------------------------

### setRepo method (package-private)

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/git.md

Test-only seam to set the repository; not part of the public API.

```java
// line 58–61 (package-private)
void setRepo(final Repository repo) {
  this.repo = repo;
}
```

--------------------------------

### isSkipDockerBuild() getter

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Returns the skipDockerBuild flag as a boolean.

```java
// lines 321–323
public boolean isSkipDockerBuild() {
  return skipDockerBuild;
}
```

--------------------------------

### Skip tagging during package phase

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/tagmojo.md

Use `-DskipDockerTag` to skip the tagging goal when bound to the `package` phase.

```sh
mvn package -DskipDockerTag
```

--------------------------------

### execute(DockerClient) method for tagging

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/tagmojo.md

Protected method that performs the docker tagging operation. It skips if skipDockerTag is set, parses the newName into repo and tag, optionally resolves the tag from git commit ID, tags the image, pushes if configured, and writes image info file.

```java
// lines 94–122
@Override
protected void execute(DockerClient docker)
    throws MojoExecutionException, DockerException,
           IOException, InterruptedException, GitAPIException {

  if (skipDockerTag) {
    getLog().info("Skipping docker tag");
    return;
  }

  final String[] repoTag = parseImageName(newName);
  final String repo = repoTag[0];
  String tag = repoTag[1];

  if (useGitCommitId) {
    if (tag != null) {
      getLog().warn("Ignoring useGitCommitId flag because tag is explicitly set in image name ");
    } else {
      tag = new Git().getCommitId();
    }
  }

  final String normalizedName = isNullOrEmpty(tag) ? repo : String.format("%s:%s", repo, tag);
  getLog().info(String.format("Creating tag %s from %s", normalizedName, image));
  docker.tag(image, normalizedName, forceTags);

  final DockerBuildInformation buildInfo = new DockerBuildInformation(normalizedName, getLog());

  if (pushImage) {
    pushImage(docker, newName, null, getLog(), buildInfo, getRetryPushCount(),
        getRetryPushTimeout(), isSkipDockerPush());
  }

  writeImageInfoFile(buildInfo, tagInfoFile);
}
```

--------------------------------

### Error: system properties: docker has type STRING rather than OBJECT

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Error output shown when a Maven property named `docker` is declared, conflicting with plugin properties like `docker.build.defaultProfile`. Fix by renaming the `docker` property in pom.xml.

```text
[ERROR] Failed to execute goal com.spotify:docker-maven-plugin:0.0.21:build (default) on project <....>: 
Exception caught: system properties: docker has type STRING rather than OBJECT

```

--------------------------------

### execute(DockerClient) method implementation

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/removeimagemojo.md

The core logic of RemoveImageMojo: parses the image name, handles imageTags and removeAllTags, and removes each unique tag with force removal while preserving untagged parents. 404 errors are caught and logged as warnings.

```java
// lines 66–109
@Override
protected void execute(final DockerClient docker)
    throws MojoExecutionException, DockerException, InterruptedException {
  final String[] imageNameParts = parseImageName(imageName);
  if (imageTags == null) {
    imageTags = new ArrayList<>(1);
    imageTags.add(imageNameParts[1]);
  } else if (removeAllTags) {
    getLog().info("Removal of all tags requested, searching for tags");
    // removal of all tags requested, loop over all images to find tags
    for (final Image currImage : docker.listImages()) {
      getLog().debug("Found image: " + currImage.toString());
      String[] parsedRepoTag;
      if (currImage.repoTags() != null) {
        for (final String repoTag : currImage.repoTags()) {
          parsedRepoTag = parseImageName(repoTag);
          // if repo name matches imageName then save the tag for deletion
          if (Objects.equal(parsedRepoTag[0], imageNameParts[0])) {
            imageTags.add(parsedRepoTag[1]);
            getLog().info("Adding tag for removal: " + parsedRepoTag[1]);
          }
        }
      }
    }
  }
  imageTags.add(imageNameParts[1]);

  final Set<String> uniqueImageTags = new HashSet<>(imageTags);
  for (final String imageTag : uniqueImageTags) {
    final String currImageName =
        imageNameParts[0] + ((isNullOrEmpty(imageTag)) ? "" : (":" + imageTag));
    getLog().info("Removing -f " + currImageName);

    try {
      // force the image to be removed but don't remove untagged parents
      for (final RemovedImage removedImage : docker.removeImage(currImageName, true, false)) {
        getLog().info("Removed: " + removedImage.imageId());
      }
    } catch (ImageNotFoundException | NotFoundException e) {
      // ignoring 404 errors only
      getLog().warn("Image " + imageName + " doesn't exist and cannot be deleted - ignoring");
    }
  }
}
```

--------------------------------

### separatorsToUnix (static)

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/buildmojo.md

Normalizes a path by replacing Windows separators with Unix separators.

```APIDOC
## separatorsToUnix (static)

### Description
Normalizes a path by replacing Windows separators (`\`) with Unix separators (`/`). Returns the input unchanged if it contains no backslash or is null.

### Method
`public static String separatorsToUnix(final String path)`

### Parameters
- **path** (String) - Optional - Path to normalize; `null` is returned as-is.

### Returns
- **String** - The input with Windows separators replaced by Unix separators; unchanged if it contains no backslash.

### Example
```java
String normalized = BuildMojo.separatorsToUnix("target\\docker\\app.jar"); // "target/docker/app.jar"
```

```

--------------------------------

### Abstract execute method signature

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/abstract-dockermojo.md

Abstract method that each concrete mojo must implement. Receives an auto-closed DockerClient created by buildDockerClient().

```java
// line 183
protected abstract void execute(final DockerClient dockerClient) throws Exception;
```

--------------------------------

### isRepository method

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/git.md

Returns true when a git repository was discovered.

```java
// line 52
public boolean isRepository() {
  return repo != null;
}
```

--------------------------------

### Getters for all fields

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/dockerbuildinformation.md

Simple getter methods for image, repo, commit, and digest. Each returns the field value, which may be null for repo, commit, and digest.

```java
// lines 94–107
public String getImage() { return image; }
public String getRepo() { return repo; }
public String getCommit() { return commit; }
public String getDigest() { return digest; }
```

--------------------------------

### Push specific Docker image tags with dockerImageTags

Source: https://github.com/spotify/docker-maven-plugin/blob/master/README.md

Specify exact tags to push via the `-DdockerImageTags` property on the command line, combined with `-DpushImageTag`. This overrides the imageTags defined in the configuration.

```bash
mvn ... docker:build -DpushImageTag -DdockerImageTags=latest,another-tag
```

--------------------------------

### PUSH_FAIL_WARN_TEMPLATE constant

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/utils.md

Defines the message format used when a push fails and will be retried. Placeholders correspond to `imageName`, `retryPushTimeout / 1000`, `attempt + 1`, and `retryPushCount`.

```java
// line 46
public static final String PUSH_FAIL_WARN_TEMPLATE = "Failed to push %s,"
        + " retrying in %d seconds (%d/%d).";
```

--------------------------------

### Utils class declaration

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/utils.md

Declares the public static utility class `Utils` in the `com.spotify.docker` package.

```java
package com.spotify.docker;

// line 44
public class Utils {
```

--------------------------------

### Command-line tag with Git commit ID

Source: https://github.com/spotify/docker-maven-plugin/blob/master/_autodocs/api-reference/tagmojo.md

Run `mvn docker:tag` with `-DuseGitCommitId` to tag the image with the Git commit ID. The resulting tag is `registry.example.com/my-image:<commit-id>`, with additional suffixes for tags and dirty working tree.

```sh
mvn docker:tag -Dimage=my-image -DnewName=registry.example.com/my-image -DuseGitCommitId
```
Tokens:
Raw