# 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**:
```bash
docker ps # Check if backend is running
docker logs picpeak-backend # Check for startup errors
```

2. **Test backend directly**:
```bash
# 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**:
```bash
# 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**:
```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**:
```bash
# 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**:
```bash
# From outside
curl -v https://picpeak.local.nothaft.cloud/api/public/settings

# Should see backend logs if request reaches container
```

3. **Verify Traefik middleware**:
```bash
# 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:

```bash
# 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.