Docker Compose Quickstart

This tutorial aims to introduce fundamental concepts of Docker Compose by guiding you through the development of a basic Python web application.

Using the Flask framework, the application features a hit counter in Redis, providing a practical example of how Docker Compose can be applied in web development scenarios. The concepts demonstrated here should be understandable even if you're not familiar with Python.

Prerequisites

Make sure you have:

• Installed the latest version of Docker Compose
• A basic understanding of Docker concepts and how Docker works

Step 1: Set up the project

1. Create a directory for the project:

   $ mkdir compose-demo
   $ cd compose-demo
   

2. Create app.py in your project directory and add the following:

   import os
   import redis
   from flask import Flask
   
   app = Flask(__name__)
   cache = redis.Redis(
       host=os.getenv("REDIS_HOST", "redis"),
       port=int(os.getenv("REDIS_PORT", "6379")),
   )
   
   @app.route("/")
   def hello():
       count = cache.incr("hits")
       return f"Hello from Docker! I have been seen {count} time(s).\n"

   The app reads its Redis connection details from environment variables, with sensible defaults so it works out of the box.

3. Create requirements.txt in your project directory and add the following:

   flask
   redis

4. Create a Dockerfile:

   # syntax=docker/dockerfile:1
   FROM python:3.12-alpine  # Builds an image with the Python 3.12 image
   WORKDIR /code  # Sets the working directory to `/code`
   ENV FLASK_APP=app.py  # Sets environment variables used by the `flask` command
   ENV FLASK_RUN_HOST=0.0.0.0
   RUN apk add --no-cache gcc musl-dev linux-headers  # Installs `gcc` and other dependencies
   COPY requirements.txt .  # Copies `requirements.txt`
   RUN pip install -r requirements.txt  # Installs the Python dependencies
   COPY . .  # Copies the current directory `.` in the project to the workdir `.` in the image
   EXPOSE 5000
   CMD ["flask", "run", "--debug"]  # Sets the default command for the container to `flask run --debug`

   Important

   Make sure the file is named Dockerfile with no extension. Some editors add .txt automatically, which causes the build to fail.

   For more information on how to write Dockerfiles, see the Dockerfile reference.

5. Create a .env file to hold configuration values:

   APP_PORT=8000
   REDIS_HOST=redis
   REDIS_PORT=6379

   Compose automatically reads .env and makes these values available for interpolation in your compose.yaml. For this example the gains are modest, but in practice, keeping configuration out of the Compose file makes it easier to:

   • Change values across environments without editing YAML
   • Avoid committing secrets to version control
   • Reuse values across multiple services

6. Create a .dockerignore file to keep unnecessary files out of your build context:

   .env
   *.pyc
   __pycache__
   redis-data

   Docker sends everything in your project directory to the daemon when it builds an image. Without .dockerignore, that includes your .env file (which may contain secrets) and any cached Python bytecode. Excluding them keeps builds fast and avoids accidentally baking sensitive values into an image layer.

Step 2: Define and start your services

Compose simplifies the control of your entire application stack, making it easy to manage services, networks, and volumes in a single YAML configuration file.

1. Create compose.yaml in your project directory and paste the following:

   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
   
     redis:
       image: redis:alpine

   This Compose file defines two services:

   • The web service uses an image that's built from the Dockerfile in the current directory. It maps port 8000 on the host to port 5000 on the container where Flask listens by default.

   • The redis service uses a public Redis image pulled from the Docker Hub registry.

   For more information on the compose.yaml file, see How Compose works.

2. Start up your application:

   $ docker compose up
   

   With a single command, you create and start all the services from your configuration file. Compose builds your web image, pulls the Redis image, and starts both containers.

3. Open http://localhost:8000. You should see:

   Hello from Docker! I have been seen 1 time(s).

   Refresh the page — the counter increments on each visit.

   This minimal setup works, but it has two problems you'll fix in the next steps:

   • Startup race: web starts at the same time as redis. If Redis isn't ready yet, the Flask app fails to connect and crashes.
   • No persistence: If you run docker compose down followed by docker compose up, the counter resets to zero. docker compose down removes the containers, and with them any data written to the container's writable layer. docker compose stop preserves the containers so data survives, but you can't rely on that in production where containers are regularly replaced.

4. Stop the stack before moving on:

   $ docker compose down
   

Step 3: Fix the startup race with health checks

To fix the startup race, Compose needs to wait until redis is confirmed healthy before starting web.

1. Update compose.yaml:

   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy
   
     redis:
       image: redis:alpine
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s

   The healthcheck block tells Compose how to test whether Redis is ready:

   • test is the command Compose runs inside the container to check its health. redis-cli ping connects to Redis and expects a PONG response — if it gets one, the container is healthy.
   • start_period gives Redis 10 seconds to initialize before health checks begin. Any failures during this window don't count toward the retry limit.
   • interval runs the check every 5 seconds after the start period has elapsed.
   • timeout gives each check 3 seconds to respond before treating it as a failure.
   • retries sets how many consecutive failures are allowed before Compose marks the container as unhealthy. With interval: 5s and retries: 5, Compose will wait up to 25 seconds before giving up.

2. Start the stack to confirm the ordering is fixed:

   $ docker compose up
   

   You should see something similar to:

   [+] Running 2/2
   ✔ Container compose-demo-redis-1  Healthy                       0.0s

3. Open http://localhost:8000 to confirm the app is still working, then stop the stack before moving on:

   $ docker compose down
   

Step 4: Enable Compose Watch for live updates

Without Compose Watch, every code change requires you to stop the stack, rebuild the image, and restart the containers. Compose Watch eliminates that cycle by automatically syncing changes into your running container as you save files.

