picpeak/TROUBLESHOOTING-TRAEFIK.md

Traefik Troubleshooting Guide

Common Issues and Solutions

1. 404 Errors on API Routes

Problem: Getting 404 errors when accessing /api/* routes

Causes:

• Traefik routing rules not properly configured
• Backend container not healthy
• Path stripping not working correctly

Solutions:

1. Check container health:

docker ps # Check if backend is running
docker logs picpeak-backend # Check for startup errors

2. Test backend directly:

# Access backend container
docker exec -it picpeak-backend sh

# Test health endpoint
wget -O- http://localhost:3000/health

# Test public settings endpoint
wget -O- http://localhost:3000/public/settings

3. Check Traefik routing:

# Check if routes are registered in Traefik
curl https://traefik.yourdomain.com/api/http/routers | jq '.[] | select(.rule | contains("picpeak"))'

2. Backend Not Accessible Through Traefik

Key Configuration Points:

1. Traefik Labels (in deploy section):

   • traefik.enable=true - Enable Traefik for this container
   • traefik.docker.network=proxy - Specify which network Traefik should use
   • traefik.http.routers.picpeak-backend.priority=100 - Higher priority for API routes

2. Path Stripping:

   • Frontend expects /api/* but backend serves routes without /api prefix
   • Middleware strips /api before forwarding to backend

3. Network Configuration:

   • Backend must be in both picpeak (internal) and proxy (Traefik) networks

3. Environment Variable Issues

Critical Variables:

• ADMIN_URL and FRONTEND_URL must match your actual domain
• These affect CORS configuration

Example .env:

# URLs
ADMIN_URL=https://picpeak.local.nothaft.cloud
FRONTEND_URL=https://picpeak.local.nothaft.cloud

# Database
DB_USER=picpeak
DB_PASSWORD=your_secure_password
DB_NAME=picpeak

# JWT
JWT_SECRET=your_secure_jwt_secret

# Email (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=true
SMTP_USER=noreply@example.com
SMTP_PASS=smtp_password
EMAIL_FROM=noreply@example.com

4. Debugging Steps

1. Check if backend is receiving requests:

# Watch backend logs
docker logs -f picpeak-backend

# Look for incoming requests when you try to access the admin page

2. Test API routes directly:

# From outside
curl -v https://picpeak.local.nothaft.cloud/api/public/settings

# Should see backend logs if request reaches container

3. Verify Traefik middleware:

# Check if stripprefix middleware exists
curl https://traefik.yourdomain.com/api/http/middlewares | jq '.[] | select(.name | contains("picpeak"))'

5. Quick Fix Checklist

• Backend container is healthy (docker ps)
• Backend is in both networks (docker inspect picpeak-backend | grep -A 20 Networks)
• Traefik labels use correct network (traefik.docker.network=proxy)
• Priority is set correctly (backend: 100, frontend: 10)
• ADMIN_URL and FRONTEND_URL match your domain
• Database is accessible from backend
• Migrations have run successfully

6. Alternative Testing

If Traefik routing is problematic, test backend directly:

# Port forward to test backend directly
docker run --rm -it --network picpeak alpine/curl curl http://backend:3000/health

# Or expose backend port temporarily
docker run -d --name picpeak-backend-test \
  --network picpeak \
  -p 3001:3000 \
  registry.local.nothaft.cloud/picpeak-backend:latest

Then access http://localhost:3001/health to verify backend is working.