Installing and Using Docker Compose

today • 1 min read

Cloud Server v3.x Server v2.x

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.

• Example project
• Using Docker Compose with machine executor
• Using Docker Compose with docker executor
• Limitations

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: '1.29.2'
          command: |
            curl -L "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o ~/docker-compose
            chmod +x ~/docker-compose
            sudo mv ~/docker-compose /usr/local/bin/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

Example project

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.

Using Docker Compose with machine executor

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 Compose with docker executor

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.

Limitations

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

See also

See the Mounting Folders section of the Running Docker Commands for examples and details.

---

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

• Suggest an edit to this page (please read the contributing guide first).
• To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
• CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

---

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.