Compose Basics
This page introduces the tool, and one simple example, before the next page grows it into a full stack.
What Docker Compose Is
Docker Compose lets you describe every container your project needs — images, ports, volumes, environment variables, networks — in a single YAML file. One command starts everything; one command stops everything.
Recall Container Networking from the last section: you manually ran docker network create, then attached two containers to it with --network. Compose does exactly that for you, automatically, for every service in the file.
docker compose, Not docker-compose
You may see two different commands in older tutorials:
docker-compose(with a hyphen) — the original, standalone tool. It still works on many machines, but it is the legacy version.docker compose(a space, as a subcommand ofdockeritself) — Compose v2, built directly into the Docker CLI. This is the current version, and the one this guide uses.
Check which you have:
docker compose versionIf that fails, your Docker installation may only have the older standalone tool. Docker Desktop includes Compose v2 by default.
Your First compose.yaml
Create a file named compose.yaml in your Next.js project’s root folder — the same folder as your Dockerfile:
services:
web:
build: .
ports:
- "3000:3000"services:— the list of containers this project needs. There is one so far:web.build: .— there is no ready-made image forwebyet. This tells Compose to build one itself, using theDockerfilein this folder (.) — the same action as runningdocker build .by hand, from Building Images.ports:— the same idea as-p 3000:3000on the command line.
Compose does not replace the Dockerfile — you still need both. The Dockerfile says how to build the image. compose.yaml says how to run it, and points build: . at the Dockerfile to do so.
Running It
Start it
docker compose upThis builds the image (if needed) and starts the container, with logs printed straight to your terminal.
Start it in the background
docker compose up -d-d runs detached, exactly like docker run -d did in Foundation.
See what is running
docker compose psView logs
docker compose logs -f webStop everything
docker compose downThis stops and removes the containers Compose created — but not the image, and not any named volumes, unless you add -v.
docker compose down -v also deletes named volumes. Do not add -v if you have real data you want to keep — the next pages will make this distinction matter.
Quick Check
- Can you explain the difference between
docker-composeanddocker compose? - What does
build: .do inside a Compose service? - Can you explain what
docker compose down -vremoves that plaindocker compose downdoes not?
Next → The Full Stack