f9a34fe9c7
- 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>
325 lines
8.9 KiB
Markdown
325 lines
8.9 KiB
Markdown
# 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
|