DOCSEARCHbyAlgolia
Submit Docs

spotify/docker-maven-plugin

repository·master·Indexed 25 days ago

https://github.com/spotify/docker-maven-plugin

A Maven plugin for building and pushing Docker images. It supports generating Dockerfiles from POM configuration or using existing Dockerfiles. Note: This plugin is currently inactive; Spotify recommends using dockerfile-maven instead.

Tokens
2.5K
Snippets
7
Records
13
Agent score
33%

What's inside docker-maven-plugin

  2. Configure Docker connection via DOCKER_HOST

    master

    By default, the plugin attempts to connect to Docker on localhost:2375. To connect to a remote Docker daemon, set the DOCKER_HOST environment variable. The plugin also honors standard Docker environment variables for TLS and certificates.

    DOCKER_HOST=tcp://<host>:2375

  3. Configure Docker Authentication

    master

    The plugin automatically uses credentials from ~/.dockercfg or ~/.docker/config.json. It also supports Google Container Registry via Application Default Credentials (ADC) or the DOCKER_GOOGLE_CREDENTIALS environment variable.

    To explicitly configure credentials in Maven, add a <server> to your settings.xml and reference its <id> in the plugin's <serverId> configuration.

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

<!-- In pom.xml -->
<configuration>
  <serverId>docker-hub</serverId>
  <registryUrl>https://index.docker.io/v1/</registryUrl>
</configuration>

  4. Specify Docker build info directly in the POM

    master

    You can define the image configuration (base image, entry point, and resources) directly in your pom.xml without a separate Dockerfile. This is useful for simple images where you only need to copy artifacts like JAR files.

    <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>

  5. Push to Private Registries

    master

    To push to a private registry, the image tag must be prefixed with the registry's hostname and port (e.g., registry.example.com/my-image).

    Option 1: Direct Configuration Set the <imageName> to include the registry hostname:

    <configuration>
  <imageName>registry.example.com/my-image</imageName>
</configuration>

    Option 2: Tagging after build Use docker:tag with the -DpushImage flag to tag a short-named image with the full registry hostname and push it immediately.

  6. Bind Docker commands to Maven phases

    master

    To automate container building, tagging, and pushing during standard Maven lifecycles (like mvn deploy), bind the plugin goals to specific phases in your pom.xml. This is particularly useful for multi-module projects where sub-modules need to trigger image builds from the parent.

    <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>

  7. Use a Dockerfile with docker-maven-plugin

    master

    If you need to use commands not supported by the POM configuration (such as VOLUME) or prefer a standard Dockerfile, use the dockerDirectory element.

    Note: When dockerDirectory is specified, the baseImage, maintainer, cmd, and entryPoint elements in the POM are ignored. The contents of the specified directory will be copied into ${project.build.directory}/docker to serve as the build context.

    <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>

  8. Configure image tags and overwrite behavior

    master

    In your pom.xml, you can define multiple tags using the <imageTags> configuration element. By default, tags are not overwritten; set <forceTags>true</forceTags> to force Docker to overwrite tags on every build.

    <configuration>
  <!-- optionally overwrite tags every time image is built with docker:build -->
  <forceTags>true</forceTags>
  <imageTags>
     <imageTag>${project.version}</imageTag>
     <imageTag>latest</imageTag>
  </imageTags>
</configuration>

  9. Troubleshoot 'HTTP 500 Internal Server Error'

    master

    An InternalServerErrorException: HTTP 500 Internal Server Error indicates an unexpected error in the local Docker daemon.

    Common Causes:

    • Invalid Repository Names: Attempting to use uppercase characters in the repository name (e.g., using a ${project.version} that contains SNAPSHOT).
    • Solution: Use the <dockerImageTags> configuration to put the version in a tag instead of the repository name.

    Debugging: Check your Docker daemon logs (typically at /var/log/docker.log or /var/log/upstart/docker.log) for specific error details.

  10. Troubleshoot 'docker has type STRING rather than OBJECT' error

    master

    This error occurs if you declare a Maven property named docker in your pom.xml. Because the plugin uses internal properties like docker.build.defaultProfile, a user-defined docker property causes a type conflict.

    Solution: Rename your docker property to something else.

  12. Build and push Docker images via Maven CLI

    master
    You can build Docker images using the docker:build goal. To push the image to a registry, use the -DpushImage flag. To push only specific tags, use the -DpushImageTag flag. You can also specify tags directly on the command line using -DdockerImageTags.