Running an image

The internal/docker-run step runs a Docker image. This step is equivalent to running the Docker command docker run.

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-build step:

- 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-kill step.


The internal/docker-run step supports the following properties:

  • image(mandatory): Indicates the image that will be used to create a container. This must either match the image-name property specified in a prior internal/docker-build step, 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): Indicates the name of the container. It also acts as the hostname of the container.
  • user: Indicates 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:
    • "porta portb portc"
    • "porta:portx portb:porty portc:portz".

In the first format, publishing of container would be→porta,→portb,→portc.

In the second format, publishing of the container would be→portx,→porty,→portz.

For example, "80:8080 443:8443" would be published as→8080/tcp,→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, sleep 30.
  • workingDir: Indicates the working directory for the commands to run in inside the newly created container.
  • entrypoint: Indicates 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.

Container Networking

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.