Skip to content
Tutorials Center
My learning

Topics

Lesson 58 of 111 ยท Docker Compose

Introduction to Docker Compose

Start with Docker Compose: why it exists, how a compose.yaml describes services, what docker compose up and down do, project names, and why the version key is obsolete.

By now you have typed long docker run commands with networks, volumes, ports and environment variables, and you have started several containers in the right order by hand. It works, but it is easy to forget a flag, impossible to review in a pull request, and painful to repeat on a teammate's machine. Docker Compose fixes this by letting you describe your whole application, its containers, networks and volumes, in one YAML file and manage it with a few short commands.

In this lesson you will write your first compose.yaml, bring it up and down, read the output, learn what Compose creates for you, and understand projects, file names and the obsolete version: key. All output below comes from Docker Compose v5 on Docker Engine 29.

The problem Compose solves

Here is a small system: a web server serving static files and a Redis cache, with a published port and a read-only bind mount. With plain Docker you need a network and two container commands:

CONSOLE
$ docker network create hello_default
$ docker run -d --name hello-cache-1 --network hello_default --network-alias cache redis:alpine
$ docker run -d --name hello-web-1 --network hello_default --network-alias web \
    -p 127.0.0.1:8080:80 -v "$PWD/site:/usr/share/nginx/html:ro" nginx:alpine

Now imagine ten services, each with environment variables, healthchecks and volumes, and a new developer who has to copy-paste all of it correctly. Compose turns the same setup into a file that lives in your repository next to the code:

YAML
# compose.yaml
name: hello

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    depends_on:
      - cache

  cache:
    image: redis:alpine

(We used a different host port than the examples earlier in this track to avoid clashes; use any free port.) Create a folder site with an index.html containing <h1>Hello from Compose</h1> next to this file. Then one command starts everything.

Your first docker compose up

Run it in the folder that contains compose.yaml:

CONSOLE
$ docker compose up -d
 Network hello_default Creating
 Network hello_default Created
 Container hello-cache-1 Creating
 Container hello-cache-1 Created
 Container hello-web-1 Creating
 Container hello-web-1 Created
 Container hello-cache-1 Starting
 Container hello-cache-1 Started
 Container hello-web-1 Starting
 Container hello-web-1 Started

Read the log from top to bottom, because it tells you exactly what Compose did:

  1. It created a network named hello_default (the project name, an underscore, default).
  2. It created the cache container first, because web declares depends_on: cache.
  3. It created the web container, then started both in dependency order.

The -d flag means detached, as with docker run: the containers run in the background and your terminal returns. Without it, Compose stays in the foreground, prints the combined logs of all services with colored prefixes, and stops everything when you press Ctrl+C.

Check the state of the project, and test the site:

CONSOLE
$ docker compose ps
NAME            IMAGE          COMMAND                  SERVICE   CREATED         STATUS         PORTS
hello-cache-1   redis:alpine   "docker-entrypoint.sโ€ฆ"   cache     4 seconds ago   Up 2 seconds   6379/tcp
hello-web-1     nginx:alpine   "/docker-entrypoint.โ€ฆ"   web       4 seconds ago   Up 1 second    127.0.0.1:8080->80/tcp
$ curl -s http://127.0.0.1:8080
<h1>Hello from Compose</h1>

docker compose ps lists only this project's containers, and shows the service name (web, cache) next to the container name. Services can reach each other by service name, just like in a hand-made user-defined bridge network:

CONSOLE
$ docker compose exec web ping -c1 cache
PING cache (172.21.0.2): 56 data bytes
64 bytes from 172.21.0.2: seq=0 ttl=64 time=1.438 ms

You did not create a network, name anything, or pass --network. Compose did all of it.

What Compose creates

For every project Compose creates and labels:

Object Name pattern Notes
Containers <project>-<service>-<number> hello-web-1; the number matters when you scale a service
Network <project>_default One shared bridge network unless you define more
Named volumes <project>_<volume> Only if you declare volumes (see Networks and Volumes in Compose)

