Direct Docker Access

Sometimes your pipelines need to be able to access a Docker daemon directly. You can now use Docker commands such as docker build, docker run, docker push in your pipeline, with full access to all their features.

Configuration

Simply set the property docker: true in your pipeline and a Docker daemon will be provisioned exclusively for your pipeline. When your pipeline terminates, the daemon (and the host on which it runs) is destroyed.

build:
  box: alpine
  docker: true
  steps:
  ...

You can use the docker command or any tool or a library that requires direct access to a Docker daemon. The environment variable DOCKER_HOST is set to the URI of the daemon.

Note that if your pipeline needs to use the docker command, you will need to specify a box image that already has Docker installed or add a step to install it.

Environment variables

The following additional environment variables are made available in your pipeline:

Variable name Example Description
DOCKER_HOST w-HuMwpXsKhN URI of docker daemon
DOCKER_NETWORK_NAME tcp://10.15.54.245:14567 Name of Docker bridge network used by the box (pipeline container) and the services

Docker networks

The pipeline container (and any services that you specify) are connected to a Docker bridge network created by Wercker. The name of the network is available in the environment variable $DOCKER_NETWORK_NAME.

This means that if your pipeline starts a container, then you should connect it to the same network. This allows the pipeline container (and other containers on that network) to create connections to the new container using the name of the container as the hostname.

For example, if you want to use the docker run command to start a container, then you can do this by adding the --network=$DOCKER_NETWORK_NAME parameter.

Example

The following example shows a pipeline which requires direct access to a Docker daemon, and therefore specifies docker: true property.

The pipeline starts by installing docker and curl.

It then uses the docker run command to start a container using a sample image from Docker that starts a simple web server. The --network=$DOCKER_NETWORK_NAME parameter is used to add the container to the same network as the pipeline container.

The curl command is then used to send a HTTP GET request to the web server. Note that the name of the container is used as the hostname, which is only possible because we specified --network=$DOCKER_NETWORK_NAME.

Finally, the docker kill command is used to kill the container.

build:
  box: alpine
  docker: true
  steps:
    - script:
        name: Install docker
        code: apk --no-cache add docker
    - script:
        name: Install Curl
        code: apk --no-cache add curl
    - script:
        name: Run a docker container
        code: docker run --rm -d -p 8888:80 --name static-site --network=$DOCKER_NETWORK_NAME dockersamples/static-site
    - script:
        name: Connect to the container
        code: |
          sleep 2 # allow time for the container to start
          curl static-site:80
    - script:
        name: kill the container using docker kill
        code: |
          docker kill static-site

Volumes and mounts

When starting a Docker container, you can specify volumes and mounts in the usual way. However, you need to be aware that your pipeline runs in a container rather than on the host machine directly. This means that you can’t directly mount directories that exist within the pipeline container.

If your containers need access to files or directories that exist in the pipeline container, you can use the docker cp command to copy them to the new container.

How does direct Docker access relate to the internal steps for Docker?

Wercker already has some built-in steps to perform basic Docker operations. These are internal/docker-build, internal/docker-push, internal/docker-scratch-push, internal/docker-run and internal/docker-kill. For more information see Internal Steps and Building an image.

These steps allow you to perform various Docker operations without the need for direct Docker access. They are faster and simpler than using the docker command but have limitations.

In addition, the internal/docker-push and internal/docker-scratch-push steps provide a way to convert the currently running pipeline container directly into a Docker image and push it immediately to a registry. This avoids the need to create a Dockerfile and use the docker build and docker push commands.