Troubleshooting 504 Gateway Timeout on portugalodissey.pt¶

Problem¶

Getting 504 Gateway Timeout when accessing qual.portugalodissey.pt (or other portugalodissey.pt domains).

Common Causes¶

Service container not running
Service unhealthy (healthcheck failing)
Traefik router not detecting the new domain
Network connectivity issues
Service not listening on expected port

Diagnostic Steps¶

Step 1: Check if Service is Running¶

# On VPS
cd /opt/po-platform

# Check if public-fo-qual is running
docker ps | grep public-fo-qual

# Should show: po-public-fo-qual ... Up (healthy)
# If not running or unhealthy, that's the issue

Step 2: Check Traefik Router Configuration¶

# Verify router rules include portugalodissey.pt
docker inspect po-public-fo-qual | grep -A 2 'traefik.http.routers.public-fo-qual.rule'

# Should show:
# "traefik.http.routers.public-fo-qual.rule=Host(`public-fo-qual.portugalodyssey.pt`) || Host(`qual.portugalodyssey.pt`) || Host(`public-fo-qual.portugalodissey.pt`) || Host(`qual.portugalodissey.pt`)"

Step 3: Check Traefik Logs¶

# Look for errors related to portugalodissey.pt or 504 errors
docker logs po-traefik 2>&1 | grep -i 'portugalodissey\|504\|timeout\|error' | tail -30

# Look for router detection
docker logs po-traefik 2>&1 | grep -i 'public-fo-qual' | tail -10

Step 4: Check Service Health¶

# Check health status
docker inspect po-public-fo-qual | grep -A 10 '"Health"'

# Test direct connection to service
docker exec po-public-fo-qual wget -qO- http://127.0.0.1:80 | head -5

# Should return HTML content, not error

Step 5: Check Traefik API for Router Status¶

# Check if Traefik sees the router
curl -s http://localhost:8080/api/http/routers | jq '.[] | select(.name | contains("public-fo-qual"))'

# Check if router includes portugalodissey.pt in rule
curl -s http://localhost:8080/api/http/routers/public-fo-qual@docker | jq '.rule'

Step 6: Verify Network Connectivity¶

# Check if service is on traefik-public network
docker inspect po-public-fo-qual | grep -A 5 'traefik-public'

# Test connectivity from Traefik to service
docker exec po-traefik wget -qO- http://po-public-fo-qual:80 | head -5

Solutions¶

Solution 1: Force Recreate Service¶

If the service exists but Traefik isn't routing correctly:

cd /opt/po-platform

# Force recreate to ensure fresh labels
docker compose -f infrastructure/compose/qualification.yml --env-file .env.qual up -d --force-recreate public-fo-qual

# Wait a few seconds
sleep 5

# Check Traefik logs
docker logs po-traefik 2>&1 | grep -i 'public-fo-qual' | tail -5

Solution 2: Restart Traefik¶

If Traefik isn't detecting the new router:

cd /opt/po-platform

# Restart Traefik to reload router configuration
docker compose -f infrastructure/compose/shared.yml --env-file infrastructure/compose/.env.shared restart traefik

# Wait for Traefik to start
sleep 10

# Check logs
docker logs po-traefik 2>&1 | tail -20

Solution 3: Verify DNS¶

Ensure DNS is pointing to the VPS:

# Check DNS resolution
dig qual.portugalodissey.pt +short

# Should return the VPS IP address
# If not, DNS is not configured correctly

Solution 4: Check Service Logs¶

# Check service logs for errors
docker logs po-public-fo-qual 2>&1 | tail -50

# Look for startup errors, port binding issues, etc.

Solution 5: Verify Compose File¶

Ensure the compose file has the correct router rules:

cd /opt/po-platform

# Check if router rule includes portugalodissey.pt
grep -A 1 'traefik.http.routers.public-fo-qual.rule' infrastructure/compose/qualification.yml

# Should include: || Host(`qual.portugalodissey.pt`)

Quick Fix Script¶

Run this script to diagnose and attempt fixes:

#!/bin/bash
cd /opt/po-platform

echo "=== Diagnosing 504 Error ==="
echo ""

# Check service status
echo "1. Service Status:"
docker ps | grep public-fo-qual || echo "  ❌ Service not running"
echo ""

# Check router rule
echo "2. Router Rule:"
docker inspect po-public-fo-qual 2>/dev/null | grep -A 1 'traefik.http.routers.public-fo-qual.rule' || echo "  ❌ Cannot inspect service"
echo ""

# Check Traefik logs
echo "3. Recent Traefik Errors:"
docker logs po-traefik 2>&1 | grep -i 'portugalodissey\|504\|timeout' | tail -5 || echo "  ✅ No errors found"
echo ""

# Test service directly
echo "4. Direct Service Test:"
docker exec po-public-fo-qual wget -qO- http://127.0.0.1:80 2>&1 | head -3 || echo "  ❌ Service not responding"
echo ""

# Attempt fixes
echo "=== Attempting Fixes ==="
echo ""

# Recreate service
echo "Recreating service..."
docker compose -f infrastructure/compose/qualification.yml --env-file .env.qual up -d --force-recreate public-fo-qual

sleep 5

# Restart Traefik
echo "Restarting Traefik..."
docker compose -f infrastructure/compose/shared.yml --env-file infrastructure/compose/.env.shared restart traefik

sleep 10

echo ""
echo "=== Verification ==="
echo "Check if service is now accessible:"
echo "  curl -I https://qual.portugalodissey.pt"

Expected Behavior After Fix¶

✅ Service container shows as Up (healthy)
✅ Traefik logs show router detected with portugalodissey.pt rule
✅ curl -I https://qual.portugalodissey.pt returns 200 OK (or redirects to HTTPS)
✅ No 504 errors in Traefik logs

Self-signed certificate: See Let's Encrypt Rate Limit Guide
Service unhealthy: Check service logs and healthcheck configuration
Network issues: Verify Docker networks are correctly configured