Installing and Using Docker Compose

This document describes how to install and use Docker Compose, and assumes the reader has some experience using the docker-compose utility.

If you are new to Docker Compose, do consider reviewing the official Docker Compose overview, or checking out the Getting Started guide.

The docker compose utility is pre-installed in the CircleCI convenience images and machine executor images.

If you are using the Docker executor and are not using a convenience image, you can install Docker Compose into your primary container during the job execution with the Remote Docker Environment activated by adding the following to your .circleci/config.yml file:

      - run:
          name: Install Docker Compose
          environment:
            COMPOSE_VERSION: 'v2.25.0'
          command: |
            curl -sSL "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o ~/docker-compose
            mkdir -p ~/.docker/cli-plugins
            chmod +x ~/docker-compose
            mv ~/docker-compose ~/.docker/cli-plugins/docker-compose

The above code example assumes that you will also have curl available in your executor. If you are constructing your own docker images, consider reading the custom docker images document.

Then, to activate the Remote Docker Environment, add the setup_remote_docker step:

      - setup_remote_docker

This step enables you to run docker compose commands to build images:

      - run:
          name: Build images of services declared in docker-compose.yml
          command: docker compose build

Or to run the whole system:

      - run:
          name: Start all services declared in docker-compose.yml
          command: docker compose up -d

Or to also verify if a service is running for example:

      - run:
          name: Start docker compose and verify service(s)
          command: |
            # Setting the Docker Compose project name to "circleci-demo-docker" means
            # the names of our services' containers would be prefixed with "circleci-demo-docker".
            docker compose --project circleci-demo-docker up -d

            # In this example, we have a "contacts" service, and
            # we are trying to check, via `dockerize`, if the service is ready.
            docker container run --network container:circleci-demo-docker_contacts_1 \
              docker.io/jwilder/dockerize \
              -wait http://localhost:8080/healthcheck \
              -wait-retry-interval 2s \
              -timeout 20s

See the Example docker-compose Project on GitHub for a demonstration and use the full configuration file as a template for your own projects.

Note: The primary container runs in a separate environment from Remote Docker and the two cannot communicate directly. To interact with a running service, run a container in the service’s network.

If you want to use Docker Compose to manage a multi-container setup with a Docker Compose file, use the machine key in your .circleci/config.yml file and use docker compose as you would normally (see Linux VM execution environment documentation here for more details). That is, if you have a Docker Compose file that shares local directories with a container, this will work as expected. Refer to Docker’s documentation of Your first docker-compose.yml file for details.

Using docker combined with setup_remote_docker provides a remote engine similar to the one created with docker-machine, but volume mounting and port forwarding do not work the same way in this setup. The remote docker daemon runs on a different system than the docker CLI and docker compose, so you must move data around to make this work. Mounting can usually be solved by making content available in a docker volume. It is possible to load data into a docker volume by using docker cp to get the data from the CLI host into a container running on the docker remote host.

This combination is required if you want to build docker images for deployment.

Using docker compose with the macos executor is not supported. See our support article for more information.

Running Docker Commands