fabric8io/docker-maven-plugin

One purpose of this plugin is to create Docker images holding the actual application. This is done with the docker:build goal. It is easy to include build artefacts and their dependencies into an image.

Several ways for configuring the builds are supported:

Images that are built with this plugin can be pushed to public or private Docker registries with docker:push.

With this plugin it is possible to run completely isolated integration tests so you don’t need to take care of shared resources. Ports can be mapped dynamically and made available as Maven properties to your integration test code.

Multiple containers can be managed at once, which can be linked together or share data via volumes. Containers are created and started with the docker:start goal and stopped and destroyed with the docker:stop goal. For integration tests both goals are typically bound to the the pre-integration-test and post-integration-test phase, respectively. It is recommended to use the maven-failsafe-plugin for integration testing in order to stop the docker container even when the tests fail.

For proper isolation, container exposed ports can be dynamically and flexibly mapped to local host ports. It is easy to specify a Maven property which will be filled in with a dynamically assigned port after a container has been started. This can then be used as parameter for integration tests to connect to the application.

The plugin configuration contains a global part and a list of image-specific configuration within a <images> list, where each image is defined within a <image> tag. See below for an example.

The global part contains configuration applicable to all images like the Docker URL or the path to the SSL certificates for communication with the Docker Host.

Then, each specific image configuration has three parts:

The <build>, <run> and <copy> parts are optional and can be omitted.

In the following examples, two images are specified. One is the official PostgreSQL 9 image from Docker Hub, which internally is referenced with an alias "database". It only has a <run> section which declares that the startup should wait until the given text pattern is matched in the log output. Next is a "service" image, which has a <build> section. It creates an image which has artifacts and dependencies in the /maven directory (and which are specified with an assembly descriptor). Additionally, it specifies the startup command for the container, which in this example fires up a microservice from a jar file copied over via the assembly descriptor. It also exposes port 8080. In the <run> section this port is mapped to a dynamically chosen port and then assigned to the Maven property ${tomcat.port}. This property could be used, for example, by an integration test to access this microservice. An important part is the <links> section which indicates that the image with the alias of "database" is linked into the "service" container, which can access the internal ports in the usual Docker way (via environment variables prefixed with DB_).

Images can be specified in any order and the plugin will take care of the proper startup order (and will bail out if it detects circular dependencies).

Some other highlights, in random order:

When specifying the image name in the configuration with the <name> field you can use several placeholders which are replaced during runtime by this plugin. In addition you can use regular Maven properties which are resolved by Maven itself.

Replacements can also be used in <tag> fields within the the tags of any build configuration.

Similar to image name placeholders, for starting and stopping containers and alternate set of placeholders can be configured in order to the name the containers to create.

These placeholders can be used in the top-level configuration value containerNamePattern which is used globally for every container that is created. This global pattern can be overwritten individually by each image’s run configuration. If neither is given, then by default the pattern %n-%i is used.

When specifying the container name pattern the following placeholders can be used:

You can combine the placeholders in any combination and will be resolved during docker:start, docker:stop and docker:watch.

The following example is using a container name pattern of %n-%i which is also the default. Given an image fabric8io/dmp-sample-jolokia:latest, then during mvn docker:start a container with the name dmp-sample-jolokia-1 is first tried. If there is already a container with this name, then dmp-sample-jolokia-2 is the second attempt. This goes on until a "free" name is found.

Similar, when stopping containers with mvn docker:stop then only the container with the highest index is stopped. However, if you don’t use an index via %i then all containers started with docker:start are stopped. Use mvn docker:stop -Ddocker.allContainers to also stop every container named via a %i pattern.

Goals that need to refer to images or containers where the name of the image or container is not fixed may support name patterns for matching. Patterns can use an Ant-like syntax or Java regular expressions.

This goal will build all images which have a <build> configuration section, or, if the global configuration variable filter (property: docker.filter) is set, only the images contained in this variable (comma separated) will be built.

There are two different modes how images can be built:

