How to debug Docker Compose services?

· Category: Docker

Short answer

Debug Docker Compose services by inspecting logs, running commands inside containers, verifying configurations, and checking resource usage. Use docker compose logs, docker compose exec, and docker compose config.

Steps

  1. View logs: docker compose logs -f <service>.
  2. Open a shell: docker compose exec <service> /bin/sh.
  3. Verify merged config: docker compose config.
  4. Check service status: docker compose ps.

Example

docker compose logs -f web

Run a one-off command:

docker compose run --rm web python manage.py migrate

Debug a failing start:

docker compose run --rm --entrypoint /bin/sh web

Tips

  • Use docker compose config to verify environment variable substitution.
  • Stream logs from all services or filter by service name.
  • Use a dedicated debug profile with tools like curl, netcat, and vim.

Common issues

  • docker compose exec fails if the container is not running; use docker compose run instead.
  • Exit codes from docker compose up may be misleading if a dependent service fails first.
  • Stale volumes or networks can cause configuration drift; prune them if needed.