1. Update compose.yaml to add the develop.watch block to the web service:

   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy
       develop:
         watch:
           - action: sync+restart
             path: .
             target: /code
           - action: rebuild
             path: requirements.txt
   
     redis:
       image: redis:alpine
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s

   The watch block defines two rules:

   • The sync+restart action watches your project directory (.) on the host. When a file changes, Compose copies any changed files into /code inside the running container, then restarts the container. Because the container restarts with the updated files already in place, Flask starts up reading the new code directly — no manual rebuild or restart needed.
   • The rebuild action on requirements.txt triggers a full image rebuild whenever you add a new dependency, since installing packages requires rebuilding the image, not just syncing files.

2. Start the stack with Watch enabled:

   $ docker compose up --watch
   

3. Make a live change. Open app.py and update the greeting:

   return f"Hello from Compose Watch! I have been seen {count} time(s).\n"

4. Save the file. Compose Watch detects the change and syncs it immediately:

   Syncing service "web" after changes were detected

5. Refresh http://localhost:8000. The updated greeting appears without any restart and the counter should still be incrementing.

6. Stop the stack before moving on:

   $ docker compose down
   

   For more information on how Compose Watch works, see Use Compose Watch.

Step 5: Persist data with named volumes

Each time you stop and restart the stack the visit counter resets to zero. Redis data lives inside the container, so it disappears when the container is removed. A named volume fixes this by storing the data on the host, outside the container lifecycle.

1. Update compose.yaml:

   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy
       develop:
         watch:
           - action: sync+restart
             path: .
             target: /code
           - action: rebuild
             path: requirements.txt
   
     redis:
       image: redis:alpine
       volumes:
         - redis-data:/data
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s
   
   volumes:
     redis-data:

   The redis-data:/data entry under redis.volumes mounts the named volume at /data, the path where Redis writes its data files. The top-level volumes key registers it with Docker so it persists between compose down and compose up cycles.

2. Start the stack with docker compose up --watch and refresh http://localhost:8000 a few times to build up a count.

3. Tear down the stack with docker compose down and then bring it back up again with docker compose up --watch.

4. Open http://localhost:8000 — the counter continues from where it left off.

5. Now reset the counter with docker compose down -v.

   The -v flag removes named volumes along with the containers. Use this intentionally — it permanently deletes the stored data.

Step 6: Structure your project with multiple Compose files

As applications grow, a single compose.yaml becomes harder to maintain. The include top-level element lets you split services across multiple files while keeping them part of the same application.

This is especially useful when different teams own different parts of the stack, or when you want to reuse infrastructure definitions across projects.

1. Create a new file in your project directory called infra.yaml and move the Redis service and volume into it:

    services:
     redis:
       image: redis:alpine
       volumes:
         - redis-data:/data
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s
   
   volumes:
     redis-data:

2. Update compose.yaml to include infra.yaml:

   include:
      - path: ./infra.yaml
   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy
       develop:
         watch:
           - action: sync+restart
             path: .
             target: /code
           - action: rebuild
             path: requirements.txt

3. Run the application to confirm everything still works:

   $ docker compose up --watch
   

   Compose merges both files at startup. The web service can still reference redis by name because all included services share the same default network.

   This is a simplified example, but it demonstrates the basic principle of include and how it can make it easier to modularize complex applications into sub-Compose files. For more information on include and working with multiple Compose files, see Working with multiple Compose files.

4. Stop the stack before moving on:

   $ docker compose down
   

Step 7: Inspect and debug your running stack

With a fully configured stack, you can observe what's happening inside your containers without stopping anything. This step covers the core commands for inspecting the resolved configuration, streaming logs, and running commands inside a running container.

Before starting the stack, verify that Compose has resolved your .env variables and merged all files correctly:

$ docker compose config

docker compose config doesn't require the stack to be running — it works purely from your files. A few things worth noting in the output:

• ${APP_PORT}, ${REDIS_HOST}, and ${REDIS_PORT} have all been replaced with the values from your .env file.
• Short-form port notation ("8000:5000") is expanded into its canonical fields (target, published, protocol).
• The default network and volume names are made explicit, prefixed with the project name compose-demo.
• The output is the fully resolved configuration, with any files brought in via include merged into a single view.

Use docker compose config any time you want to confirm what Compose will actually apply, especially when debugging variable substitution or working with multiple Compose files.

Now start the stack in detached mode so the terminal stays free for the commands that follow:

$ docker compose up -d

Stream logs from all services

$ docker compose logs -f

The -f flag follows the log stream in real time, interleaving output from both containers with color-coded service name prefixes. Refresh http://localhost:8000 a few times and watch the Flask request logs appear. To follow logs for a single service, pass its name:

$ docker compose logs -f web

Press Ctrl+C to stop following logs. The containers keep running.

Run commands inside a running container

docker compose exec runs a command inside an already-running container without starting a new one. This is the primary tool for live debugging.

Verify environment variables are set correctly

$ docker compose exec web env | grep REDIS

REDIS_HOST=redis
REDIS_PORT=6379

Test that the web container can reach Redis using the service name as the hostname

$ docker compose exec web python -c "import redis; r = redis.Redis(host='redis'); print(r.ping())"

True

This uses the same redis library your app uses, so a True response confirms that service discovery, networking, and the Redis connection are all working end to end.

Inspect the live value of the hit counter in Redis

$ docker compose exec redis redis-cli GET hits

Where to go next

• Explore the full list of Compose commands
• Explore the Compose file reference
• Check out the Learning Docker Compose video on LinkedIn Learning
• Learn how to set environment variables in Compose
• Learn how to package and distribute your Compose app