diff --git a/.serena/memories/traefik_add_new_app_guide.md b/.serena/memories/traefik_add_new_app_guide.md new file mode 100644 index 0000000..b7ede99 --- /dev/null +++ b/.serena/memories/traefik_add_new_app_guide.md @@ -0,0 +1,190 @@ +# How to Add New Application with Global Traefik + +## Current Working Configuration + +Global Traefik is successfully running on the server managing multiple applications: +- **traefik.quixy.uk** - Traefik dashboard (working ✅) +- **music.quixy.uk** - Quixotic app (working ✅) + +## Steps to Add New Application + +### 1. Update Application's docker-compose.yml + +Add the following to your app service: + +```yaml +services: + your-app: + image: your-image + container_name: your-app-name + restart: unless-stopped + + # Your app configuration + environment: + PORT: 3000 # or whatever port your app uses + + # Traefik labels + labels: + - "traefik.enable=true" + + # Router configuration + - "traefik.http.routers.yourapp.rule=Host(`yourapp.quixy.uk`)" + - "traefik.http.routers.yourapp.entrypoints=websecure" + - "traefik.http.routers.yourapp.tls.certresolver=letsencrypt" + - "traefik.http.routers.yourapp.service=yourapp" + + # Service configuration (must match the port your app listens on) + - "traefik.http.services.yourapp.loadbalancer.server.port=3000" + + # Network specification + - "traefik.docker.network=traefik-global" + + # Networks - connect to both traefik-global and internal network + networks: + - traefik-global + - your-internal-network # if you have databases, etc. + +networks: + # External network managed by global Traefik + traefik-global: + external: true + + # Internal network for app-only communication (optional) + your-internal-network: + driver: bridge +``` + +### 2. Key Points + +**Router Name**: Use unique name for each app (e.g., `yourapp`, `music`, `api`, etc.) +- `traefik.http.routers.YOURAPP.rule=...` +- `traefik.http.routers.YOURAPP.entrypoints=...` +- `traefik.http.services.YOURAPP.loadbalancer.server.port=...` + +**Port**: Must match the INTERNAL port your app listens on inside the container +- If your app runs on port 3000 inside container → use `port=3000` +- If your app runs on port 8080 inside container → use `port=8080` + +**Networks**: App must be in `traefik-global` network for Traefik to reach it +- Database containers should NOT be in traefik-global (security) +- App connects to both networks (bridge between Traefik and internal services) + +### 3. Deploy Application + +```bash +# Navigate to app directory +cd /path/to/your-app + +# Start the application +docker-compose up -d + +# Check logs +docker logs your-app-name -f + +# Verify Traefik detected it +docker logs traefik-global | grep yourapp +``` + +### 4. Configure DNS + +Add A record: +``` +yourapp.quixy.uk → YOUR_SERVER_IP +``` + +### 5. Verify + +After DNS propagation (5-30 minutes): +- App accessible at: `https://yourapp.quixy.uk` +- SSL certificate auto-generated by Let's Encrypt +- HTTP automatically redirects to HTTPS + +## Example: Quixotic Music App (Working Configuration) + +```yaml +services: + quixotic-app: + build: + context: . + dockerfile: Dockerfile + container_name: quixotic-app + restart: unless-stopped + env_file: + - .env.docker + environment: + NODE_ENV: production + PORT: 3000 + DATABASE_URL: postgresql://user:pass@postgres:5432/db + volumes: + - downloads:/app/downloads + labels: + - "traefik.enable=true" + - "traefik.http.routers.quixotic.rule=Host(`music.quixy.uk`)" + - "traefik.http.routers.quixotic.entrypoints=websecure" + - "traefik.http.routers.quixotic.tls.certresolver=letsencrypt" + - "traefik.http.routers.quixotic.service=quixotic" + - "traefik.http.services.quixotic.loadbalancer.server.port=3000" + - "traefik.docker.network=traefik-global" + depends_on: + postgres: + condition: service_healthy + networks: + - quixotic # Internal network for postgres + - traefik-global # External network for Traefik + + postgres: + image: postgres:15-alpine + container_name: quixotic-postgres + networks: + - quixotic # Only internal network, NOT traefik-global + +networks: + quixotic: + driver: bridge + traefik-global: + external: true +``` + +## Troubleshooting + +### App not accessible +```bash +# Check container is running +docker ps | grep your-app + +# Check container is in traefik-global network +docker inspect your-app-name | grep Networks -A 10 + +# If not in network, connect manually +docker network connect traefik-global your-app-name +``` + +### 502 Bad Gateway +- Wrong port in labels (check what port app listens on inside container) +- App not responding (check app logs) +- App not in traefik-global network + +### 404 Not Found +- Wrong Host() rule in labels +- DNS not configured +- Traefik didn't detect container (check traefik logs) + +### SSL Certificate not issued +- DNS not propagated yet (wait 5-30 minutes) +- Ports 80/443 not open in firewall +- Check traefik logs for ACME errors + +## Current Traefik Routes (Working) + +- `music.quixy.uk` → quixotic@docker → port 3000 ✅ +- `traefik.quixy.uk` → traefik-dashboard@docker → api@internal ✅ +- Auto HTTP→HTTPS redirect enabled ✅ +- ACME challenge working ✅ + +## Important Notes + +1. **Never expose database ports** - keep databases in internal networks only +2. **Each app needs unique router name** - use app name as prefix +3. **Port must match container internal port** - not host port +4. **DNS must be configured** - before SSL will work +5. **Traefik auto-discovers** - no restart needed when adding apps