# 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