_global-configuration.adoc

Global configuration

Global configuration parameters specify overall behavior like the connection to the Docker host. The corresponding system properties which can be used to set it from the outside are given in parentheses.

The docker-maven-plugin uses the Docker remote API so the URL of your Docker Daemon must somehow be specified. The URL can be specified by the dockerHost or machine configuration, or by the DOCKER_HOST environment variable.

The Docker remote API supports communication via SSL and authentication with certificates. The path to the certificates can be specified by the certPath or machine configuration, or by the DOCKER_CERT_PATH environment variable.

Table 1. Global Configuration

Element	Description	Property
apiVersion	Use this variable if you are using an older version of docker not compatible with the current default use to communicate with the server.	docker.apiVersion
authConfig	Authentication information when pulling from or pushing to Docker registry. There is a dedicated section Authentication for how doing security.
autoCreate CustomNetworks	Create automatically Docker networks during {plugin}:start and remove it during {plugin}:stop if you provide a custom network in the run configuration of an image. The default is false.	docker.autoCreate CustomNetworks
autoPull	Decide how to pull missing base images or images to start. This option is deprecated, please use imagePullPolicy instead. The following values are supported: on or once: Automatic download any missing images (default) off : Automatic pulling is switched off always always : Pull images always even when they already exist locally.	docker.autoPull
buildArchiveOnly	Skip the actual Docker image build and only create the archive holding the Dockerfile and build context. The following values are supported: /path/to/archive : Create the build tar archive as file with name /path/to/archive and then stop without doing the actual image build true (or an empty value) : Skip building the image, but don’t copy the generated build archive. false : Build the image. This is the default behaviour.	docker.buildArchiveOnly
certPath	Path to SSL certificate when SSL is used for communicating with the Docker daemon. These certificates are normally stored in ~/.docker/. With this configuration the path can be set explicitly. If not set, the fallback is first taken from the environment variable DOCKER_CERT_PATH and then as last resort ~/.docker/. The keys in this are expected with it standard names ca.pem, cert.pem and key.pem. Please refer to the Docker documentation for more information about SSL security with Docker.	docker.certPath
dockerHost	The URL of the Docker Daemon. If this configuration option is not given, then the optional <machine> configuration section is consulted. The scheme of the URL can be either given directly as http or https depending on whether plain HTTP communication is enabled or SSL should be used. Alternatively the scheme could be tcp in which case the protocol is determined via the IANA assigned port: 2375 for http and 2376 for https. Finally, Unix sockets are supported by using the scheme unix together with the filesystem path to the unix socket. The discovery sequence used by the docker-maven-plugin to determine the URL is: value of dockerHost (docker.host) the Docker host associated with the docker-machine named in <machine>, i.e. the DOCKER_HOST from docker-machine env. See below for more information about Docker machine support. If <machine> is not set, then no docker-machine detection is used. the value of the environment variable DOCKER_HOST. /var/run/docker.sock if it is a readable socket (Unix & OS X). //./pipe/docker_engine if it is a readable named pipe (Windows)	docker.host
filter	In order to temporarily restrict the operation of plugin goals this configuration option can be used. Typically this will be set via the system property docker.filter when Maven is called. The value can be a single image name (either its alias or full name) or it can be a comma separated list with multiple image names. Any name which doesn’t refer an image in the configuration will be ignored.	docker.filter
imagePullPolicy	Specify whether images should be pull when looking for base images while building or images for starting. This property can take the following values (case insensitive): IfNotPresent: Automatic download any missing images (default) Never : Automatic pulling is switched off always Always : Pull images always even when they already exist locally. 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).	docker.imagePullPolicy
logDate	Date format which is used for printing out container logs. This configuration can be overwritten by individual run configurations and described below. The format is described in Logging.	docker.logDate
logStdout	For all container logging to standard output if set to true, regardless whether a file for log output is specified. See also Logging	docker.logStdout
machine	Docker machine configuration. See Docker Machine for possible values
maxConnections	Number of parallel connections are allowed to be opened to the Docker Host. For parsing log output, a connection needs to be kept open (as well for the wait features), so don’t put that number to low. Default is 100 which should be suitable for most of the cases.	docker.maxConnections
jib	Delegate Image Build process to JIB, false by default. Note that this option is applicable only for build and push goals, other goals won’t work if this is enabled (since they dependend on Docker specific features)	docker.build.jib
jibImageFormat	Format of the image to be built. Values can be oci and docker with docker as default value	docker.build.jib.imageFormat
outputDirectory	Default output directory to be used by this plugin. The default value is target/docker and is only used for the goal {plugin}:build.	docker.target.dir
portPropertyFile	Global property file into which the mapped properties should be written to. The format of this file and its purpose are also described in Port Mapping.
registry	Specify globally a registry to use for pulling and pushing images. See Registry handling for details.	docker.registry
skip	With this parameter the execution of this plugin can be skipped completely.	docker.skip
skipBuild	If set no images will be build (which implies also skip.tag) with {plugin}:build	docker.skip.build
skipPush	If set dont push any images even when {plugin}:push is called.	docker.skip.push
skipPom	If set to true this plugin will skip every projects, where project.packaging is set to pom.	docker.skip.pom
skipRun	If set dont create and start any containers with {plugin}:start or {plugin}:run	docker.skip.run
skipTag	If set to true this plugin won’t add any tags to images that have been built with {plugin}:build. If set to true this plugin won’t push any tags with {plugin}:push. If set to true this plugin won’t remove any tags with {plugin}:remove.	docker.skip.tag
skipMachine	Skip using docker machine in any case	docker.skip.machine
sourceDirectory	Default directory that contains the assembly descriptor(s) used by the plugin. The default value is src/main/docker. This option is only relevant for the {plugin}:build goal.	docker.source.dir
useColor	Whether to use colored log output. By default this is switched on when running on a console, off otherwise.	docker.useColor
outputFile	If specified, this parameter will cause the logs to be written to the path specified, instead of writing to the console.	outputFile
verbose	String attribute for switching on verbose output on standard output (stdout). It takes a comma separated list of string values to switch on various verbosity groups. The currently known groups are: build:: Print out Docker build instructions api:: API calls to the Docker daemons are logged all:: All levels are enabled If you set an empty string (or only e.g. -Ddocker.verbose) then the "build" group is enabled. You can also use "true" / "false" to switch on / off verbose logging. Default is that verbose logging is disabled.	docker.verbose