With an inline plugin configuration all information required to build the image is contained in the plugin configuration. By default its the standard XML based configuration for the plugin but can be switched to a property based configuration syntax as described in the section External configuration. The XML configuration syntax is recommended because of its more structured and typed nature.

When using this mode, the Dockerfile is created on the fly with all instructions extracted from the configuration given.

Alternatively an external Dockerfile template or Docker archive can be used. This mode is switched on by using one of these three configuration options within

All paths can be either absolute or relative paths (except when both dockerFileDir and dockerFile are provided in which case dockerFile must not be absolute). A relative path is looked up in ${project.basedir}/src/main/docker by default. You can make it easily an absolute path by using ${project.basedir} in your configuration.

Any additional files located in the dockerFileDir directory will also be added to the build context as well. You can also use an assembly if specified in an assembly configuration. However, you need to add the files on your own in the Dockerfile with an ADD or COPY command. The files of the assembly are stored in a build context relative directory maven/ but can be changed by changing the assembly name with the option <name> in the assembly configuration.

E.g. the files can be added with

so that the assembly files will end up in /my/target/directory within the container.

If this directory contains a .maven-dockerignore (or alternatively, a .maven-dockerexclude file), then it is used for excluding files for the build. Each line in this file is treated as a FileSet exclude pattern as used by the maven-assembly-plugin. It is similar to .dockerignore when using Docker but has a slightly different syntax (hence the different name). Example .maven-dockerexclude or .maven-dockerignore is an example which excludes all compiled Java classes.

If this directory contains a .maven-dockerinclude file, then it is used for including only those files for the build. Each line in this file is also treated as a FileSet exclude pattern as used by the maven-assembly-plugin. Example .maven-dockerinclude shows how to include only jar file that have build to the Docker build context.

Except for the assembly configuration all other configuration options are ignored for now.

When only a single image should be built with a Dockerfile no XML configuration is needed at all. All what need to be done is to place a Dockerfile into the top-level module directory, alongside to pom.xml. You can still configure global aspects in the plugin configuration, but as soon as you add an <image> in the XML configuration, you need to configure also the build explicitly.

The image name is by default set from the Maven coordinates (%g/%a:%l, see Image Name for an explanation of the params which are essentially the Maven GAV) This name can be set with the property docker.name.

If you want to add some <run> configuration to this image for starting it with docker:run then you can add an image configuration but without a <build> section in which case the Dockerfile will be picked up, too. This works only for a single image, though.

fabric8-maven-plugin filters given Dockerfile with Maven properties, much like the maven-resource-plugin does. Filtering is enabled by default and can be switched off with a build config <filter>false</filter>. Properties which we want to replace are specified with the ${..} syntax. Replacement includes Maven project properties such as ${project.artifactId}, properties set in the build, command-line properties, and system properties. Unresolved properties remain untouched.

This partial replacement means that you can easily mix it with Docker build arguments and environment variable reference, but you need to be careful. If you want to be more explicit about the property delimiter to clearly separate Docker properties and Maven properties you can redefine the delimiter. In general, the filter option can be specified the same way as delimiters in the resource plugin. In particular, if this configuration contains a * then the parts left, and right of the asterisks are used as delimiters.

For example, the default <filter>${*}</filter> parse Maven properties in the format that we know. If you specify a single character for <filter> then this delimiter is taken for both, the start and the end. E.g a <filter>@</filter> triggers on parameters in the format @…​@, much like in the maven-invoker-plugin. Use something like this if you want to clearly separate from Docker builds args. This form of property replacement works for Dockerfile only. For replacing other data in other files targeted for the Docker image, please use the maven-resource-plugin or an assembly configuration with filtering to make them available in the docker build context.

The following example uses a Dockerfile in the directory src/main/docker/demo and replaces all properties in the format @property@ within the Dockerfile.

This plugin supports so call dmp-plugins which are used during the build phase. dmp-plugins are enabled by just declaring a dependency in the plugin declaration:

These plugins contain a descriptor META-INF/maven/io.fabric8/dmp-plugin with class names, line-by-line:

