What Is Docker Compose? A Beginner's Guide

Docker Compose lets you describe a multi-container application in a single YAML file and start the whole thing with one command. Instead of typing a long docker run line for your web app, then another for your database, then another for a cache, you write them down once in compose.yaml and run docker compose up.

Docker's documentation on the Compose application model puts it this way: you use a YAML configuration file, known as the Compose file, and manage it with the Compose command line tool. If you are new to containers, read what Docker is first, because Compose builds on those ideas.

The file Compose looks for

Compose looks for compose.yaml first, then compose.yml, in the working directory. It also supports docker-compose.yaml and docker-compose.yml for backward compatibility, and if both naming styles exist, compose.yaml takes precedence. That is why AI tools trained on older tutorials sometimes create docker-compose.yml. Both work, but prefer the newer name.

Because the file is YAML, indentation is meaning. You can also split a setup across several files: the Docker docs say multiple Compose files can be merged, with later files overriding simple values and appending to lists. That is handy for keeping a base setup plus a local override. If that is unfamiliar, what a YAML file is and why spaces matter will save you an hour.

The five building blocks

The Docker docs define a handful of concepts. These are the ones you will meet in almost every file.

• Services. A service is a computing component of the application. The docs describe it as an abstract concept implemented by running the same container image, one or more times. In practice: your web app is a service, your database is a service.

• Networks. Services talk to each other over networks. A network establishes an IP route between connected containers.

• Volumes. Services store and share persistent data in volumes. Without one, data in a container disappears when the container is removed.

• Configs. Runtime or platform-dependent configuration that appears inside the container as mounted files.

• Secrets. Sensitive data, also mounted into containers as files. They are a separate concept so that platforms can handle them more safely than ordinary settings.

Reading a real example

The Docker docs include this non-normative example, a frontend and a backend with a persistent volume, two networks, one config, and one secret:

services:
  frontend:
    image: example/webapp
    ports:
      - "443:8043"
    networks:
      - front-tier
      - back-tier
    configs:
      - httpd-config
    secrets:
      - server-certificate

  backend:
    image: example/database
    volumes:
      - db-data:/etc/data
    networks:
      - back-tier

volumes:
  db-data:
    driver: flocker
    driver_opts:
      size: "10GiB"

configs:
  httpd-config:
    external: true

secrets:
  server-certificate:
    external: true

networks:
  # The presence of these objects is sufficient to define them
  front-tier: {}
  back-tier: {}

Read it top to bottom. The frontend service publishes a port and joins both networks. The backend service, the database, joins only back-tier, so the frontend can reach it but nothing else can. That small detail is the main benefit of networks: you decide which services can see each other.

The db-data volume is what keeps the database contents alive between restarts. The config and secret entries are marked external: true, which means they are defined outside this file.

The two commands you use daily

The docs list these basics:

docker compose up     # start all services in compose.yaml
docker compose down   # stop and remove the running services

Two more are handy: docker compose ps to check what is running, and docker compose logs to see container output. When something fails to start, logs are the first place to look.

Do you need Compose?

If your AI-built app is one process that talks to a hosted database, you probably do not. Compose earns its place when you want the whole stack, say an app, a local database, and a queue, running identically on your machine and a teammate's, or inside a dev container for your AI coding agent.

If you do use it, keep real passwords out of the file. Use the secrets mechanism, or follow our advice on environment variables and secrets in an AI-built app. And if an agent writes your Dockerfile too, check it against how to prompt AI to write a Dockerfile that builds fast. More tools like this live in the AI coding tools guide.

Frequently asked questions

What is Docker Compose used for?

It defines and runs multi-container applications from one YAML file, so you can start a whole stack, such as a web app and its database, with a single command.

What is the difference between Docker and Docker Compose?

Docker runs individual containers. Compose describes several containers and how they connect, then manages them together.

What should the Compose file be called?

compose.yaml is the preferred name. Compose also reads compose.yml, docker-compose.yaml, and docker-compose.yml, and compose.yaml wins if more than one exists.

Does docker compose down delete my data?

It stops and removes the running services. Data kept in a named volume is separate from the containers, so check the volume settings before assuming either way.