Docker Compose for Multi-Container Apps

Why it exists

Modern applications are rarely a single process; they depend on other services like databases, caches, or message queues. Manually running docker run for each component, configuring networks, and managing startup order is tedious and error-prone. Docker Compose was created to solve this coordination problem for local development environments.

The mental model

Think of Docker Compose as a blueprint for your entire local development stack. You write a single YAML file (docker-compose.yml) that describes all the services (your Node.js app, a PostgreSQL database), the networks they need to communicate, and the volumes they use for persistent data. One command, docker-compose up, brings the whole stack to life as an isolated, reproducible environment.

How it works

You create a docker-compose.yml file in your project root. Inside, you define services. Each service gets a name, like app for your Node.js server and db for PostgreSQL. For the app service, you can tell Compose to build it from a local Dockerfile. For the db service, you can pull a public image like postgres:14. Compose automatically creates a shared network, allowing services to find each other using their service names as hostnames. Your application code connects to the database using the hostname db, not localhost.

When to use it

Use Docker Compose for managing multi-service applications in development and testing. It's perfect for spinning up your application along with all its dependencies (databases, message queues, caches) with a single command. This ensures every developer on a team has an identical, reproducible environment, eliminating "works on my machine" problems.

When not to use it

While you can use Docker Compose for simple, single-host production deployments, it is not a full-fledged container orchestrator. For production environments requiring high availability, auto-scaling, and complex multi-node cluster management, tools like Kubernetes or Amazon ECS are the appropriate choice. Compose lacks the features for managing a resilient, distributed system.

One canonical example

A typical setup involves a Node.js Express app and a PostgreSQL database. The docker-compose.yml defines two services: app and postgresdb. The app service is built using a Dockerfile in the project. The postgresdb service uses the official postgres image from Docker Hub. The Node app's database configuration is updated to read the host from an environment variable, which is set to postgresdb (the service name), not localhost.