Docker Compose for Multi-Service Apps

Run an API, database, and cache together with Compose: services, networks, volumes, health checks, and environment files.

Est. 30 min Updated Suggest a fix
// Part 01 — A local system, not a single process

Describe Services Together

A backend feature often needs more than an API process. A delivery-status service might need a PostgreSQL database for durable orders and Redis for short-lived cache or coordination. Docker Compose reads a YAML file describing services, networks, volumes, and configuration, then manages the local application as a group. It provides a repeatable development environment; it is not automatically a production orchestrator or a replacement for a production backup and security plan.

Each service is created from an image or a build context. Compose creates a private network by default so service names can be used as DNS names between containers. In the example, the API can connect to PostgreSQL at host db and Redis at host cache; those names are not generally reachable from the developer's laptop. Only the API's port is published to the host. The database and cache remain internal unless an explicit port mapping is added for local tools.

Compose conceptRole in the exampleWhat it does not guarantee
ServiceAPI, PostgreSQL, or Redis container definitionApplication-level correctness
NetworkPrivate service-to-service name resolutionProtection from a compromised host
VolumePersistent database files across container replacementA backup or disaster recovery plan
Health checkReports whether a configured command succeedsThat every business operation works
💡 Note
Compose is excellent for local integration and demos. Production environments may use managed databases, a container platform, or another deployment system with separately managed secrets, availability, and backups.
// Part 02 — The YAML file

Wire an API, PostgreSQL, and Redis

Save the following as compose.yaml beside the API's Dockerfile and application source. The API is built locally; database and cache services use their upstream images. The example uses Compose variable substitution for credentials and database settings, reads values from an environment file, and checks service health before starting the API. Review the current image documentation and pin a tested version or digest for shared and release environments; do not assume a floating tag is reproducible.

compose.yaml
yaml
services:
  app:
    build: .
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      REDIS_URL: redis://cache:6379/0
    ports:
      - "127.0.0.1:8000:8000"
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=3)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres:latest
    env_file:
      - .env
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

  cache:
    image: redis:latest
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  postgres-data:

The database URL uses Compose interpolation from the project-level .env file. The health-check command uses $$ to pass a dollar sign through Compose so the container shell expands the value at runtime. The sample FastAPI health route does not create database or cache clients; a real API must read these URLs, use appropriate drivers, and define its own readiness behavior. For services that support separate user/password/database variables, passing those values separately can avoid embedding reserved URL characters without encoding. Check the framework's database URL parsing rules.

⚠️ Important
Replace latest with a deliberate, tested version or digest before a team relies on the setup. Database images can change behavior across releases, and a floating tag makes repeated builds less predictable.
// Part 03 — Environment configuration

Keep Local Settings Out of Source Control

Compose can read a project-level .env file for variable interpolation, and env_file passes environment values into a service container. Those are related but different uses. Add the real local file to .gitignore; provide teammates a safe template containing variable names and non-secret examples. Values in a file are still plain text on the machine, so protect file permissions and do not treat a checked-in template or an ignored file as a production secret manager.

.env.example
bash
POSTGRES_USER=appuser
POSTGRES_PASSWORD=replace-with-a-local-only-password
POSTGRES_DB=delivery_dev
.gitignore
bash
.env
.env.*.local

Copy the example to your local .env and set a unique development password that is not used anywhere else. Avoid committing a password, token, or real customer data. In CI and production, inject sensitive values via the platform's secret facility with access limited to the workload that needs them. Rotate exposed values rather than simply deleting a line from the latest commit.

bash
cp .env.example .env
# Edit .env with a unique, local-only value before starting services.
🎯 Pro Tip
Keep configuration names consistent across local, test, and production environments, but use separate values and access controls. Never copy production database credentials into a developer's Compose file.
// Part 04 — Start and inspect

Bring the Stack Up in a Controlled Way

Before starting all services, render the Compose configuration and inspect it for accidental secrets, incorrect ports, or an unexpected build context. Then build and start the application. up creates or reuses services, while ps and logs help inspect state. The first database startup initializes its volume; later starts reuse that volume. Do not remove volumes casually if they contain data you need.

bash
docker compose config
docker compose up --build -d
docker compose ps
docker compose logs --tail 60 app db cache
curl http://localhost:8000/health

Service startup order and service readiness are different. Compose's depends_on can establish ordering; with a health condition, Compose waits for the dependency's health check before creating the dependent service. The application still needs robust connection handling because a database can become unavailable later. Health checks should test a meaningful readiness condition without being excessively expensive or exposing sensitive data.

  1. Validate the rendered configuration and confirm values are local-only.
  2. Start the stack and inspect service state and logs.
  3. Wait for healthy dependencies, then verify the API endpoint.
  4. Test how the API behaves when a dependency is stopped and restored.
// Part 05 — Dependencies and health

A Running Container Is Not Necessarily Ready

