How I Debugged Docker, Nginx, and Reverse Proxy Problems in Production

Production issues at the edge often look like “the app is down” when the container is healthy and Nginx is misrouting. This is the playbook I use when Docker, Nginx, and a reverse proxy disagree.

Confirm Where the Failure Lives

# Is the container up?
docker ps
docker logs --tail=200 app

# Does the app answer on its internal port?
docker exec -it nginx wget -qO- http://app:3000/health

# What does Nginx think?
nginx -t
tail -n 200 /var/log/nginx/error.log

Classic 502 Bad Gateway Causes

• Upstream container name/DNS wrong after compose change
• App listening on 127.0.0.1 inside the container instead of 0.0.0.0
• Port mismatch between proxy_pass and the service
• App crashed after boot; healthcheck still passing an old container

Headers That Break Auth and Redirects

When TLS terminates at Nginx, the app must know the original scheme and host:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Missing X-Forwarded-Proto commonly causes infinite HTTP/HTTPS redirect loops or secure cookie problems (including auth providers).

WebSockets and Long Requests

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 60s;

Docker Networking Gotchas

1. Containers on different compose networks cannot resolve each other
2. localhost inside Nginx is Nginx itself, not the host machine
3. Published ports are for the host; service-to-service should use internal ports
4. Stale containers after docker compose up without recreate

A Minimal Debug Sequence

1. Hit /health on public URL
2. Hit upstream from inside proxy container
3. Compare Host / Proto headers app receives
4. Check TLS cert and redirect rules
5. Restart only the failing service; avoid blind full stack bounce

Final Thoughts

Most Docker + Nginx outages are routing and header problems, not mysterious application bugs. Prove each hop: public edge → proxy → container → app port. Fix the first broken hop.

Written by A.M. Rinas · Published August 28, 2026

Written by A.M. Rinas

Full-Stack Software Engineer working on web applications, DevOps automation, and databases. More about me on the about page, or say hi through the contact page and LinkedIn.

← Back to all articles