Write a docker-compose.yml

Spinning up a single container with docker run works for learning, but real-world applications rarely live in isolation. A web app needs a database, a cache, a message queue — and starting each by hand, in the right order, with the right networks and volumes, becomes tedious and error-prone. Docker Compose fixes this by letting you define your entire multi-container application in a single YAML file, so you can start everything with one command.

The problem this lesson solves

Without Docker Compose, you run separate docker run commands for each service, manually manage networks and volumes, and worry about startup order. A single typo in a port mapping or a missing environment variable can break your stack. Worse, sharing this setup with teammates means sharing shell scripts or copy-pasted commands. Docker Compose eliminates this chaos by codifying your application's infrastructure in a docker-compose.yml file.

Core concept / mental model

Think of a docker-compose.yml file as a blueprints for your application's microservices ecosystem. It declares:

• Services: Each container (e.g., web server, database, cache)
• Networks: How containers talk to each other
• Volumes: Persistent data storage
• Environment variables: Configuration per service

Docker Compose reads this file and does the heavy lifting: creates networks, starts containers in the right order, and wires everything together. The result is a self-documenting, reproducible setup that anyone on your team can run with docker-compose up.

How it works step by step

1. Install Docker Compose

Docker Desktop includes Compose. On Linux, you may need to install it separately:

sudo apt-get install docker-compose-plugin

Check the version:

docker compose version

Note: Newer versions use docker compose (no hyphen). The old docker-compose (hyphen) is deprecated. We use the plugin version throughout this lesson.

2. Understand the basic structure

A minimal docker-compose.yml file has a services block. Each service maps to a container image and its configuration.

version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
  db:
    image: postgres:13-alpine
    environment:
      POSTGRES_PASSWORD: example

3. Define services, networks, and volumes

• services: The list of containers you want to run.
• networks: Custom networks (optional — Compose creates a default network automatically).
• volumes: Named volumes for persistent data.

4. Start the stack

Place the file in a project folder (often the root of your codebase) and run:

docker compose up -d

The -d flag runs containers in the background (detached mode).

5. View running services

docker compose ps

6. Stop and remove everything

docker compose down

Hands-on walkthrough

Let's create a real example: a Node.js app talking to a Redis cache.

Project structure

myapp/
├── docker-compose.yml
├── app.js
├── package.json
└── Dockerfile

1. Create package.json

{
  "name": "myapp",
  "version": "1.0.0",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^4.18.0",
    "redis": "^4.5.0"
  }
}

2. Create app.js

const express = require('express');
const redis = require('redis');

const app = express();
const client = redis.createClient({ url: 'redis://redis:6379' });

client.on('error', err => console.error('Redis error', err));

app.get('/', async (req, res) => {
  await client.connect();
  const visits = await client.incr('visits');
  res.send(`Hello! You are visitor ${visits}`);
  await client.disconnect();
});

app.listen(3000, () => console.log('Server running on port 3000'));

3. Create Dockerfile

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["node", "app.js"]

4. Write docker-compose.yml

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - redis
    environment:
      - NODE_ENV=production
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

5. Run it

docker compose up --build -d

Check logs:

docker compose logs -f

Open http://localhost:3000 — you should see the visit counter increment each time.

6. Tear down

docker compose down

Compare options / when to choose what

When to choose Compose: You have 2–10 containers that need to work together, and you want a repeatable setup for local development, CI, or small deployments.

Troubleshooting & edge cases

Service name resolution

Containers can reach each other by service name (e.g., redis from app). If you use localhost, it won't work — use the service name.

Missing .env variables

Compose reads a .env file in the same directory automatically. If you set environment variables inline, make sure the syntax is correct:

environment:
  - DB_PASSWORD=secret

Port conflicts

If port 3000 is already in use, change the host port:

ports:
  - "3001:3000"

Startup order

depends_on only waits for the container to start, not for the service inside to be ready. For database readiness, use a health check or wait script.

redis:
  image: redis:7-alpine
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]
    interval: 5s
    timeout: 3s
    retries: 5

Build fails

• Check that the Dockerfile and app code are in the same directory as docker-compose.yml.
• Use docker compose build --no-cache to force a fresh build.

What you learned & what's next

You now know how to write a docker-compose.yml file to define a multi-container application, including services, networks, volumes, and environment variables. You practiced with a real Node.js + Redis example, learned when to choose Compose over raw Docker commands, and how to troubleshoot common issues like port conflicts and startup order.

Key learning objectives achieved: - Explain the core concept of Docker Compose as a blueprint for multi-container apps. - Complete a practical exercise that runs two services and makes them communicate.

Next lesson: In the next step, you'll learn about Docker Compose networking — how to customize networks, control DNS resolution, and connect services across multiple Compose files.

Safe orchestration!