Everything carries labels such as com.docker.compose.project, which is how docker compose ps and down find "their" objects without touching anything else on your machine.

Stopping and removing

Compose has a deliberate difference between stopping and removing:

CONSOLE
$ docker compose stop
 Container hello-web-1 Stopping
 Container hello-web-1 Stopped
 Container hello-cache-1 Stopping
 Container hello-cache-1 Stopped
$ docker compose ps -a --format 'table {{.Name}}\t{{.Service}}\t{{.Status}}'
NAME            SERVICE   STATUS
hello-cache-1   cache     Exited (0) 1 second ago
hello-web-1     web       Exited (0) 1 second ago
$ docker compose start
 Container hello-cache-1 Starting
 Container hello-cache-1 Started
 Container hello-web-1 Starting
 Container hello-web-1 Started

stop keeps the containers (and any data in their writable layers); start brings them back. To delete the project, use down:

CONSOLE
$ docker compose down
 Container hello-web-1 Stopping
 Container hello-web-1 Stopped
 Container hello-web-1 Removing
 Container hello-web-1 Removed
 Container hello-cache-1 Stopping
 Container hello-cache-1 Stopped
 Container hello-cache-1 Removing
 Container hello-cache-1 Removed
 Network hello_default Removing
 Network hello_default Removed

down stops and removes the containers and the networks, in reverse dependency order. It does not delete named volumes unless you add -v, which is a safety feature: your database data survives a down and up cycle. The difference matters:

Command Containers Networks Named volumes
docker compose stop stopped, kept kept kept
docker compose down removed removed kept
docker compose down -v removed removed removed

docker compose down -v deletes the data in your named volumes, including database files. Use it deliberately, for example to reset a development database, never as a reflex.

Running up again

docker compose up is idempotent: it makes the running state match the file. If nothing changed, it does nothing:

CONSOLE
$ docker compose up -d
 Container hello-web-1 Running
 Container hello-cache-1 Running

If you edit the file (a new port, a new image tag, an environment variable), up -d recreates only the services whose configuration changed and leaves the rest alone. This is the everyday loop: edit compose.yaml, run docker compose up -d, done. More commands are in Compose Commands.

The compose file format

Compose uses the Compose Specification, an open format. A file has a few top-level keys:

Key Purpose
name Optional project name
services The containers to run (the only required key)
networks Custom networks
volumes Named volumes
configs, secrets Configuration and secrets, see Environment, Variables and Secrets

Each entry under services is a service: a recipe for one or more identical containers. Almost every docker run flag has a matching key (ports for -p, volumes for -v, environment for -e). The next lesson, Services in Compose, goes through them one by one.

File names

Compose looks for these names in the current folder, in this order: compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml. The first one is the modern, preferred name; the docker-compose.* names are supported for older projects. Use -f to point at any other file: docker compose -f deploy/prod.yaml up -d.

The obsolete version: key

Old tutorials start files with version: "3.8". In the current format that key is obsolete. Compose ignores it and prints a warning:

CONSOLE
$ docker compose -f compose.yaml config
time="2026-10-23T18:54:15+04:00" level=warning msg="/project/compose.yaml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion"
name: demo
services:
  web:
    image: nginx:alpine
    networks:
      default: null
networks:
  default:
    name: demo_default

Delete the line. The file format no longer has numbered versions; features are tied to the Compose release you have installed.

docker compose vs docker-compose

The original Compose was a separate Python program called docker-compose (version 1), now discontinued. The current Compose is a Go plugin of the Docker CLI, invoked as docker compose with a space. Docker Desktop includes it, and on Linux you install the docker-compose-plugin package. If an old guide says docker-compose up, run docker compose up instead; the options are almost identical. Check your version:

CONSOLE
$ docker compose version
Docker Compose version v5.5.1

