internal/docker-run step runs a Docker image. This step is equivalent to running the Docker command
The main purpose of the
internal/docker-run step is to allow the users to test an image that is built using the
internal/docker-build step. However, you can use this step whenever you want your pipeline to start a Docker image.
Wercker already offers a feature called services that allows you to automatically start one or more Docker images at the beginning of a pipeline and automatically shut it down at the end. However, this does not allow an image to be started half-way through a pipeline in order to test an image created in a preceding step. The
internal/docker-run step addresses this limitation by allowing an image to be started at any point in the pipeline.
The following step runs an image created earlier by the
- internal/docker-run: image: my-new-image name: myTestContainer
This creates a container using the specified image and runs it in the detached mode. The
name property is used to give the container a name. The container will automatically be shut down at the end of the pipeline.
Sometimes, it might be necessary to kill a specific container that has been started by the
docker-run command before the end of the pipeline is reached. You can do this using the
internal/docker-run step supports the following properties:
image(mandatory): Specifies the image that will be used to create a container. This must either match the
image-nameproperty specified in a prior
internal/docker-buildstep, or the repository (and optional tag) of an image in an image registry. In case the registry needs authentication, you must authenticate the registry in the same way as you’d do for a Box image.
name(mandatory): Specifies the name of the container. It also acts as the hostname of the container.
username: If the specified
imageis in a private registry, then this property may be set to the username which will be used when pulling the image. If not set, then any username specified on the
boxwill be used.
password: If the specified
imageis in a private registry, then this property may be set to the password which will be used when pulling the image. If not set, then any password specified on the
boxwill be used.
registry: If the specified
imageis in a private registry, then this property may be set to the registry which will be used when pulling the image. If not set, then any registry specified on the
boxwill be used.
user: Specifies the user that commands run inside the container.
ports: A list of ports that are exposed and published as part of the run. These can be given in the following two formats:
In the first format, publishing of container would be 0.0.0.0:porta→porta, 0.0.0.0:portb→portb, 0.0.0.0:portc→portc.
In the second format, publishing of the container would be 0.0.0.0:porta→portx, 0.0.0.0:portb→porty, 0.0.0.0:portc→portz.
For example, “80:8080 443:8443” would be published as 0.0.0.0:80→8080/tcp, 0.0.0.0:443→8443/tcp. In consistency with the services, the command line argument –expose-ports is necessary for publishing ports.
env: A set of environment variables that you must set inside an image. Set the environment variables with one or more key-value pairs in the following format:
VAR=value, with multiple values separated by spaces. Enclose the resulting string in double-quotes. If the value contains spaces, you must enclose it within single quotes. For example,
"VAR1=value1 VAR2='Three word value'".
cmd: Used to specify a command that is run as a string or an array of strings. Input is space delimited entries. For example,
workingDir: Specifies the working directory for the commands to run in inside the newly created container.
entrypoint: Specifies the entry point for the container as a string or an array of strings. If the array consists of exactly one empty string ([“”]) then the entry point is reset to system default (that is, the entry point used by docker when there is no
ENTRYPOINT instruction in the Dockerfile). Input is in the form of space delimited entries. For example,
sh -c tail -f /dev/null.
When you start a container from your Wercker build using the
docker-run command, you can connect to it from the main box container, or from other containers that you have started using the container’s name and port, where the name that you use is specified using the
name property of the
docker-run step. For example:
- internal/docker-run: image: mongo:2.2.7 name: mon1
When connecting to a container, note that the port must have been exposed by that container.