Installing and Using docker-compose
This document describes how to install and use docker-compose
.
- 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 executors. If you are using another image, you
can install it into your primary container during the job
execution with the Remote Docker Environment activated by adding the following
to your config.yml
file:
- run:
name: Install Docker Compose
command: |
curl -L https://github.com/docker/compose/releases/download/1.25.3/docker-compose-`uname -s`-`uname -m` > ~/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 add docker-compose
commands to build images:
docker-compose build
Or to run the whole system:
docker-compose up -d
In the following example, the whole system starts, then verifies it is running and responding to requests:
- run:
name: Start container and verify it is working
command: |
set -x
docker-compose up -d
docker run --network container:contacts \
appropriate/curl --retry 10 --retry-delay 1 --retry-connrefused http://localhost:8080/contacts/test
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, use docker and a container running 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 config.yml
file and use docker-compose as you would normally (see machine executor 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. Note: There is an overhead for provisioning a machine executor as a result of spinning up a private Docker server. Use of the machine
key may require additional fees in a future pricing update.
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 the support article for more information.
See also
See the Mounting Folders section of the Running Docker Commands for examples and details.