During a build with docker:build, those classes are loaded and certain fixed method are called.

The following methods are supported:

If a configured plugin does not provide method of this name and signature, then it will be simply ignored. Also, no interface needs to be implemented to keep the coupling low.

The following official dmp-plugins are known and supported:

Check out samples/run-java for a fully working example.

This goal creates and starts docker containers. This goal evaluates the configuration’s <run> section of all given (and enabled images).

Also you can specify docker.follow as system property so that the docker:start will never return but block until CTRL-C is pressed. That is similar to the option -i for docker run. This will automatically switch on showLogs so that you can see what is happening within the container. Also, after stopping with CTRL-C, the container is stopped (but not removed so that you can make postmortem analysis). docker:run is an alias for docker:start with docker.follow enabled.

By default container specific properties are exposed as Maven properties. These properties have the format docker.container.<alias>.<prop> where <alias> is the name of the container (see below) and <prop> is one of the following container properties:

Instead of the <alias> a fixed property key can be configured in the image’s <run> configuration with the option exposedPropertyKey.

For example the Maven property docker.container.tomcat.ip would hold the Docker internal IP for a container with an alias "tomcat". You can set the global configuration exposeContainerInfo to an empty string to not expose container information that way or to a string for an other prefix than docker.container.

Stops and removes a docker container. This goal stops every container started with <docker:start> either during the same build (e.g. when bound to lifecycle phases when doing integration tests) or for containers created by a previous call to <docker:start>

If called within the same build run, only the containers that were explicitly started during the run will be stopped. Existing containers started using docker:start for the project will not be affected.

If called as a separate invocation, the plugin will stop and remove any container it finds whose image is defined in the project’s configuration. Any existing containers found running whose image name matches but were not started by the plugin will not be affected.

In case the naming strategy for an image is alias (i.e. the container name is set to the given alias), then only the container with this alias is stopped. Other containers originating from the same image are not touched.

It should be noted that any containers created prior to version 0.13.7 of the plugin may not be stopped correctly by the plugin because the label needed to tie the container to the project may not exist. Should this happen, you will need to use the Docker CLI to clean up the containers and/or use the docker.allContainers option listed below.

For tuning what should happen when stopping there are four global parameters which are typically used as system properties: allContainers, keepContainer, keepRunning and removeVolumes.

This goal uploads images to the registry which have a <build> configuration section. The images to push can be restricted with the global option filter (see Global Configuration for details). The registry to push is by default docker.io but can be specified as part of the images’s name name the Docker way. E.g. docker.test.org:5000/data:1.5 will push the image data with tag 1.5 to the registry docker.test.org at port 5000. Security information (i.e. user and password) can be specified in multiple ways as described in section Authentication.

By default a progress meter is printed out on the console, which is omitted when using Maven in batch mode (option -B). A very simplified progress meter is provided when using no color output (i.e. with -Ddocker.useColor=false).

When developing and testing applications you will often have to rebuild Docker images and restart containers. Typing docker:build and docker:start all the time is cumbersome. With docker:watch you can enable automatic rebuilding of images and restarting of containers in case of updates.

docker:watch is the top-level goal which performs these tasks. There are two watch modes, which can be specified in multiple ways:

This mode works only when there is a <build> section in an image configuration. Otherwise no automatically build will be triggered for an image with only a <run> section. Note that you need the package phase to be executed before otherwise any artifact created by this build can not be included into the assembly. As described in the section about docker:start this is a Maven limitation. * run : Automatically restart container when their associated images changes. This is useful if you pull a new version of an image externally or especially in combination with the build mode to restart containers when their image has been automatically rebuilt. This mode works reliably only when used together with docker:start.

The mode can also be both or none to select both or none of these variants, respectively. The default is both.

docker:watch will run forever until it is interrupted with CTRL-C after which it will stop all containers. Depending on the configuration parameters keepContainer and removeVolumes the stopped containers with their volumes will be removed, too.

When an image is removed while watching it, error messages will be printed out periodically. So don’t do that ;-)

