Docker Compose for Local FastAPI Stacks

WHY IT EXISTS: Before container orchestration, developers installed Postgres, Redis, and Python directly on their laptops. Version mismatches between machines caused bugs that only appeared in production, and onboarding a new engineer meant hours of README archaeology. Docker Compose was created to solve this by codifying every dependency, network rule, and environment variable into a single file that could spin up an entire environment with one command.

THE MENTAL MODEL: Think of Docker Compose as a conductor for a chamber orchestra. Each musician is a container; the composer score is the YAML file. The conductor does not play the instruments but ensures they start in the right order, can hear each other over the same network, and stop together when the piece ends. You are not managing servers; you are declaring a desired state and letting the tool reconcile reality with that declaration.

HOW IT WORKS: You write a docker-compose.yml file that lists services, their images or build contexts, ports, volumes, and environment variables. When you run docker compose up, the tool creates a default bridge network isolated to that project, then starts containers in dependency order based on depends_on directives. Your FastAPI container can reach Postgres by hostname because Compose injects DNS entries for each service name. Volume mounts let you edit code on your host and see changes immediately inside the container without rebuilding the image.

WHEN TO USE IT: Use Compose when you need three or more moving parts that must talk to each other locally, such as a FastAPI backend, a Postgres database, and a Redis cache. It shines during integration testing, when you want pytest to hit a real database instead of mocks, and when onboarding teammates who should not need to install anything beyond Docker Desktop. It is also the right choice when you need reproducible data seeding or migration scripts that run against the exact same database version used in production.

WHEN NOT TO USE IT: Do not use Docker Compose for production orchestration at scale. It lacks self-healing, rolling updates, and robust secret management out of the box. If your stack runs on multiple hosts, you need Kubernetes or a cloud container service instead. Also avoid Compose for single scripts with no dependencies; the overhead of building and networking a container is overkill when a local virtual environment and SQLite suffice.

ONE CANONICAL EXAMPLE: A typical FastAPI project defines two services in docker-compose.yml: web and db. The web service builds from a Dockerfile containing Python 3.11, mounts the local app directory as a volume, exposes port 8000, and sets DATABASE_URL to postgres://db:5432/app. The db service uses the official Postgres image, mounts a named volume for persistence, and initializes with environment variables for username and password. Running docker compose up brings up the stack; running docker compose down -v tears it down and wipes the named volume for a clean slate.