Example

<configuration>
   <dockerHost>https://localhost:2376</dockerHost>
   <certPath>src/main/dockerCerts</certPath>
   <useColor>true</useColor>
   .....
</configuration>

Docker Machine

This plugin supports also Docker machine (which must be installed locally, of course). A Docker machine configuration can be provided with a top-level <machine> configuration section. This configuration section knows the following options:

Table 2. Docker Machine Options

Element	Description
name	Docker machine’s name. Default is default
autoCreate	if set to true then a Docker machine will automatically created. Default is false.
regenerateCertsAfterStart	if set to true then certificates will be regenerated after starting the Docker Machine. This is useful if using the AWS EC2 driver, which will assign machines new IP addresses after each start. Default is false.
createOptions	Map with options for Docker machine when auto-creating a machine. See the docker machine documentation for possible options.

When no Docker host is configured or available as an environment variable, then the configured Docker machine is used. If the machine exists but is not running, it is started automatically. If it does not exists but autoCreate is true, then the machine is created and started. Otherwise, an error is printed. Please note, that a machine which has been created because of autoCreate gets never deleted by docker-maven-plugin. This needs to be done manually if required.

In absence of a <machine> configuration section the Maven property docker.machine.name can be used to provide the name of a Docker machine. Similarly, the property docker.machine.autoCreate can be set to true for creating a Docker machine, too.

You can use the property docker.skip.machine if you want to override the internal detection mechanism to always disable docker machine support.

Example

<!-- Work with a docker-machine -->
<configuration>
  <machine>
    <name>maven</name>
    <autoCreate>true</autoCreate>
    <createOptions>
      <driver>virtualbox</driver>
      <virtualbox-cpu-count>2</virtualbox-cpu-count>
    </createOptions>
  </machine>
   .....
</configuration>