Implement Dockge structure with Traefik, Authelia, DuckDNS, and Gluetun VPN

- Update AI copilot instructions for /opt/stacks structure and automated config management - Replace Nginx Proxy Manager with Traefik (file-based configuration for AI) - Add Authelia for SSO with bypass rules for Jellyfin/Plex apps - Add DuckDNS for dynamic DNS with Let's Encrypt integration - Add Gluetun VPN with Surfshark (WireGuard) for secure downloads - Update all services to use /opt/stacks paths instead of local directories - Add Traefik labels to all services for automatic routing - Configure qBittorrent to route through Gluetun VPN - Update .env.example with all new required variables - Create configuration templates for Traefik and Authelia - Add comprehensive Dockge deployment guide Co-authored-by: kelinfoxy <67766943+kelinfoxy@users.noreply.github.com>
2026-01-12 00:13:55 +00:00
parent 6083da7036
commit f9a34fe9c7
13 changed files with 1082 additions and 112 deletions
--- a/docker-compose/README-dockge.md
+++ b/docker-compose/README-dockge.md
@@ -0,0 +1,324 @@
+# Docker Compose Stacks - Dockge Structure
+
+This directory contains Docker Compose files designed for use with Dockge. Each stack should be placed in `/opt/stacks/stack-name/` on your server.
+
+## Structure
+
+```
+/opt/stacks/
+├── traefik/
+│   ├── docker-compose.yml     # Copy from traefik.yml
+│   ├── traefik.yml           # Static configuration
+│   ├── dynamic/              # Dynamic routes
+│   ├── acme.json            # SSL certificates (chmod 600)
+│   └── .env
+├── authelia/
+│   ├── docker-compose.yml     # Copy from authelia.yml
+│   ├── configuration.yml     # Authelia config
+│   ├── users_database.yml    # User definitions
+│   └── .env
+├── duckdns/
+│   ├── docker-compose.yml     # Copy from duckdns.yml
+│   └── .env
+├── gluetun/
+│   ├── docker-compose.yml     # Copy from gluetun.yml (includes qBittorrent)
+│   └── .env
+├── infrastructure/
+│   ├── docker-compose.yml     # Copy from infrastructure.yml
+│   └── .env
+├── media/
+│   ├── docker-compose.yml     # Copy from media.yml
+│   └── .env
+├── monitoring/
+│   ├── docker-compose.yml     # Copy from monitoring.yml
+│   └── .env
+└── development/
+    ├── docker-compose.yml     # Copy from development.yml
+    └── .env
+```
+
+## Core Infrastructure Stacks
+
+### 1. Traefik (REQUIRED - Deploy First)
+**File**: `traefik.yml`  
+**Location**: `/opt/stacks/traefik/`
+
+Reverse proxy with automatic SSL certificates via Let's Encrypt.
+
+**Features**:
+- Automatic HTTPS with Let's Encrypt
+- Docker service discovery via labels
+- File-based configuration for AI management
+- HTTP to HTTPS redirect
+
+**Setup**:
+```bash
+mkdir -p /opt/stacks/traefik/dynamic
+cd /opt/stacks/traefik
+# Copy traefik.yml to docker-compose.yml
+# Copy config templates from config-templates/traefik/
+# Create acme.json and set permissions
+touch acme.json && chmod 600 acme.json
+# Edit .env with your domain and email
+docker compose up -d
+```
+
+### 2. Authelia (REQUIRED - Deploy Second)
+**File**: `authelia.yml`  
+**Location**: `/opt/stacks/authelia/`
+
+Single Sign-On (SSO) authentication for all services.
+
+**Features**:
+- Protects services with authentication
+- Bypass rules for apps (Jellyfin, Plex)
+- Integrates with Traefik via middleware
+- TOTP 2FA support
+
+**Setup**:
+```bash
+mkdir -p /opt/stacks/authelia
+cd /opt/stacks/authelia
+# Copy authelia.yml to docker-compose.yml
+# Copy config templates from config-templates/authelia/
+# Generate secrets: openssl rand -hex 64
+# Edit configuration.yml and users_database.yml
+# Hash password: docker run authelia/authelia:latest authelia crypto hash generate argon2 --password 'yourpassword'
+docker compose up -d
+```
+
+### 3. DuckDNS (RECOMMENDED)
+**File**: `duckdns.yml`  
+**Location**: `/opt/stacks/duckdns/`
+
+Dynamic DNS updater for your domain.
+
+**Setup**:
+```bash
+mkdir -p /opt/stacks/duckdns
+cd /opt/stacks/duckdns
+# Copy duckdns.yml to docker-compose.yml
+# Add DUCKDNS_TOKEN and DUCKDNS_SUBDOMAINS to .env
+docker compose up -d
+```
+
+### 4. Gluetun VPN (REQUIRED for torrenting)
+**File**: `gluetun.yml`  
+**Location**: `/opt/stacks/gluetun/`
+
+VPN client (Surfshark) for routing download clients securely.
+
+**Includes**: qBittorrent configured to route through VPN
+
+**Setup**:
+```bash
+mkdir -p /opt/stacks/gluetun
+mkdir -p /opt/stacks/qbittorrent
+cd /opt/stacks/gluetun
+# Copy gluetun.yml to docker-compose.yml
+# Add Surfshark WireGuard credentials to .env
+# Get WireGuard config from Surfshark dashboard
+docker compose up -d
+```
+
+## Application Stacks
+
+### Infrastructure
+**File**: `infrastructure.yml`  
+**Location**: `/opt/stacks/infrastructure/`
+
+- Pi-hole: Network-wide ad blocking
+- Portainer: Docker management UI
+- Watchtower: Automatic container updates
+
+### Media
+**File**: `media.yml`  
+**Location**: `/opt/stacks/media/`
+
+- Plex: Media streaming (NO Authelia - app access)
+- Jellyfin: Open-source streaming (NO Authelia - app access)
+- Sonarr: TV show automation (WITH Authelia)
+- Radarr: Movie automation (WITH Authelia)
+- Prowlarr: Indexer manager (WITH Authelia)
+
+**Note**: qBittorrent is in gluetun.yml (VPN routing)
+
+### Monitoring
+**File**: `monitoring.yml`  
+**Location**: `/opt/stacks/monitoring/`
+
+- Prometheus: Metrics collection
+- Grafana: Visualization
+- Node Exporter: System metrics
+- cAdvisor: Container metrics
+- Uptime Kuma: Service monitoring
+- Loki: Log aggregation
+- Promtail: Log shipping
+
+### Development
+**File**: `development.yml`  
+**Location**: `/opt/stacks/development/`
+
+- Code Server: VS Code in browser
+- GitLab: Git repository manager
+- PostgreSQL: Database
+- Redis: In-memory store
+- pgAdmin: Database UI
+- Jupyter Lab: Data science notebooks
+- Node-RED: Automation
+
+## Networks
+
+Create these networks before deploying stacks:
+
+```bash
+docker network create traefik-network
+docker network create homelab-network
+```
+
+## Environment Variables
+
+Each stack needs a `.env` file. Use `/home/runner/work/AI-Homelab/AI-Homelab/.env.example` as a template.
+
+**Required variables**:
+- `DOMAIN`: Your DuckDNS domain (e.g., `yourdomain.duckdns.org`)
+- `DUCKDNS_TOKEN`: Your DuckDNS token
+- `ACME_EMAIL`: Email for Let's Encrypt
+- `AUTHELIA_JWT_SECRET`: Generate with `openssl rand -hex 64`
+- `AUTHELIA_SESSION_SECRET`: Generate with `openssl rand -hex 64`
+- `AUTHELIA_STORAGE_ENCRYPTION_KEY`: Generate with `openssl rand -hex 64`
+- `SURFSHARK_PRIVATE_KEY`: From Surfshark WireGuard config
+- `SURFSHARK_ADDRESSES`: From Surfshark WireGuard config
+
+## Deployment Order
+
+1. **Create networks**:
+   ```bash
+   docker network create traefik-network
+   docker network create homelab-network
+   ```
+
+2. **Deploy Traefik** (reverse proxy):
+   ```bash
+   cd /opt/stacks/traefik
+   docker compose up -d
+   ```
+
+3. **Deploy Authelia** (SSO):
+   ```bash
+   cd /opt/stacks/authelia
+   docker compose up -d
+   ```
+
+4. **Deploy DuckDNS** (optional but recommended):
+   ```bash
+   cd /opt/stacks/duckdns
+   docker compose up -d
+   ```
+
+5. **Deploy Gluetun** (VPN for downloads):
+   ```bash
+   cd /opt/stacks/gluetun
+   docker compose up -d
+   ```
+
+6. **Deploy other stacks** as needed:
+   ```bash
+   cd /opt/stacks/infrastructure
+   docker compose up -d
+   
+   cd /opt/stacks/media
+   docker compose up -d
+   ```
+
+## Accessing Services
+
+All services are accessible via your domain:
+
+- **With Authelia (SSO required)**:
+  - `https://traefik.yourdomain.duckdns.org` - Traefik dashboard
+  - `https://portainer.yourdomain.duckdns.org` - Portainer
+  - `https://sonarr.yourdomain.duckdns.org` - Sonarr
+  - `https://radarr.yourdomain.duckdns.org` - Radarr
+  - `https://prowlarr.yourdomain.duckdns.org` - Prowlarr
+  - `https://qbit.yourdomain.duckdns.org` - qBittorrent
+  - `https://grafana.yourdomain.duckdns.org` - Grafana
+  - And more...
+
+- **Without Authelia (direct app access)**:
+  - `https://plex.yourdomain.duckdns.org` - Plex
+  - `https://jellyfin.yourdomain.duckdns.org` - Jellyfin
+
+- **Authentication page**:
+  - `https://auth.yourdomain.duckdns.org` - Authelia login
+
+## AI Management
+
+The AI assistant (GitHub Copilot) can:
+
+1. **Add new services**: Creates compose files with proper Traefik labels and Authelia middleware
+2. **Modify routes**: Updates Docker labels to change proxy routing
+3. **Manage SSO**: Adds or removes Authelia middleware as needed
+4. **Configure VPN**: Sets up services to route through Gluetun
+5. **Update configurations**: Modifies config files in `/opt/stacks/*/config/`
+
+All configuration is file-based, allowing the AI to manage everything without web UI dependencies.
+
+## Storage Strategy
+
+- **Config files**: `/opt/stacks/stack-name/config/` (on system drive)
+- **Small data**: Docker named volumes
+- **Large data**: 
+  - Media: `/mnt/media` (separate drive)
+  - Downloads: `/mnt/downloads` (separate drive)
+  - Backups: `/mnt/backups` (separate drive)
+
+## Troubleshooting
+
+### Service won't start
+```bash
+cd /opt/stacks/stack-name
+docker compose logs -f
+```
+
+### Check Traefik routing
+```bash
+docker logs traefik
+# Or visit: https://traefik.yourdomain.duckdns.org
+```
+
+### Test VPN connection
+```bash
+docker exec gluetun sh -c "curl ifconfig.me"
+# Should show VPN IP, not your home IP
+```
+
+### Authelia issues
+```bash
+cd /opt/stacks/authelia
+docker compose logs -f authelia
+# Check configuration.yml for syntax errors
+```
+
+## Backup Important Files
+
+Regular backups of:
+- `/opt/stacks/` (all compose files and configs)
+- `/opt/stacks/traefik/acme.json` (SSL certificates)
+- `/opt/stacks/authelia/users_database.yml` (user accounts)
+- Environment files (`.env` - store securely, not in git!)
+
+## Security Notes
+
+1. **Secrets**: Never commit `.env` files or `acme.json` to git
+2. **Authelia**: Use strong passwords, hash them properly
+3. **VPN**: Always route download clients through Gluetun
+4. **Updates**: Watchtower keeps containers updated automatically
+5. **Firewall**: Only expose ports 80 and 443 to the internet
+
+## Getting Help
+
+- Check the main [README.md](../README.md)
+- Review [Docker Guidelines](../docs/docker-guidelines.md)
+- Use GitHub Copilot in VS Code for AI assistance
+- Check service-specific logs