Docker plugin¶

Description¶

The Docker plugin is used for running or attaching to a Docker container.

Mandatory settings¶

Mandatory settings change depending on which mode is selected. See mode for more information.

Optional settings¶

The configuration of the make plugin may contain the following settings:

Settings for all modes¶

patterns: A list of patterns to apply on the command line. See Patterns (5).

enviroment: A list of environment variables that should be set before the commands are executed. See Environment (5).

command-line: Additional command line parameters to pass as a list of separate arguments. By default no additional arguments are added.

working-dir: The working directory of the command. Can be an absolute path are a relative one w.r.t. the path to the considered configuration file. Commands that should be executed relative to the current working dir can use the {EH_WORKING_DIR} pattern.

mode

Set the mode of the Docker call for the specific command. Default: exec.

Supported modes are:

run: Create a new container based on the given image and runs the given command. Note: use --rm as an additional command line argument to automatically clean up the created container.
exec: Run the command in the given, actively running, container.

env: A map of environment key/value pairs set inside the container. Default: an empty map.

interactive: Boolean indicating whether to run interactively inside the container. Check the Docker documentation for more information. Default: same as the used Docker default.

tty: Boolean indicating whether to use a pseudo-tty inside the container. Check the Docker documentation for more information. Default: same as the used Docker default.

privileged: Boolean indicating whether to run the container in privileged mode. Check the Docker documentation for more information. Default: no.

user: Set the given user inside the container. Check the Docker documentation for more information. Default: the container default.

Settings for the run mode¶

volumes: List of volumes to be mounted into the container. Eeach value maps directly to a Docker volume configuration. Check the Docker documentation for all the options and formats that can be used. Default: an empty list.

image: The Docker image to use as the base image for creating a new container. This configuration option is mandatory when the plugin is in run mode.

Settings for the exec mode¶

container: The Docker container to execute the command in. Note that the container must already be running when this command is called. This configuration option is mandatory when the plugin is in exec mode.

Example¶

Configuration¶

commands:                       # Define the commands that can be run
    example: Run the docker example
    run: Show the contents of the /example folder

patterns:                       # Define the patterns that can be used
    IMAGE:                      # Define the IMAGE
        default-values:         # Define the default value(s)
            - ubuntu:rolling
        short-option: i         # Define the short option for overriding the default value
        long-option: image      # Define the long option for overriding the default value

    COMMAND:
        default-values:
            - ls
            - echo

example:
    - docker                    # Use the docker plugin when running the 'example' command

ls:
    - command-line-command      # Use the 'command-line-command' plugin for constructing the 'ls' command

echo:
    - command-line-command      # Use the 'command-line-command' plugin for constructing the 'echo' command

docker:
    example:
        patterns:               # Define the patterns we will use for this command.
            - IMAGE             # Use the IMAGE pattern => all occurences of '{IMAGE}' will be replaced by the actual value
            - COMMAND
        mode: run               # Use the 'run' mode
        image: "{IMAGE}"        # Set the image. The quotes "" are required due to the YAML specification and its JSON compatibility.
        envs:                   # Define additional environment variables inside the container
            SHELL: xterm-color  # Use a YAML dictionary to define all kay-value pairs
        interactive: yes        # Run an interactive shell in the container
        tty: no                 # Do not attach to a pseudo-tty in the container
        privileged: no          # Do not run a privileged container
        user: root              # Explicitly run as the root user
        volumes:
            - "${PWD}:/examples"  # Mount the folder of this configuration file in the container on the /examples path
        targets: "{COMMAND}"    # Run the 'run' task in the configured container

command-line-command:
    ls:                        # Configure the 'run' command
        command-line: [ ls, -la, /root]  # Run 'ls -la /root'

    echo:                       # configure the 'echo' command
        command-line: [ echo, Hello world]   # Run 'echo Hello world'

Usage¶

Save the example to an exec-helper configuration file and execute in the same directory:

eh example