Stage 4 · Provision
Networking, Storage & Compose Deep Dive
Compose Troubleshooting
Diagnose failing stacks with docker compose ps, logs, exec, events, config, and network inspect.
Common Issues
The most common Compose issues are: services failing to start due to dependency ordering, network connectivity problems between services, port conflicts, volume mount failures, and environment variable misconfigurations. Systematic debugging follows a specific order.
# 1. Check service status
docker compose ps
# 2. Check service logs
docker compose logs api
# 3. Check recent events
docker compose events --since 5m
# 4. Validate the compose file
docker compose config
# 5. Check network connectivity
docker compose exec api ping dbFollow this checklist when something is wrong. Each step eliminates a category of issues: status shows running/stopped, logs show errors, events show state changes, config validates syntax, and ping tests connectivity.
Service Status
# Show all services and their status
docker compose ps
# Output:
# NAME STATUS PORTS
# api Up 5 minutes 0.0.0.0:3000->3000/tcp
# db Up 5 minutes (healthy)
# cache Up 5 minutes (healthy)
# Show only unhealthy services
docker compose ps --filter "health=unhealthy"
# Show only exited services
docker compose ps --filter "status=exited"
# Check a specific service
docker compose ps apidocker compose ps shows the status of all services. The health column shows healthy, unhealthy, or starting. Status shows Up, Exited, or Restarting.
Log Analysis
# View logs for all services
docker compose logs
# Follow logs for a specific service
docker compose logs -f api
# Show last 50 lines
docker compose logs --tail 50 api
# Show logs with timestamps
docker compose logs -t api
# Show logs since a specific time
docker compose logs --since 2025-01-15T10:00:00 api
# Filter logs by keyword
docker compose logs api | grep -i error
# Show only the last restart's logs
docker compose logs --since 1m apidocker compose logs aggregates logs from all services. Use -f to follow in real time. --tail limits output. grep filters for specific errors or patterns.
Network Debugging
# List Compose networks
docker network ls | grep <project>
# Inspect network details
docker network inspect <project>_default
# Check which containers are on a network
docker network inspect <project>_default --format '{{range .Containers}}{{.Name}} {{end}}'
# Test connectivity from a service
docker compose exec api ping db
docker compose exec api nc -zv db 5432
# Check DNS resolution
docker compose exec api nslookup db
# Check container IP addresses
docker compose exec api ip addr showNetwork debugging follows a sequence: verify the network exists, check which containers are connected, test connectivity with ping and nc, verify DNS resolution, and check IP configuration.
Configuration Validation
# Validate the compose file
docker compose config
# Show the resolved configuration
docker compose config --format json
# Check for deprecated features
docker compose config 2>&1 | grep -i deprecat
# Validate a specific service
docker compose config api
# Show the final environment variables
docker compose config --format json | jq '.services.api.environment'docker compose config validates the compose file and shows the resolved configuration with all defaults, environment variables, and merged overrides. It catches syntax errors and missing required fields.
Events and Monitoring
# Show Compose events (container start, stop, die, etc.)
docker compose events
# Show events for a specific service
docker compose events api
# Show events since a specific time
docker compose events --since 5m
# Real-time event monitoring
docker compose events --format "{{.Time}} {{.Service}} {{.Event}}"
# Check resource usage
docker stats --no-stream $(docker compose ps -q)docker compose events shows container lifecycle events: create, start, stop, die, kill, oom. These help identify crash loops, restarts, and OOM kills.
docker compose ps -q outputs only container IDs, one per line. This is useful for piping to other commands: docker stats $(docker compose ps -q) shows stats for all containers in the stack.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.