picpeak/DEPLOYMENT-TRAEFIK.md

Deployment Guide - Traefik Production Setup

Overview

This guide explains how to deploy PicPeak with an external Traefik reverse proxy for production use.

Fixed Issues

1. Database Migration: Added missing created_at column to email_queue table
2. 502 Bad Gateway: Properly configured Traefik routing and backend accessibility
3. Health Checks: Fixed health check endpoint imports and paths

Deployment Steps

1. Update Environment Variables

Ensure your .env file has the correct URLs:

ADMIN_URL=https://picpeak.nothaft.cloud
FRONTEND_URL=https://picpeak.nothaft.cloud

2. Build Images

# Build backend image
docker build -t picpeak-backend:latest ./backend

# Build frontend image  
docker build -t picpeak-frontend:latest ./frontend \
  --build-arg VITE_API_URL=/api \
  --build-arg VITE_UMAMI_URL=${VITE_UMAMI_URL} \
  --build-arg VITE_UMAMI_WEBSITE_ID=${VITE_UMAMI_WEBSITE_ID}

3. Deploy with Traefik

Use the new Traefik-specific compose file:

docker-compose -f docker-compose.traefik.yml up -d

4. Verify Deployment

Check that all services are healthy:

# Check container status
docker-compose -f docker-compose.traefik.yml ps

# Check backend health
curl https://picpeak.nothaft.cloud/api/health

# Check logs
docker-compose -f docker-compose.traefik.yml logs -f backend

Key Differences from Standard Deployment

1. No Internal Nginx: Traefik handles all routing externally
2. API Path Stripping: Traefik strips /api prefix when forwarding to backend
3. Network Configuration: Services join external traefik network
4. Health Checks: Backend exposes /health endpoint (not /api/health)

Why CI/CD Tests Pass But Production Fails

CI/CD tests typically:

• Use in-memory or temporary databases with fresh migrations
• Don't test through reverse proxy (direct API calls)
• Don't run background services (email processor, etc.)
• Have different network configurations

Production environment has:

• Persistent database that may have migration state issues
• Reverse proxy routing complexity
• All background services running
• Different security and network constraints

Troubleshooting

502 Bad Gateway

• Check Traefik network connectivity: docker network ls
• Verify backend is in traefik network: docker inspect picpeak-backend
• Check Traefik logs: docker logs traefik

Database Issues

• Connect to database: docker exec -it picpeak-db psql -U picpeak
• Check migration status: SELECT * FROM migrations;
• Run migrations manually: docker exec -it picpeak-backend npm run migrate:safe

Email Service Errors

• Check email queue: SELECT * FROM email_queue ORDER BY created_at DESC LIMIT 10;
• Monitor email processor: docker logs picpeak-backend | grep "email"