Docker Compose: Running Multi-Container Apps Locally
Compose defines a multi-container application in one file. Learn services, networks, volumes, and the commands you use daily.
By Velloreth
The file
Compose defines a multi-container application in compose.yaml.
services:
api:
build: .
ports:
- "3000:3000"
environment:
DATABASE_URL: postgres://user:pass@db:5432/app
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: app
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user"]
interval: 5s
timeout: 5s
retries: 5
volumes:
pgdata:
Start it:
docker compose up
docker compose up -d # detached
docker compose up --build # rebuild first
Stop it:
docker compose down
docker compose down -v # also remove volumes
Services
A service is a container definition. Compose creates one container per service by default.
Build from a Dockerfile:
services:
api:
build:
context: .
dockerfile: Dockerfile
Use an image:
services:
db:
image: postgres:16-alpine
Ports:
ports:
- "3000:3000" # host:container
- "127.0.0.1:3000:3000" # bind to localhost only
Environment:
environment:
NODE_ENV: production
PORT: 3000
Or from a file:
env_file:
- .env
Command override:
command: npm run dev
Restart policy:
restart: unless-stopped
Networking
Compose creates a network and attaches every service to it. A service reaches another by its service name.
services:
api:
environment:
DATABASE_URL: postgres://user:pass@db:5432/app
The hostname db resolves to the db service’s container. This is why you do not need to know the container’s IP.
Custom networks:
services:
api:
networks:
- frontend
- backend
db:
networks:
- backend
networks:
frontend:
backend:
This isolates the database from the frontend, so only the API can reach it.
Volumes
Named volume:
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
Named volumes persist across docker compose down. They are removed only with -v.
Bind mount:
volumes:
- ./src:/app/src
The host path is mapped into the container. Edits appear immediately, which is why this is the standard development setup.
Read-only bind mount:
volumes:
- ./config:/app/config:ro
depends_on and healthchecks
depends_on controls start order, but it does not wait for the dependency to be ready.
depends_on:
- db
This starts db before api, but api may start before Postgres is accepting connections. The result is a connection error on startup.
The fix is a healthcheck plus a condition.
services:
api:
depends_on:
db:
condition: service_healthy
db:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user"]
interval: 5s
timeout: 5s
retries: 5
Now Compose waits for the healthcheck to pass before starting api.
This is the most common Compose mistake, and the healthcheck is the fix.
Development workflow
A typical development setup mounts the source and runs a watcher.
services:
api:
build: .
volumes:
- ./src:/app/src
- /app/node_modules # keep the container's node_modules
command: npm run dev
ports:
- "3000:3000"
The anonymous volume at /app/node_modules is important: it prevents the host’s node_modules from overwriting the container’s, which would break native modules built for a different platform.
Override file. compose.override.yaml is merged automatically, which is the place for development-only settings.
# compose.override.yaml
services:
api:
volumes:
- ./src:/app/src
command: npm run dev
The base file stays production-like, and the override adds development conveniences.
Useful commands
docker compose up -d
docker compose down
docker compose ps
docker compose logs -f api
docker compose exec api sh
docker compose build
docker compose pull
docker compose restart api
docker compose run --rm api npm test
docker compose config # validate and print the merged config
docker compose config is the fastest way to check that the file is valid and to see the merged result of the base and override files.
Compose versus Kubernetes
Compose runs containers on a single host. It is aimed at local development and simple deployments.
Kubernetes orchestrates containers across many hosts, with scaling, rolling updates, self-healing, and service discovery. It is aimed at production at scale.
The honest assessment: Compose is the right tool for development and for a small deployment on one machine. Reaching for Kubernetes for a single-host application adds a large amount of complexity for no benefit.
Common mistakes
A connection error on startup. depends_on started the dependency but did not wait for it to be ready. Add a healthcheck and condition: service_healthy.
Data lost after down. The volume was anonymous, or -v was used. Use a named volume and avoid -v unless you intend to delete the data.
The host’s node_modules overwriting the container’s. A bind mount of the whole project copies the host’s node_modules over the container’s, which breaks native modules built for a different platform. Add an anonymous volume at /app/node_modules.
A service not reachable by name. The services are on different networks, or the name is misspelled. Check with docker compose config and docker network inspect.
Changes not taking effect. The image was not rebuilt. Use docker compose up --build.
A port conflict. Two services map the same host port. Change one, or remove the host mapping for a service that only needs to be reachable internally.
Environment variables not set. The env_file path is relative to the Compose file, not the working directory, which is a common surprise.
Compose profiles
Profiles let you start a subset of services.
services:
api:
build: .
debug:
image: busybox
profiles: ["debug"]
docker compose up # starts api only
docker compose --profile debug up # starts api and debug
This is useful for optional services: a database admin tool, a mail catcher, or a profiler that is not needed every day.
Compose in CI
Compose is useful in a continuous integration pipeline, because it can start the dependencies a test needs without a separate service configuration. A test job that needs Postgres and Redis can start them with Compose, run the suite, and tear them down, all within the job. The alternative is to configure the services in the CI platform’s own syntax, which duplicates the local setup and drifts from it over time. Using the same Compose file in CI and locally means the test environment matches the development environment, which is the point of the dev/prod parity idea. The one adjustment is usually to wait for the healthchecks to pass before running the tests, which the --wait flag does.
Migrating from Compose to production
Compose is a reasonable deployment tool for a single host, and many small applications run that way for years. The pattern is to build the images in CI, push them to a registry, and have the host pull and restart. A reverse proxy in front handles TLS and routing. The limits appear when you need more than one host: Compose has no scheduler, so it cannot place a container on the machine with capacity, and it has no self-healing across hosts. At that point the migration is to an orchestrator, and the Compose file is a useful starting point because it already describes the services, their dependencies, and their configuration. The concepts transfer: a service becomes a Deployment, a volume becomes a PersistentVolumeClaim, and an environment block becomes a ConfigMap and a Secret.
Practical guidance
- Use service names as hostnames.
- Add healthchecks and use
condition: service_healthy. - Use named volumes for data that must persist.
- Use bind mounts for development.
- Keep
node_modulesin the container with an anonymous volume. - Use
compose.override.yamlfor development settings. - Run
docker compose configto validate. - Use
down -vonly when you want to delete the data.
For the related guides, see docker-basics-guide and dockerfile-best-practices. For the broader context, environment-variables-explained and kubernetes-basics.
Quotable summary
Compose defines services, networks, and volumes in a single YAML file and starts them with one command, and services on the same Compose network reach each other by service name, which acts as a hostname. depends_on controls start order but does not wait for a service to be ready, so a healthcheck with condition: service_healthy is needed to avoid connection errors on startup. Named volumes persist data across docker compose down, while anonymous ones are removed, and down -v deletes the named volumes too. Compose is for local development and simple single-host deployments, while orchestration at scale needs Kubernetes. Use compose.override.yaml for development-only settings and docker compose config to validate the merged result.