fabric8io docker-maven-plugin

The docker-maven-plugin is a Maven plugin designed for building Docker images and managing containers, specifically for use in integration testing workflows. It integrates Docker lifecycle management directly into the Maven build lifecycle.

Requirements:

• Maven: 3.0.5 or later
• Docker: 1.6.0 or later

Docker API Compatibility Notes:

• Use Docker 1.8.1+ if you need docker:watch.
• Use Docker 1.9+ if you need custom networks or build arguments.
• Docker 29+ (v1.44) is required for compatibility with Docker 29+ daemons.

The watchMode parameter (property docker.watchMode) determines the reaction to detected changes:

• build: Rebuilds the image when changes are detected in the assembly.
• run: Restarts the container if its image changes.
• copy: Copies changed files directly into the container (requires Docker >= 1.8). The container must be running or be a data container linked to a platform container.
• both: Combines build and run behaviors.
• none: Disables watching for that specific image (useful for pre-built images).

You can connect containers using the <links> element within the <run> configuration. This allows one container to access another using a specific alias.

Example: <link>database:db</link> links the image with the alias database into the current container, making it accessible via the hostname db (and typically providing environment variables like DB_ for connection details).

<run>
  <links>
    <link>database:db</link>
  </links>
</run>

To specify multiple values for configuration items that accept lists (like ports, tags, or volumes), use an _idx suffix in the property name.

• Integer indices (e.g., .1, .2) are processed first in ascending order.
• Non-integer indices (e.g., .alpha, .beta) are processed second in ascending alphabetical order.

The <wait> section allows you to block the Maven build execution until specific conditions are met after a container starts. As soon as one condition is met, the build continues.

If you include a <time> element, it acts as a timeout for other conditions (like http or log). If the timeout is reached before the condition is met, the build aborts. If only <time> is specified without other conditions, the build simply waits for that duration and then proceeds.

You can use Maven properties (e.g., ${host.port}) within any of these configuration elements.

<wait>
  <http>
    <url>http://localhost:${host.port}</url>
    <method>GET</method>
    <status>200..399</status>
  </http>
  <time>10000</time>
</wait>

The property ${docker.host.address} is implicitly set to the address of the Docker host.

• If using HTTP/HTTPS, it is taken from the docker.host configuration.
• If using a Unix socket, it defaults to localhost.
• You can override this value by setting the Maven property explicitly.

The plugin supports variable substitution in docker-compose.yml files using Maven project properties.

Important Note: If you intend to run the same docker-compose.yml file using the standard docker-compose CLI command, the variables used must be valid environment variables (i.e., they must not contain a dot .).

To achieve true isolation, you can map container-exposed ports to dynamic host ports. By specifying a Maven property name in the <run> section, the plugin will assign the dynamically chosen host port to that property. This allows your integration tests to discover the correct port at runtime.

Example: <port>tomcat.port:8080</port> maps the container's port 8080 to a host port, which is then accessible via the Maven property ${tomcat.port}.

<run>
  <ports>
    <port>tomcat.port:8080</port>
  </ports>
</run>

The <wait> configuration in the <run> section allows you to pause the Maven build until a container is actually ready to handle requests. You can wait based on three criteria:

1. HTTP: Check if a specific URL is reachable. Requires a <url> and an optional <time> (timeout).
2. Log: Check if a specific text pattern appears in the container's log output. Requires a <log> pattern and an optional <time> (timeout).
3. Time: A simple delay (though HTTP and Log are preferred for reliability).

Goals that refer to images or containers (like stop or remove) support Ant-like path matching patterns. These patterns account for registry names, repository paths, and tags.

Wildcards:

• ?: Matches a single character.
• *: Matches zero or more characters up to the next slash / or the tag separator :.
• **: Matches zero or more characters up to the tag separator :.
• **/: Matches zero or more characters up to a slash, ensuring the match ends with a slash.

// Example patterns:
**tomcat:jdk-11*
**/megacorp/tomcat:*alpine
megacorp/*-operator:* 

When using dynamic port assignment or capturing host IPs, the resolved values are only available in the Maven model after the container has started. This can cause issues for other plugins that resolve properties in earlier lifecycle phases.

To solve this, use the portPropertyFile configuration option. This writes the resolved host IP and dynamic ports to a file. The keys in the file are the property names defined in your <ports> configuration, and the values are the actual attributes assigned by Docker.