Looking at the final configuration

docker compose config prints the file as Compose understands it: with defaults filled in, short syntax expanded, variables substituted and paths made absolute. It is the best way to debug a file that does not behave as you expect:

CONSOLE
$ docker compose config
name: hello
services:
  cache:
    image: redis:alpine
    networks:
      default: null
  web:
    depends_on:
      cache:
        condition: service_started
        required: true
    image: nginx:alpine
    networks:
      default: null
    ports:
      - mode: ingress
        host_ip: 127.0.0.1
        target: 80
        published: "8080"
        protocol: tcp
    volumes:
      - type: bind
        source: /home/you/hello/site
        target: /usr/share/nginx/html
        read_only: true
        bind: {}
networks:
  default:
    name: hello_default

Notice how - cache under depends_on became condition: service_started, and how the short port string "127.0.0.1:8080:80" expanded into host IP, target and published port. docker compose config --quiet only validates, printing nothing on success.

Projects and isolation

Everything Compose creates belongs to a project. The project name comes from, in order: the -p flag, the COMPOSE_PROJECT_NAME variable, the top-level name: in the file, or the name of the folder containing the file. Because names and networks are prefixed with the project, you can run the same file twice side by side:

CONSOLE
$ docker compose -p hello-copy up -d
 Container hello-copy-cache-1 Started
 Container hello-copy-web-1 Starting
Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint hello-copy-web-1 (45d22e23a156): Bind for 127.0.0.1:8080 failed: port is already allocated
$ docker compose ls
NAME           STATUS        CONFIG FILES
hello          running(2)    /home/you/hello/compose.yaml
hello-copy     running(1)    /home/you/hello/compose.yaml

Two projects with different names do not collide on container names or networks. The error above is not a Compose problem: the file publishes a fixed host port (8080) and only one container can own it. This is why serious projects either use different ports per copy, or do not publish ports for internal services at all. docker compose ls shows every project on the machine. Remove the extra one with docker compose -p hello-copy down.

When to use Compose (and when not)

Use Compose when:

  • You run several containers on one machine: local development, CI test environments, demos, small production deployments.
  • You want a reproducible setup in version control that any teammate can start with one command.
  • You want sensible defaults (a project network, service-name DNS) without writing them.

Look elsewhere when you need containers spread over many machines, automatic rescheduling after a node failure, or rolling updates across a cluster. That is the job of an orchestrator; see Why Orchestration?.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does docker compose up -d do on a project that is already running with an unchanged file?

    up is idempotent. It compares the file with the running state and only recreates services whose configuration changed.
  2. 2. What is the difference between docker compose stop and docker compose down?

    stop only stops the containers. down removes containers and networks. Named volumes are removed only with down -v.
  3. 3. How does the web service reach the cache service in the example?

    Compose puts all services on a default network where Docker's embedded DNS resolves service names. No links: or IPs are needed.
  4. 4. Why should you remove the version: key from a modern compose.yaml?

    The Compose Specification has no file versions any more. The key is ignored, and keeping it only creates a confusing warning.
  5. 5. Which command prints the fully resolved configuration, with defaults filled in and variables substituted?

    docker compose config renders the final model Compose will use, which makes it the standard tool for debugging a file. Add --quiet to only validate.

Summary

  • Compose describes a multi-container application in one compose.yaml and manages it with docker compose commands.
  • docker compose up -d creates the project network and containers in dependency order; running it again only applies changes.
  • Services find each other by service name on the automatic <project>_default network.
  • stop keeps containers, down removes containers and networks, down -v also removes named volumes.
  • Names are prefixed with the project name (from -p, name: or the folder), so several projects can coexist unless they publish the same host port.
  • The version: key is obsolete; use docker compose (with a space), not the old docker-compose.
  • docker compose config shows the resolved file and is the first tool to reach for when something looks wrong.

Next: Services in Compose