/
Docker Compose Service Troubleshooting Guide

Docker Compose Service Troubleshooting Guide

Purpose

This guide provides a structured approach to troubleshooting services running in Docker Compose, including networked services behind reverse proxies. It covers best practices, common pitfalls, and step-by-step diagnostics.

1. Preliminary Checks

Recommended Actions

  1. Verify Docker and Docker Compose installation:

docker --version
docker-compose --version

  1. Check the status of all containers:

docker-compose ps

  1. Review container logs for errors or warnings:

docker-compose logs
docker-compose logs <service_name>

Avoid

  • Modifying running containers without understanding service dependencies.

  • Making ad-hoc changes outside of version-controlled configuration files.

2. Service Restart and Rebuild

Recommended Actions

  • Restart a specific service:

docker-compose restart <service_name>

  • Rebuild a service if the container appears corrupted or outdated:

docker-compose up -d --build

Avoid

  • Restarting all services simultaneously without assessing potential downtime.

  • Manually killing containers without using Docker Compose commands.

3. Container Health Verification

Recommended Actions

  • Inspect logs and health status of containers:

docker logs <container_id>
docker inspect --format='{{.State.Health.Status}}' <container_id>

  • Use healthchecks defined in to validate service readiness.

Avoid

  • Assuming that “running” containers are healthy; the application may still fail internally.

4. Network and Proxy Troubleshooting

Recommended Actions

  1. Verify the proxy container is operational:

docker-compose ps

  1. Inspect proxy logs for connectivity or configuration errors:

docker-compose logs <proxy_service>

  1. Validate internal service reachability from the proxy container:

docker exec -it <proxy_container> curl http://<service_name>:<port>

  1. Ensure proper port mapping in :

ports:

  • "80:80"

  • "443:443"

  1. Confirm Docker network connectivity:

docker network ls
docker network inspect <network_name>

Avoid

  • Editing proxy configurations directly inside running containers.

  • Ignoring DNS resolution issues within the Docker network.

  • Exposing ports unnecessarily or misconfigured firewall rules.

5. Debugging Techniques

  • Access running containers for interactive troubleshooting:

docker-compose exec <service_name> /bin/sh

or

docker-compose exec <service_name> /bin/bash

  • Test service endpoints internally:

curl http://localhost:<service_port>

  • Validate Docker Compose configuration:

docker-compose config

  • Use structured logs and monitoring tools for more complex multi-container environments.

6. Best Practices Summary

Recommended

To Avoid

Check logs before acting

Blindly restart all services

Restart services individually

Edit live containers directly

Verify health checks

Assume running = healthy

Test proxy and network connectivity

Ignore DNS or network issues

Debug with docker-compose exec

Patch container files manually

7. Notes on Proxy Configuration

When troubleshooting a reverse proxy (Nginx, Traefik, Caddy, etc.):

  • Ensure the proxy configuration matches the internal service names and ports.

  • Validate SSL/TLS certificates and automatic renewals if applicable.

  • Reload or restart the proxy container after configuration changes:

docker-compose restart <proxy_service>

  • Consider enabling verbose logging temporarily for advanced debugging.