quixotic/.serena/memories/traefik_add_new_app_guide.md

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:

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

# 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)

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

# 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