Docker Compose

Docker Compose cheatsheet — start, stop, build, scale services. docker compose up -d, docker compose logs -f, docker compose exec, docker compose down -v. Full reference.

6 min read

What it is

Docker Compose is a tool for defining and running multi-container Docker applications, allowing you to manage your application’s services, networks, and volumes in a single docker-compose.yml file.

Installation

Linux:

# Download the latest Docker Compose binary
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Apply executable permissions
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker-compose --version

Mac:

# Download the latest Docker Compose binary
curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Apply executable permissions
chmod +x /usr/local/bin/docker-compose

# Verify installation
docker-compose --version

Windows:

Docker Compose is included with Docker Desktop for Windows. If you have Docker Desktop installed, Docker Compose is already available. You can verify by opening PowerShell or Command Prompt and running:

docker-compose --version

If you need to install it manually, you can download the binary from the Docker Compose releases page and add it to your system’s PATH.

Core Concepts

  • Services: Each service in your docker-compose.yml represents a container image that will be run. You define how each service is built or pulled, its ports, volumes, environment variables, and dependencies.
  • Networks: Docker Compose automatically creates a default network for your application. Services within the same Compose project can communicate with each other using their service names as hostnames. You can also define custom networks.
  • Volumes: Volumes are used to persist data generated by and used by Docker containers. Compose makes it easy to manage volumes for your services.
  • docker-compose.yml: This is the core configuration file where you define your application’s services, networks, and volumes. It uses YAML syntax.

Commands / Usage

Project Management

  • docker-compose up: Builds, creates, starts, and attaches to containers for a service.

    • docker-compose up -d: Starts containers in detached mode (in the background).
    • docker-compose up --build: Builds images before starting containers.
    • docker-compose up --force-recreate: Recreates containers even if their configuration and image haven’t changed.
    • docker-compose up --no-deps <service_name>: Starts a specific service without starting its dependencies.

  • docker-compose down: Stops and removes containers, networks, images, and volumes defined in the Compose file.

    • docker-compose down -v: Removes named volumes declared in the volumes section of the Compose file and anonymous volumes attached to containers.
    • docker-compose down --rmi all: Removes all images used by any service.
    • docker-compose down --timeout 60: Specifies a shutdown timeout in seconds for stopping containers.

  • docker-compose start: Starts existing containers for services.

  • docker-compose stop: Stops existing containers for services without removing them.

  • docker-compose restart: Restarts existing containers for services.

  • docker-compose kill: Forces the termination of containers for services.

Service Management

  • docker-compose ps: Lists containers for the current Compose project.

    • docker-compose ps -q: Lists only container IDs.

  • docker-compose logs: Displays the logs of services.

    • docker-compose logs -f: Follows log output.
    • docker-compose logs --tail 100: Displays the last 100 lines of logs.
    • docker-compose logs <service_name>: Displays logs for a specific service.

  • docker-compose exec <service_name> <command>: Executes a command in a running container.

    • docker-compose exec web bash: Opens an interactive bash shell in the web service container.
    • docker-compose exec db pg_dump -U postgres mydatabase > backup.sql: Dumps the database from the db service.

  • docker-compose run <service_name> <command>: Runs a one-off command in a new container for a service. This creates a new container based on the service’s image and runs the specified command.

    • docker-compose run --rm web python manage.py migrate: Runs a migration command in a new web container and removes it afterward.

Image and Build Management

  • docker-compose build: Builds or rebuilds services.

    • docker-compose build --no-cache: Builds without using cache.
    • docker-compose build <service_name>: Builds a specific service.

  • docker-compose pull: Pulls service images.

    • docker-compose pull <service_name>: Pulls an image for a specific service.

  • docker-compose push: Pushes service images.

Configuration and Inspection

  • docker-compose config: Validates and views the Compose file.

    • docker-compose config --services: Lists the services defined in the Compose file.
    • docker-compose config --images: Lists the images used by the Compose file.

  • docker-compose version: Shows version information.

Common Patterns

  • Starting application in the background:

    docker-compose up -d

  • Stopping and removing all resources:

    docker-compose down

  • Stopping and removing all resources including volumes:

    docker-compose down -v

  • Viewing logs for a specific service:

    docker-compose logs -f web

  • Entering a running container:

    docker-compose exec app bash

  • Running a database migration:

    docker-compose run --rm web python manage.py migrate

  • Creating a database backup:

    docker-compose exec db pg_dump -U postgres mydatabase > backup_$(date +%Y%m%d_%H%M%S).sql

  • Rebuilding an image and restarting services:

    docker-compose up -d --build

  • Checking the configuration and syntax:

    docker-compose config

  • Listing only container IDs:

    docker-compose ps -q

  • Stopping containers without removing them:

    docker-compose stop

Gotchas

  • Default Network: If you run docker-compose up in a directory without a docker-compose.yml file, Compose will still create a default network and attempt to start services if it finds a Dockerfile in the current directory. This can sometimes lead to unexpected behavior if you’re not in a project directory.
  • Volume Naming: When defining volumes in docker-compose.yml, if you use named volumes (e.g., mydata:/data), Compose will prefix the volume name with the project name (e.g., myproject_mydata). If you want to use a globally named volume, you need to ensure it’s defined at the top level of the docker-compose.yml file.
  • docker-compose run vs. docker-compose exec: run creates a new container from the service’s image for a one-off task and then removes it (if --rm is used). exec runs a command inside an already running container.
  • Orphaned Containers: If you stop and remove containers using docker-compose down but don’t remove volumes (-v), or if you manually remove containers, you might end up with orphaned volumes. Similarly, if you change the docker-compose.yml and run up -d again, old containers that are no longer defined might persist as "orphaned." docker-compose ps will show these.
  • File Permissions: When mounting volumes from your host machine into containers, be mindful of file ownership and permissions. Containers often run as a non-root user, and permission issues can arise if the host files are owned by root or a different user.
  • Version Compatibility: Ensure your Docker Compose version is compatible with your Docker Engine version. Newer Compose features might require a newer Docker Engine.
  • depends_on behavior: depends_on only guarantees that the dependent service’s container is started before the current service’s container. It does not guarantee that the dependent service is ready to accept connections. You might need to implement health checks or retry logic in your application.