Dynamically assigned ports stay stable in that they won’t change after a container has been stopped and a new container is created and started. The new container will try to allocate the same ports as the previous container.

If containers are linked together network or volume wise, and you update a container which other containers dependent on, the dependant containers are not restarted for now. E.g. when you have a "service" container accessing a "db" container and the "db" container is updated, then you "service" container will fail until it is restarted, too.

This maven goal can be configured with the following top-level parameters:

Image specific watch configuration goes into an extra image-level <watch> section (i.e. <image><watch>...</watch></image>). The following parameters are recognized:

Here is an example how the watch mode can be tuned:

Given this configuration

You can build the service image, start up all containers and go into a watch loop. Again, you need the package phase in order that the assembly can find the artifact build by this project. This is a Maven limitation. The db image will never be watch since it assumed to not change while watching.

This goal can be used to clean up images. By default all images with a build configuration are removed. You can tune this by setting the property removeMode (property: docker.removeMode) to one of the following values:

Previously, this could be tuned also by providing the property removeAll which indicates to remove all images managed by this build. Otherwise only data images were delete before 0.24.0. removeAll is deprecated and will be removed soone. Please use removeMode instead.

As with the other goals, the configuration image can be used to tune the images to remove. All containers belonging to the images are removed as well as the all tags assigned to this image

Considering three images 'db','tomcat' and 'data' where 'data' is the only image with a build configuration:

With this goal it is possible to print out the logs of containers started from images configured in this plugin. By default only the latest container started is printed, but this can be changed with a property. The format of the log output is influenced by run configuration of the configured images. The following system properties can the behaviour of this goal:

This goal copies files and directories from a container. When called, then all images which are configured in the project and having copy element in the image configuration are iterated.

In addition to the Global configuration, this goal supports the following configuration options:

The copy image configuration element is honored by the goal and has the following sub elements:

Each item in the entries list of copy element consists of the following sub elements:

The docker:source target can be used to attach a docker build archive containing the Dockerfile and all added files to the Maven project with a certain classifier. It reuses the configuration from docker:build.

By default, only the first image configuration is used for creating the source archive. You can export all image configurations by setting the sourceMode configuration to all:

For exporting all image configurations, docker:source uses the image’s alias as part of the classifier, so it is mandatory that the alias is set for this goal to work when all images should be exported this way. The classifier is calculated as docker-<alias> so when the alias is set to service, then the classifier is docker-service.

If you only export the first image configuration (which is the default), then the classifier is just docker (without alias).

docker:source can be attached to a Maven execution phase, which is generate-sources by default.

For example, this configuration will attach the docker build archive to the artifacts to store in the repository:

If not bound to an execution phase, docker:source requires that the artifact has been created so you call it best together with package

The docker:save target saves an image defined in the build configuration to a local file, analogous to docker save. If the option saveFile is not set, the file name is calculated automatically:

Please note that the exported image contains all image layers and can be quite large (also, it takes a bit to export the image).

The file name extension is used to select a compression method for the output.

If saveClassifier is set, the saved archive will be attached to the project using the provided classifier and the type determined from the file name. The placeholder %a will be replaced with the image alias.

Note that using overriding the default to use docker or docker-%a may lead to a conflict if a source archive is also attached with docker:source.

The docker:tag tags an image so that it becomes part of a repository. You can use it to tag an already built image. Here is an example of it’s usage:

This goals creates one or more standalone Docker volume, which can be referenced in a docker:start configuration for linking to a volume during runtime. Each volume has therefore a unique and referenceable name. Beside the volume driver and driver options can be specified.

The following options are available when creating volumes:

This goals is the counterpart to docker:volume-create and removes a volume. Docker volumes are configured outside of Docker images, but can be referenced by them. The configuration is the same as for docker:volume-create

Example:

The configuration is quite simple. Only the name of the volume to delete is required.

For simple needs the image configuration can be completely defined via Maven properties which are defined outside of this plugin’s configuration. Such a property based configuration can be selected with an <type> of properties. As extra configuration a prefix for the properties can be defined which by default is docker.

