Docker Compose lets you define an application’s containers, networks, ports, and storage in one YAML file. This guide uses Compose to run a small Flask web app with Redis, then explains how to start the services, preserve their data, and inspect common problems.
Compose file defines services
A Compose project groups related services. Each service normally runs in its own container. Docker says Compose can manage an application’s services, networks, and volumes from one configuration file, which makes it useful for development, testing, and small self-hosted projects (Docker Compose documentation).
First, install Docker Desktop on Windows, macOS, or Linux, or install the Compose plugin alongside Docker Engine on Linux. Docker recommends Docker Desktop as the easiest option because it includes Docker Engine, the Docker command-line tool, and Compose (Docker Compose installation documentation).
Create a directory named compose-demo. Inside it, add a file named app.py:
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.get("/")
def home():
count = cache.incr("hits")
return f"This page has been viewed {count} time(s).\n"
The program connects to a service named redis. Compose gives services a shared network by default, so a container can reach another service by its service name instead of an IP address (Docker networking documentation).
Add a requirements.txt file:
flask
redis
Then create a file named Dockerfile:
FROM python:3.12-alpine
WORKDIR /code
ENV FLASK_APP=app.py
ENV FLASK_RUN_HOST=0.0.0.0
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["flask", "run", "--debug"]
Start the Flask Redis stack
With the application files in place, create compose.yaml to define the two services:
services:
web:
build: .
ports:
- "8000:5000"
environment:
REDIS_HOST: redis
REDIS_PORT: 6379
depends_on:
redis:
condition: service_healthy
redis:
image: redis:alpine
volumes:
- redis-data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 5
volumes:
redis-data:
The web service builds from the Dockerfile. The redis service uses the Redis image. The port mapping sends traffic from port 8000 on the computer to port 5000 inside the web container. Docker’s Compose quickstart uses the same general pattern: one application service, one Redis service, and a YAML file that starts both together (Docker Compose Quickstart).
From the directory containing compose.yaml, start the project:
docker compose up --build
The --build option rebuilds the web image when needed. Open http://localhost:8000 in a browser. Each refresh should increase the counter stored in Redis. To keep the services running while you use the terminal, add --detach:
docker compose up --build --detach
Persistent storage prevents resets
The running containers handle the application, while the named volume handles Redis data. Without that volume, data written only to a container’s writable layer can disappear when the container is removed. The redis-data volume stores Redis data outside the container, so the counter can survive normal container replacement.
Stop and remove the containers with:
docker compose down
Because the volume is named separately, this command does not remove it by default. To remove the stored data as well, use:
docker compose down --volumes
Keep sensitive values out of the Compose file. Docker’s documentation warns that environment variables are not the right way to pass passwords or API keys into containers and recommends using secrets instead (Docker environment variable guidance).
Health checks control startup
The Compose file also controls the order in which the services become available. A container can be running before the application inside it is ready to accept connections. The Redis health check sends a ping command at regular intervals, while the depends_on condition tells Compose to wait for Redis to become healthy before starting the web service.
This avoids a common startup race. Without the health check, the web application could start first, try to connect to Redis, and exit before Redis was ready. A health check does not repair a failed service, but it gives Compose a better signal than container status alone.
Inspect failures without guessing
After the stack starts, use these commands to examine its current state:
docker compose ps
docker compose logs web
docker compose logs redis
docker compose config
docker compose ps shows service status. The log commands reveal application and database errors. docker compose config renders the resolved configuration, making it useful for checking indentation, port mappings, and substituted values. Docker documents docker compose logs, docker compose exec, and docker compose config as core inspection tools for running stacks (Docker Compose Quickstart).
If port 8000 is already in use, change only the host-side number, such as 8001:5000, and visit http://localhost:8001. If the web container cannot connect to Redis, confirm that the hostname is redis, not localhost. Inside a container, localhost refers to that same container.
References
Docker. (n.d.). Docker Compose. Retrieved November 15, 2026, from https://docs.docker.com/compose/
Docker. (n.d.). Docker Compose Quickstart. Retrieved November 15, 2026, from https://docs.docker.com/compose/gettingstarted/
Docker. (n.d.). Overview of installing Docker Compose. Retrieved November 15, 2026, from https://docs.docker.com/compose/install/
Docker. (n.d.). Networking in Compose. Retrieved November 15, 2026, from https://docs.docker.com/compose/how-tos/networking/
Docker. (n.d.). Set environment variables within your container’s environment. Retrieved November 15, 2026, from https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/
