The Root Cause On DigitalOcean Droplets, “Docker 502 Bad Gateway” primarily signifies that a reverse proxy, such as Nginx, cannot establish a connection with your Dockerized application container. This often occurs because the application container is either failing to start, crashing due to resource exhaustion (common on smaller droplets), or not listening on the expected network interface and port, rendering it unreachable by the proxy.

Quick Fix (CLI)

First, identify the problematic container:

docker ps -a

Inspect the container’s logs to understand the immediate issue:

docker logs <container_name_or_id>

Attempt to restart the specific container:

docker restart <container_name_or_id>

If using Docker Compose, restart the affected service or the entire stack:

docker-compose restart <service_name>
# or
docker-compose up -d --build

Configuration Check

1. Docker Container/Service Definition (e.g., docker-compose.yml, Dockerfile):

   • Verify Port Exposure: Ensure your Docker container correctly exposes the application’s internal port and maps it to a host port if required by your reverse proxy. The application inside the container should listen on 0.0.0.0 to be accessible from outside the container.
   • Example docker-compose.yml snippet:

     services:
       webapp:
         image: your_application_image
         ports:
           - "8000:8000" # HOST_PORT:CONTAINER_PORT
         environment:
           - APP_PORT=8000 # Ensure your application respects this
         healthcheck: # Recommended for better container management
           test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
           interval: 30s
           timeout: 10s
           retries: 3
           start_period: 20s

   • Application Listen Address: Confirm your application within the Docker container is configured to listen on 0.0.0.0 and the specified port (e.g., 8000), not 127.0.0.1 (localhost). This is crucial for accessibility from other containers or the host.

2. Reverse Proxy Configuration (e.g., Nginx):

   • If Nginx is installed directly on your Droplet, inspect its configuration file, typically /etc/nginx/sites-available/your_domain.conf or /etc/nginx/nginx.conf.
   • Verify proxy_pass: Ensure the proxy_pass directive correctly points to the HOST_PORT where your Docker container’s application is exposed.
   • Example Nginx configuration snippet:

     server {
         listen 80;
         server_name your_domain.com;
     
         location / {
             proxy_pass http://127.0.0.1:8000; # Must match the HOST_PORT in docker-compose.yml
             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;
         }
     }

   • Test and Reload Nginx: After any Nginx configuration changes, test the syntax and reload the service:

     sudo nginx -t
     sudo systemctl reload nginx

Verification

1. Check Container Status:

   docker ps

   Verify that the problematic container’s STATUS column shows Up (...) and its HEALTH column (if health checks are defined) shows (healthy).

2. Test Direct Access to Docker Port: From your Droplet’s CLI, attempt to access the application via its directly exposed Docker host port (e.g., 8000 in the example):

   curl -v http://localhost:8000

   You should see a successful response from your application, not an error.

3. Access via Browser: Finally, attempt to access your application through its domain name or your DigitalOcean Droplet’s IP address in a web browser.