Get started with Docker Compose

Define a web application, PostgreSQL, and Redis in Compose, then understand startup order, service discovery, persistent volumes, and operational checks.

Guance Editorial Team 2026-10-27 3 min read Updated 2026-10-27

Best practices

Illustration of application infrastructure and operations

Docker Compose defines a multi-container application in a compose.yaml file. Services, networks, and volumes become a repeatable configuration that docker compose up can create and start.

It removes much of the manual work of launching containers and wiring them together. A repository still needs its application code, Dockerfile, configuration, credentials, and initialization steps before “clone and run” is realistic.

Check that Compose is installed

docker compose version

Use a supported Docker Desktop installation or the Compose plugin for your Docker Engine environment. The current command is docker compose; the older Python-based Compose v1 used docker-compose.

Define the services

This example connects an application on port 8080 to PostgreSQL and Redis:

services:
  web:
    build: .
    ports: ["127.0.0.1:8080:8080"]
    depends_on: [db, cache]
    environment:
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}@db:5432/app
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD}
    volumes: ["pgdata:/var/lib/postgresql/data"]
  cache:
    image: redis:7
volumes:
  pgdata:

This is a scaffold. Supply a Dockerfile and an application that listens on port 8080 on a container-reachable interface, and implement retries for database connections. Redis is available as cache:6379; the application's cache configuration depends on its framework.

Set POSTGRES_PASSWORD in the controlled development environment. The example inserts it directly into a URL: characters with URL meaning must be percent-encoded in the URL without changing the actual database password. In a fuller setup, use separate connection fields or construct the URL correctly. Do not commit credentials; evaluate file-based or external secrets for deployment.

Run and inspect the application

docker compose up -d
docker compose ps
docker compose logs -f web
docker compose exec web sh

The last command requires an image containing sh. A “running” container is not proof that its application is ready: request the endpoint and check database connection logs.

To stop and remove the project's containers and ordinary project networks:

docker compose down
# For disposable test data only:
# docker compose down -v

Ordinary down preserves named volumes. Adding -v removes declared non-external named volumes and attached anonymous volumes, so it can delete the example database data. External resources are not removed by Compose.

Use service names for communication

Services sharing a Compose network can discover each other by service name. The application connects to db:5432, not a remembered container IP. It uses the database's container port, not a host-published port.

The web port is bound to host loopback for local development. The database and cache are reachable inside the project network without being published to the host.

Frequently asked questions

Does depends_on wait for PostgreSQL to accept connections?

The short form orders startup but does not wait for readiness. A dependency with a health check and condition: service_healthy can gate initial startup. The application still needs to handle later database restarts and temporary failures; startup health is not a lasting availability guarantee.

Can Compose run production services?

It can suit a managed single-host deployment when backups, updates, monitoring, and recovery are planned. Multi-host scheduling and high availability require additional design; Swarm or Kubernetes may be appropriate depending on the requirements.

Are compose.yaml and docker-compose.yml different formats?

Both filenames are recognized. Prefer the current Compose specification and command rather than assuming an old v1 tutorial applies unchanged.

References

The scaffold has not been deployed as a complete application; validate it with your image, credentials, and storage setup.