For single-image configurations it is also possible to active property based configuration via an externally set property.

By default, property based configuration uses only properties, ignoring any <build> and <run> sections. To combine values from both sources, use the property mode configuration.

Properties are read from the Maven project (defined in <properties> or global Maven configuration from settings.xml) and, since 0.25.0, from any -D flags given to Maven (takes priority over project properties).

Given this example configuration a single image configuration is built up from the following properties, which correspond to the corresponding values in the <build> and <run> sections. A build configuration is only created when a docker.from or a docker.fromExt is set.

Multiple property configuration handlers can be used if they use different prefixes. As stated above the environment and ports configuration are both used for running container and building images. If you need a separate configuration you should use explicit run and build configuration sections.

List properties refer to XML configurations items that accept a list of values, like <build><tag> or <run><ports>. To specify values using properties, you must declare a property for each value you want to add to the list, and add a idx suffix to the property name to determine its position in the resulting list. For example:

The idx suffix defines the order of copying. Entries which idx is an integer number are copied first in ascending order by the parsed value of idx. Entries which idx is not an integer number are copied second in ascending alphabetical order by idx.

By default the property handler will only consider properties and ignore any other image configuration in the XML/POM file. This can be changed by adding the <mode> configuration (since version 0.25.0), which can have one of the following values:

It also possible to activate property configuration by setting the property docker.imagePropertyConfiguration to a valid property mode, without adding an <external> section. The plugin will then use any properties with default docker. prefix. This can be useful if most of the configuration is specified in XML/POM file, but there is need to override certain configuration values without altering the POM file (instead add this to a parent POM or global settings.xml).

If set in parent POM, but not wanted in specific project, the property could be overriden locally with the value skip to disabled property configuration for that particular project. If set in settings.xml however, by Maven design, that value will always take precedence over any properties defined in pom.xml.

For configurations with multiple images, using this property will by default produce an error. All images would then use the same docker property prefix, resulting in multiple identical configurations. This can be overruled by adding an explicit <external> configuration element with an explicit <prefix> to all images (or at least all but one). Normally you’d want to use different prefix for each image, but if explicitly set it does allow you to use the same prefix (even docker) on all images. This is useful in case you just want to share a few properties. This only makes sense when property mode is override or fallback and image-specific configuration are defined in the POM configuration.

For examples, see here

For some fields it may be desired to merge values from both POM and properties. For example, in a certain run environment we might want to inject a http_proxy environment variable, but we do not want to add this to the POM file.

This is solved using a Combine policy which can be either replace or merge. Merge is only available for configuration of Map or List type. For scalar values such as strings and integers, it is not supported. For Maps, both sources are merged, with the priority source taking precedence. For Lists, they are concatenated, with values from the priority source being added first.

Combine policy is specified per configuration key/property, and the default in most cases is currently replace. The following keys have merge as default policy:

This can be overridden individually for all configuration keys (of map/list type) by setting an additional property suffixed ._combine. For example, to not merge ports, set docker.ports._combine=replace, and to enable merging of dns, set docker.dns._combine=merge.

This would build the same image as the previous example. If instead built with mvn docker:build -Pdocker.from=console/tomcat:8.0 -Ddocker.tags.0=tc8-test it would build from that image instead, and also add that tag to the image.

If -Ddocker.labels.status=beta is added, the image would be given two labels: status=beta and software=tomcat. If -Ddocker.labels._combine=replace is added, the image would be given one label only: status=beta.

Global ~/.m2/settings.xml file:

When the plugin is executed, on a machine with the given settings.xml, the plugin will see the docker.imagePropertyConfiguration configuration and enable the property merging feature. When building, it will inject the http_proxy build ARG, and when running, it will inject the http_proxy ENV variable. The rest of the configuration will be sourced from the XML, unless the Maven project has any other docker.* properties defined.