A process can exist while its service is still initializing. A database may need to create its first data directory, apply internal setup, and accept connections before an API can use it. A Redis process may also be running but not yet responding as expected. Health checks make readiness observable by executing a command inside the container. Compose's health-conditioned dependency helps with initial startup, but the application must still retry transient connection failures and report useful errors.

Choose check intervals and timeouts based on service startup and impact. A check that is too strict may mark a slow but healthy service unhealthy; one that only checks that a process exists may miss a real outage. For the API, checking its HTTP health endpoint is useful only if that endpoint reflects the readiness contract you intend. Keep liveness (process can continue) and readiness (safe to receive work) distinct when the platform supports both.

SignalQuestionExample
Container stateIs the main process running?docker compose ps
Health statusDid the configured check succeed?Compose health check result
ReadinessCan this service handle the intended work?Application-level health endpoint
Dependency recoveryCan the app reconnect after failure?Controlled stop and restart test
📌 Real World Example
If PostgreSQL restarts during a practice run, the API should log a clear connection error and recover according to its retry policy. Compose startup ordering does not replace runtime resilience.
// Part 06 — Networks and persistence

Know Which Data Survives and Who Can Connect

Compose creates a network so services can resolve one another by service name. Inside the network, the app uses db:5432 and cache:6379; localhost inside the app container refers to that same container, not the database. Publishing a host port is only needed for a client outside the Compose network. The sample publishes the API on the developer's loopback interface and does not publish database or cache ports.

The named postgres-data volume keeps database files when the database container is replaced. Removing containers does not necessarily remove named volumes, but docker compose down -v removes project volumes and can destroy local data. Back up state before cleanup, and test that a backup can be restored. For important environments, use a database service with an explicit backup, encryption, retention, and recovery plan.

bash
# Stop and remove containers and network; keep named volumes.
docker compose down

# List volumes so you understand what contains persistent state.
docker volume ls

# Inspect the database volume instead of deleting it blindly.
docker volume inspect <project>_postgres-data
⚠️ Important
Treat docker compose down -v as a destructive data operation. Use it only when you intentionally want to delete the database volume, have confirmed the target project, and do not need the stored data.
// Part 07 — Development workflow

Make Local Changes and Rebuild Deliberately

After editing the API or Compose configuration, recreate only what needs to change and inspect the resulting services. A source change for an image-built service requires a rebuild; an environment or port change may require container recreation. Use docker compose logs -f app to follow logs while testing and stop following with Ctrl+C (this stops log viewing, not necessarily the service). Keep app logs on standard output and error so Compose can collect them.

bash
docker compose up --build -d app
docker compose ps
docker compose logs -f app
# In another terminal:
curl http://localhost:8000/health

Local Compose files should stay understandable to the team. Avoid hard-coding machine-specific absolute paths, production endpoints, or secrets. If developer-specific overrides are needed, document how to use them and keep private override files out of version control. Review the resolved configuration before sharing logs or config output, because rendered settings can contain credentials.

// Part 08 — Pitfalls

Common Mistakes

Using localhost as the database hostname from the app container

Why: localhost refers to the current container, not its Compose peer.

Fix: Connect using the Compose service name, such as db.

Starting the API as soon as the database container exists

Why: A running process may not yet accept database connections.

Fix: Use health checks for startup and implement runtime retries in the application.

Assuming depends_on makes the app resilient

Why: It controls startup conditions, not later outages or reconnection behavior.

Fix: Handle dependency failures in the app and test recovery.

Deleting volumes to fix every local problem

Why: The volume may contain the only copy of useful data.

Fix: Inspect state and back up first; remove volumes only when data loss is intended.

// Part 09 — Practice

Run and Diagnose a Three-Service Stack

Practice

Exercise the lifecycle, not only startup

  1. Create the Compose file, local .env, and .gitignore, then inspect docker compose config before starting anything.
  2. Start the app, PostgreSQL, and Redis; inspect health and call the API endpoint from the host.
  3. Confirm the app uses db and cache as internal hostnames and that only the API port is published.
  4. Stop the database container, observe app logs, then restore it and evaluate whether the app recovers.
  5. Run docker compose down and bring the stack back up; check that the database volume still contains its data.
  6. Write a short note describing how production secrets, database backups, and service health would differ from this local setup.

Hint: Do not use production credentials or data. Check the resolved Compose config carefully because it may display environment values.

🎯 Key Takeaways

  • ✓Compose describes a group of related services, networks, volumes, and configuration in one file.
  • ✓Containers on the Compose network connect to each other by service name, not localhost.
  • ✓depends_on controls startup dependencies; health checks and application retries address different needs.
  • ✓Use environment files for local configuration, exclude private values from Git, and use a secret manager in production.
  • ✓A named volume persists data beyond a container but is not a backup.
  • ✓Review configuration, logs, health, ports, and recovery behavior throughout the lifecycle.

Next

What comes next

You can run a multi-service application locally. Next, map these ideas to cloud compute, least-privilege identity, and private network design.

Lesson 06 · Cloud Core — Compute, IAM and VPC Networking →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...