new app guide

.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