Using the same global ~/.m2/settings.xml file as in previous example, but with two image definitions and no extra configuration will cause an error, saying that you cannot use property docker.imagePropertyConfiguration on projects with multiple images.

By adding an explicit external configuration directive with the same prefix in both images, this error is disabled.

The behaviour will now be same as previous example. Note that you must explicitly state <mode>override</mode>, otherwise it will use the default only.

This plugin supports also configuration via a docker-compose file, especially for running containers specified in docker-compose.yml. Docker Compose handling is available also as an external configuration provider.

The following options can be provided:

The Docker Compose file can contain variables as described in the Docker Compose documentation. These are substituted with Maven project properties. Please note, when the docker-compose.yml with variables is to be used with the docker-compose CLI command, that these variables must also be valid environment variables (i.e. must not contain a .).

In addition to the docker-compose.yml you can add all known options for <build> , <run> and <watch> configuration elements which are then used as defaults and are overwritten by the configuration defined in the docker-compose.yml file. The merging between the XML configuration and the information found in docker-compose.yml is correlated via the <alias> name. E.g. if the XML image configuration is aliased with webapp then its is used as a default configuration for a Docker Compose service name webapp. All other services defined in the compose file are left untouched.

The credentials lookup described above is valid for both push and pull operations. In order to narrow things down, credentials can be provided for pull or push operations alone:

In an <authConfig> section a sub-section <pull> and/or <push> can be added. In the example below the credentials provider are only used for image push operations:

When the credentials are given on the command line as system properties, then the properties docker.pull.username / docker.pull.password and docker.push.username / docker.push.password are used for pull and push operations, respectively (when given). Either way, the standard lookup algorithm as described in the previous section is used as fallback.

When working with the default registry in OpenShift, the credentials to authenticate are the OpenShift username and access token. So, a typical interaction with the OpenShift registry from the outside is:

(note, that the image’s username part ("default" here") must correspond to an OpenShift project with the same name to which you currently connected account has access).

This can be simplified by using the system property docker.useOpenShiftAuth in which case the plugin does the lookup. The equivalent to the example above is

Alternatively the configuration option <useOpenShiftAuth> can be added to the <authConfig> section.

For dedicated pull and push configuration the system properties docker.pull.useOpenShiftAuth and docker.push.useOpenShiftAuth are available as well as the configuration option <useOpenShiftAuth> in an <pull> or <push> section within the <authConfig> configuration.

If useOpenShiftAuth is enabled then the OpenShift Konfiguration will be looked up in $KUBECONFIG or, if this environment variable is not set, in ~/.kube/config.

Regardless which mode you choose you can encrypt password as described in the Maven documentation. Assuming that you have setup a master password in ~/.m2/security-settings.xml you can create easily encrypt passwords:

This password then can be used in authConfig, docker.password and/or the <server> setting configuration. However, putting an encrypted password into authConfig in the pom.xml doesn’t make much sense, since this password is encrypted with an individual master password.

Some docker registries require additional steps to authenticate. Amazon ECR requires using an IAM access key to obtain temporary docker login credentials. The docker:push and docker:pull goals automatically execute this exchange for any registry of the form <awsAccountId> .dkr.ecr. <awsRegion> .amazonaws.com, unless the skipExtendedAuth configuration (docker.skip.extendedAuth property) is set true.

Note that for an ECR repository with URI 123456789012.dkr.ecr.eu-west-1.amazonaws.com/example/image the d-m-p’s docker.registry should be set to 123456789012.dkr.ecr.eu-west-1.amazonaws.com and example/image is the <name> of the image.

You can use any IAM access key with the necessary permissions in any of the locations mentioned above except ~/.docker/config.json. Use the IAM Access key ID as the username and the Secret access key as the password. In case you’re using temporary security credentials provided by the AWS Security Token Service (AWS STS), you have to provide the security token as well. To do so, either specify the docker.auth system property or provide an <auth> element alongside username & password in the authConfig.

d-m-p will attempt to read AWS credentials from some well-known spots in case there is no explicit configuration:

If any of these authentication information is accessible, it will be used.