kelin/EZ-Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update all documentation to reflect 60+ services, Dockge, Traefik, Authelia, and new features

Browse Source 
- Update README.md with comprehensive overview of all 40+ services
- Add Quick Setup guide with Dockge deployment steps
- List all service stacks by category (Infrastructure, Media, Home Automation, Productivity, etc.)
- Update AI assistant examples for Traefik, Authelia, VPN routing
- Add network architecture with Traefik routing patterns
- Update common operations for Dockge structure
- Add storage strategy (opt/stacks vs /mnt/)
- Update configuration management section
- Add proxying external hosts overview
- Update getting started checklist with all new steps

- Update docker-guidelines.md with Dockge and Traefik sections
- Add comprehensive Dockge structure explanation
- Add Traefik and Authelia integration patterns
- Document when to use SSO vs bypass
- Add VPN routing patterns with Gluetun
- Update storage strategy recommendations

- Completely rewrite getting-started.md with step-by-step Dockge deployment
- Add DuckDNS signup instructions
- Add detailed core infrastructure deployment (DuckDNS, Traefik, Authelia, Dockge)
- Add Homepage configuration steps
- Add API key configuration for widgets
- Add troubleshooting section
- Add security checklist

- Create docs/services-reference.md - comprehensive catalog of all 60+ services
- Organized by category with descriptions
- Access URLs and SSO requirements
- Storage recommendations
- Quick deployment guide
- Summary table by stack

All documentation now accurately reflects the complete homelab setup with Dockge, Traefik, Authelia, Gluetun, Homepage, and all 40+ services across 10 stack files.

Co-authored-by: kelinfoxy <67766943+kelinfoxy@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-01-12 01:16:12 +00:00
parent 63f39e51a4
commit 6fec6b501e
4 changed files with 1297 additions and 509 deletions
Download Patch File Download Diff File Expand all files Collapse all files

559
README.md
View File

@@ -4,16 +4,23 @@ AI-Powered Homelab Administration with GitHub Copilot
## Overview
This repository provides a structured approach to managing a homelab infrastructure using Docker Compose, with integrated AI assistance through GitHub Copilot. The AI assistant is specifically trained to help you create, modify, and manage Docker services while maintaining consistency across your entire server stack.
This repository provides a comprehensive, production-ready homelab infrastructure using Docker Compose with Dockge, featuring 40+ pre-configured services. Integrated AI assistance through GitHub Copilot helps you create, modify, and manage Docker services while maintaining consistency across your entire server stack.
The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia for Single Sign-On, Gluetun for VPN routing, and DuckDNS for dynamic DNS - all managed through file-based configurations that the AI can modify.
## Features
- **AI-Powered Management**: GitHub Copilot integration with specialized instructions for Docker service management
- **Docker Compose First**: All persistent services defined in organized compose files
- **Consistent Structure**: Standardized naming conventions and patterns across all services
- **Dockge Structure**: All stacks organized in `/opt/stacks/` for easy management via Dockge
- **40+ Pre-configured Services**: Production-ready compose files across infrastructure, media, home automation, productivity, and monitoring
- **Traefik Reverse Proxy**: Automatic HTTPS with Let's Encrypt via file-based configuration (no web UI needed)
- **Authelia SSO**: Single Sign-On protection for all admin interfaces with smart bypass rules for media apps
- **Gluetun VPN**: Surfshark WireGuard integration for secure downloads
- **Homepage Dashboard**: AI-configurable dashboard with Docker integration and service widgets
- **External Host Proxying**: Proxy external services (Raspberry Pi, routers, NAS) through Traefik
- **Stack-Aware Changes**: AI considers the entire infrastructure when making changes
- **Comprehensive Documentation**: Detailed guidelines and examples for all operations
- **Example Services**: Ready-to-use compose files for common homelab services
- **Comprehensive Documentation**: Detailed guidelines including proxying external hosts
- **File-Based Configuration**: Everything managed via YAML files - no web UI dependencies
## Quick Start
@@ -23,8 +30,10 @@ This repository provides a structured approach to managing a homelab infrastruct
- Docker Compose V2
- Git
- VS Code with GitHub Copilot extension (for AI assistance)
- A domain from DuckDNS (free)
- Surfshark VPN account (optional, for VPN features)
### Initial Setup
### Quick Setup (Dockge Structure)
1. **Clone the repository:**
```bash
@@ -36,45 +45,90 @@ This repository provides a structured approach to managing a homelab infrastruct
2. **Create environment file:**
```bash
cp .env.example .env
# Edit .env with your values
# Edit .env with your values (domain, API keys, passwords)
nano .env
```
3. **Create the main network:**
3. **Create required directories:**
```bash
sudo mkdir -p /opt/stacks
sudo chown -R $USER:$USER /opt/stacks
```
4. **Create Docker networks:**
```bash
docker network create homelab-network
docker network create traefik-network
docker network create media-network
```
4. **Create config directories:**
5. **Deploy core infrastructure (in order):**
```bash
mkdir -p config
# 1. DuckDNS (Dynamic DNS)
mkdir -p /opt/stacks/duckdns && cp docker-compose/duckdns.yml /opt/stacks/duckdns/docker-compose.yml
cd /opt/stacks/duckdns && docker compose up -d
# 2. Traefik (Reverse Proxy with SSL)
mkdir -p /opt/stacks/traefik/dynamic
cp docker-compose/traefik.yml /opt/stacks/traefik/docker-compose.yml
cp config-templates/traefik/* /opt/stacks/traefik/
cd /opt/stacks/traefik && docker compose up -d
# 3. Authelia (SSO)
mkdir -p /opt/stacks/authelia
cp docker-compose/authelia.yml /opt/stacks/authelia/docker-compose.yml
cp config-templates/authelia/* /opt/stacks/authelia/
cd /opt/stacks/authelia && docker compose up -d
# 4. Dockge (Stack Manager)
mkdir -p /opt/stacks/infrastructure
cp docker-compose/infrastructure.yml /opt/stacks/infrastructure/docker-compose.yml
cd /opt/stacks/infrastructure && docker compose up -d dockge
```
5. **Start your first service:**
```bash
# Example: Start Portainer for container management
docker compose -f docker-compose/infrastructure.yml up -d portainer
```
6. **Access the service:**
Open `http://your-server-ip:9000` in your browser
6. **Access Dockge:**
Open `https://dockge.yourdomain.duckdns.org` (use Authelia login)
Now deploy remaining stacks through Dockge's UI!
## Repository Structure
```
AI-Homelab/
├── .github/
│ └── copilot-instructions.md # AI assistant guidelines
│ └── copilot-instructions.md # AI assistant guidelines (Dockge, Traefik, Authelia aware)
├── docker-compose/
│ ├── infrastructure.yml # Core services (proxy, DNS, Portainer)
│ ├── media.yml # Media services (Plex, Sonarr, Radarr)
│ ├── monitoring.yml # Observability (Prometheus, Grafana)
│ ├── development.yml # Dev tools (code-server, databases)
│ └── README.md # Docker Compose documentation
│ ├── traefik.yml # Reverse proxy (deploy first)
│ ├── authelia.yml # SSO authentication
│ ├── duckdns.yml # Dynamic DNS
│ ├── gluetun.yml # VPN client (Surfshark) + qBittorrent
│ ├── infrastructure.yml # Dockge, Portainer, Pi-hole, Watchtower, Dozzle, Glances
│ ├── dashboards.yml # Homepage, Homarr
│ ├── media.yml # Plex, Jellyfin, Sonarr, Radarr, Prowlarr
│ ├── media-extended.yml # Readarr, Lidarr, Lazy Librarian, Mylar3, Calibre-Web,
│ │ # Jellyseerr, FlareSolverr, Tdarr, Unmanic
│ ├── homeassistant.yml # Home Assistant, ESPHome, TasmoAdmin, Node-RED,
│ │ # Mosquitto, Zigbee2MQTT, MotionEye
│ ├── productivity.yml # Nextcloud, Mealie, WordPress, Gitea, DokuWiki,
│ │ # BookStack, MediaWiki (all with databases)
│ ├── utilities.yml # Backrest, Duplicati, Uptime Kuma, Code Server,
│ │ # Form.io, Authelia-Redis
│ ├── monitoring.yml # Prometheus, Grafana, Loki, Promtail, cAdvisor
│ ├── development.yml # GitLab, PostgreSQL, Redis, pgAdmin, Jupyter
│ └── README-dockge.md # Dockge deployment guide
├── config-templates/
│ ├── traefik/ # Traefik static and dynamic configs
│ ├── authelia/ # Authelia config and user database
│ ├── homepage/ # Homepage dashboard configs (with widgets)
│ ├── prometheus/ # Prometheus scrape configs
│ ├── loki/ # Loki log aggregation config
│ └── ... # Other service templates
├── docs/
│ └── docker-guidelines.md # Comprehensive Docker guidelines
├── config/ # Service configurations (gitignored)
├── .env.example # Environment variable template
│ ├── docker-guidelines.md # Comprehensive Docker guidelines
│ ├── getting-started.md # Step-by-step setup guide
│ ├── quick-reference.md # Command reference
│ └── proxying-external-hosts.md # Guide for proxying Raspberry Pi, routers, etc.
├── .env.example # Environment variable template (40+ vars)
├── .gitignore # Git ignore patterns
└── README.md # This file
```
@@ -87,193 +141,384 @@ AI-Homelab/
2. **Open this repository** in VS Code
3. **Start Copilot Chat** and ask questions like:
- "Help me add a new media service to my homelab"
- "Create a docker-compose file for Home Assistant"
- "How do I configure GPU support for Plex?"
- "Check my compose file for port conflicts"
- "Configure Traefik routing for my new service"
- "Add Authelia SSO protection to this service"
- "How do I proxy my Raspberry Pi through Traefik?"
- "Create a Homepage widget for this service"
- "Route this download client through Gluetun VPN"
The AI assistant automatically follows the guidelines in `.github/copilot-instructions.md` to:
- Use `/opt/stacks/` directory structure (Dockge compatible)
- Configure Traefik labels for automatic routing
- Apply Authelia middleware where appropriate
- Suggest `/mnt/` for large data storage
- Add services to Homepage dashboard with widgets
- Maintain consistency with existing services
- Use Docker Compose for all persistent services
- Consider the entire stack when making changes
- Follow naming conventions and best practices
### Example Interactions
**Creating a new service:**
**Adding a new service:**
```
You: "I want to add Home Assistant to my homelab"
You: "Add Tautulli to monitor my Plex server"
Copilot: [Analyzes existing stack, checks for conflicts, creates compose configuration]
- Checks available ports
- Uses consistent naming
- Connects to appropriate networks
- Follows established patterns
Copilot: [Creates compose configuration with]:
- /opt/stacks/tautulli/ directory structure
- Traefik labels for HTTPS access
- Authelia middleware for SSO protection
- Homepage dashboard entry with widget
- Connection to existing Plex service
```
**Modifying a service:**
**Proxying external service:**
```
You: "Add GPU support to my Plex container"
You: "Proxy my Raspberry Pi Home Assistant through Traefik"
Copilot: [Reviews current Plex configuration and updates it]
- Checks if NVIDIA runtime is available
- Updates device mappings
- Adds required environment variables
- Maintains existing configuration
Copilot: [Creates Traefik route configuration]:
- File in /opt/stacks/traefik/dynamic/
- HTTPS with Let's Encrypt
- Authelia bypass (HA has its own auth)
- WebSocket support
- Homepage dashboard entry
```
**Configuring VPN routing:**
```
You: "Route SABnzbd through the VPN"
Copilot: [Updates compose to use Gluetun]:
- network_mode: "service:gluetun"
- Exposes ports through Gluetun
- Maintains Traefik routing
- Updates documentation
```
## Available Service Stacks
### Infrastructure (`infrastructure.yml`)
- **Nginx Proxy Manager**: Web-based reverse proxy with SSL
- **Pi-hole**: Network-wide ad blocking and DNS
- **Portainer**: Docker container management UI
- **Watchtower**: Automatic container updates
### Core Infrastructure (Required)
### Media (`media.yml`)
- **Plex**: Media streaming server
- **Jellyfin**: Open-source media server alternative
- **Sonarr**: TV show automation
- **Radarr**: Movie automation
- **Prowlarr**: Indexer manager
- **qBittorrent**: Torrent client
#### 1. Traefik (`traefik.yml`)
**Reverse proxy with automatic SSL** - Deploy first!
- Automatic HTTPS via Let's Encrypt
- File-based and Docker label routing
- HTTP to HTTPS redirect
- Dashboard at `https://traefik.${DOMAIN}`
#### 2. Authelia (`authelia.yml`)
**Single Sign-On authentication**
- TOTP 2FA support
- LDAP/file-based user database
- Smart bypass rules for media apps
- Login at `https://auth.${DOMAIN}`
#### 3. DuckDNS (`duckdns.yml`)
**Dynamic DNS updater**
- Automatic IP updates
- Integrates with Let's Encrypt
- No web UI - runs silently
#### 4. Gluetun (`gluetun.yml`)
**VPN client (Surfshark WireGuard)**
- Includes qBittorrent
- Download via `https://qbit.${DOMAIN}`
- Easy to route other services through VPN
### Infrastructure Tools (`infrastructure.yml`)
- **Dockge**: Docker Compose stack manager (PRIMARY) - `https://dockge.${DOMAIN}`
- **Portainer**: Docker management UI (secondary) - `https://portainer.${DOMAIN}`
- **Pi-hole**: Network-wide ad blocking - `https://pihole.${DOMAIN}`
- **Watchtower**: Automatic container updates
- **Dozzle**: Real-time Docker logs - `https://dozzle.${DOMAIN}`
- **Glances**: System monitoring - `https://glances.${DOMAIN}`
- **Docker Proxy**: Secure Docker socket access
### Dashboards (`dashboards.yml`)
- **Homepage**: AI-configurable dashboard with widgets - `https://home.${DOMAIN}`
- Docker integration (container status)
- Service widgets (Sonarr, Radarr, Plex, Jellyfin, etc.)
- 11 organized categories
- **Homarr**: Modern alternative dashboard - `https://homarr.${DOMAIN}`
### Media Services (`media.yml`)
- **Plex**: Media streaming server - `https://plex.${DOMAIN}` (no SSO - app access)
- **Jellyfin**: Open-source media server - `https://jellyfin.${DOMAIN}` (no SSO - app access)
- **Sonarr**: TV show automation - `https://sonarr.${DOMAIN}`
- **Radarr**: Movie automation - `https://radarr.${DOMAIN}`
- **Prowlarr**: Indexer manager - `https://prowlarr.${DOMAIN}`
- **qBittorrent**: Torrent client (via VPN) - See gluetun.yml
### Extended Media (`media-extended.yml`)
- **Readarr**: Ebook/audiobook management - `https://readarr.${DOMAIN}`
- **Lidarr**: Music collection manager - `https://lidarr.${DOMAIN}`
- **Lazy Librarian**: Book download automation - `https://lazylibrarian.${DOMAIN}`
- **Mylar3**: Comic book manager - `https://mylar.${DOMAIN}`
- **Calibre-Web**: Ebook reader and server - `https://calibre.${DOMAIN}`
- **Jellyseerr**: Media request management - `https://jellyseerr.${DOMAIN}` (no SSO)
- **FlareSolverr**: Cloudflare bypass (no UI)
- **Tdarr**: Distributed transcoding - `https://tdarr.${DOMAIN}`
- **Unmanic**: Library optimizer - `https://unmanic.${DOMAIN}`
### Home Automation (`homeassistant.yml`)
- **Home Assistant**: Home automation hub - `https://ha.${DOMAIN}` (uses host network)
- **ESPHome**: ESP device manager - `https://esphome.${DOMAIN}`
- **TasmoAdmin**: Tasmota device manager - `https://tasmoadmin.${DOMAIN}`
- **Node-RED**: Flow automation - `https://nodered.${DOMAIN}`
- **Mosquitto**: MQTT broker (no UI)
- **Zigbee2MQTT**: Zigbee bridge - `https://zigbee2mqtt.${DOMAIN}`
- **MotionEye**: Video surveillance - `https://motioneye.${DOMAIN}`
### Productivity (`productivity.yml`)
- **Nextcloud**: File sync & collaboration - `https://nextcloud.${DOMAIN}`
- Includes MariaDB database
- **Mealie**: Recipe manager - `https://mealie.${DOMAIN}` (no SSO)
- **WordPress**: Blog platform - `https://blog.${DOMAIN}` (no SSO - public)
- Includes MariaDB database
- **Gitea**: Self-hosted Git - `https://git.${DOMAIN}`
- Includes PostgreSQL database
- **DokuWiki**: File-based wiki - `https://wiki.${DOMAIN}`
- **BookStack**: Documentation platform - `https://docs.${DOMAIN}`
- Includes MariaDB database
- **MediaWiki**: Wiki platform - `https://mediawiki.${DOMAIN}`
- Includes MariaDB database
### Utilities (`utilities.yml`)
- **Backrest**: Backup manager (restic) - `https://backrest.${DOMAIN}`
- **Duplicati**: Backup software - `https://duplicati.${DOMAIN}`
- **Uptime Kuma**: Status monitoring - `https://status.${DOMAIN}` (no SSO - public)
- **Code Server**: VS Code in browser - `https://code.${DOMAIN}`
- **Form.io**: Form builder - `https://forms.${DOMAIN}`
- Includes MongoDB database
- **Authelia-Redis**: Session storage (no UI)
### Monitoring (`monitoring.yml`)
- **Prometheus**: Metrics collection
- **Grafana**: Metrics visualization
- **Node Exporter**: Host metrics
- **cAdvisor**: Container metrics
- **Uptime Kuma**: Service uptime monitoring
- **Prometheus**: Metrics collection - `https://prometheus.${DOMAIN}`
- **Grafana**: Metrics visualization - `https://grafana.${DOMAIN}`
- **Loki**: Log aggregation
- **Promtail**: Log shipping
- **Node Exporter**: Host metrics
- **cAdvisor**: Container metrics
### Development (`development.yml`)
- **Code Server**: VS Code in browser
- **GitLab CE**: Self-hosted Git repository
- **GitLab CE**: Git with CI/CD - `https://gitlab.${DOMAIN}`
- **PostgreSQL**: SQL database
- **Redis**: In-memory data store
- **pgAdmin**: PostgreSQL UI
- **Jupyter Lab**: Interactive notebooks
- **Node-RED**: Visual automation
- **Redis**: In-memory store
- **pgAdmin**: PostgreSQL UI - `https://pgadmin.${DOMAIN}`
- **Jupyter Lab**: Interactive notebooks - `https://jupyter.${DOMAIN}`
## Common Operations
### Starting Services
### Managing Stacks via Dockge
Access Dockge at `https://dockge.${DOMAIN}` to:
- View all stacks and their status
- Start/stop/restart stacks
- Edit compose files directly
- View logs
- Deploy new stacks
### Command Line Operations
#### Starting Services (Dockge Structure)
Start all services in a compose file:
```bash
docker compose -f docker-compose/infrastructure.yml up -d
# Start entire stack
cd /opt/stacks/media
docker compose up -d
# Start specific services
cd /opt/stacks/media
docker compose up -d sonarr radarr
# Start with rebuild
cd /opt/stacks/infrastructure
docker compose up -d --build
```
Start specific services:
#### Stopping Services
```bash
docker compose -f docker-compose/media.yml up -d plex sonarr radarr
# Stop entire stack
cd /opt/stacks/media
docker compose down
# Stop but keep volumes
cd /opt/stacks/media
docker compose stop
# Stop specific service
cd /opt/stacks/media
docker compose stop plex
```
### Stopping Services
#### Viewing Logs
Stop all services:
```bash
docker compose -f docker-compose/infrastructure.yml down
# Follow logs for entire stack
cd /opt/stacks/media
docker compose logs -f
# Follow logs for specific service
cd /opt/stacks/media
docker compose logs -f plex
# View last 100 lines
cd /opt/stacks/media
docker compose logs --tail=100 plex
# Or use Dozzle web UI at https://dozzle.${DOMAIN}
```
Stop specific service:
#### Updating Services
```bash
docker compose -f docker-compose/media.yml stop plex
```
# Pull latest images
cd /opt/stacks/media
docker compose pull
### Viewing Logs
# Update specific service
cd /opt/stacks/media
docker compose pull plex
docker compose up -d plex
Follow logs for a service:
```bash
docker compose -f docker-compose/media.yml logs -f plex
```
View last 100 lines:
```bash
docker compose -f docker-compose/media.yml logs --tail=100 plex
```
### Updating Services
Pull latest images:
```bash
docker compose -f docker-compose/media.yml pull
```
Update specific service:
```bash
docker compose -f docker-compose/media.yml pull plex
docker compose -f docker-compose/media.yml up -d plex
# Or enable Watchtower for automatic updates
```
### Testing with Docker Run
Test NVIDIA GPU support:
```bash
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
```
Use `docker run` only for temporary testing:
Test a new image:
```bash
# Test NVIDIA GPU support
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
# Test a new image
docker run --rm -it alpine:latest /bin/sh
# Test VPN connection through Gluetun
docker run --rm --network container:gluetun curlimages/curl ifconfig.me
```
## Network Architecture
All services connect to networks for inter-service communication:
Services connect to multiple networks for organization and security:
- **homelab-network**: Main network for all services
- **media-network**: Isolated network for media stack
- **monitoring-network**: Network for observability stack
- **database-network**: Isolated network for databases
- **traefik-network**: For Traefik to reach services (external)
- **homelab-network**: Main network for inter-service communication (external)
- **media-network**: Isolated network for media stack (external)
- **monitoring-network**: Network for observability stack (created per stack)
- **database-network**: Isolated networks for database services (created per stack)
- **dockerproxy-network**: Secure Docker socket access (created in infrastructure)
### Creating Required Networks
Create networks manually:
```bash
# Create external networks (do this once)
docker network create traefik-network
docker network create homelab-network
docker network create media-network
docker network create monitoring-network
docker network create database-network
# Stack-specific networks are created automatically by compose files
```
### Traefik Routing
All services accessed via Traefik with automatic HTTPS:
- Pattern: `https://service.yourdomain.duckdns.org`
- Configured via Docker labels on each service
- SSL certificates automatically managed
- No port exposure needed (except Traefik 80/443)
## Documentation
### Comprehensive Guides
- **[Docker Guidelines](docs/docker-guidelines.md)**: Complete guide to Docker service management
- **[Docker Compose README](docker-compose/README.md)**: Compose-specific documentation
- **[Copilot Instructions](.github/copilot-instructions.md)**: AI assistant guidelines
- **[Docker Guidelines](docs/docker-guidelines.md)**: Complete guide to Docker service management with Dockge
- **[Getting Started](docs/getting-started.md)**: Step-by-step setup walkthrough
- **[Quick Reference](docs/quick-reference.md)**: Command reference and troubleshooting
- **[Dockge Deployment](docker-compose/README-dockge.md)**: Dockge-specific deployment guide
- **[Proxying External Hosts](docs/proxying-external-hosts.md)**: Guide for proxying Raspberry Pi, routers, NAS via Traefik
- **[Copilot Instructions](.github/copilot-instructions.md)**: AI assistant guidelines (Traefik, Authelia, Dockge aware)
### Key Principles
1. **Docker Compose First**: Always use compose for persistent services
2. **Docker Run for Testing**: Only use `docker run` for temporary containers
3. **Consistency**: Follow established patterns and naming conventions
4. **Stack Awareness**: Consider dependencies and interactions
5. **Documentation**: Comment complex configurations
6. **Security**: Keep secrets in `.env` files, never commit them
1. **Dockge Structure**: All stacks in `/opt/stacks/stack-name/`
2. **Docker Compose First**: Always use compose for persistent services
3. **Docker Run for Testing**: Only use `docker run` for temporary containers
4. **File-Based Configuration**: Traefik labels and Authelia YAML (AI-manageable)
5. **Traefik for All**: Every service routed through Traefik with automatic SSL
6. **Smart SSO**: Authelia protects admin interfaces, bypasses media apps for device access
7. **VPN When Needed**: Route download clients through Gluetun
8. **Large Data Separate**: Use `/mnt/` for media, downloads, large databases
9. **Stack Awareness**: Consider dependencies and interactions
10. **Security**: Keep secrets in `.env` files, never commit them
## Configuration Management
### Environment Variables
All services use variables from `.env`:
All services use variables from `.env` in each stack directory:
- `PUID`/`PGID`: User/group IDs for file permissions
- `TZ`: Timezone for all services
- `DOMAIN`: Your DuckDNS domain (e.g., yourdomain.duckdns.org)
- `SERVER_IP`: Your server's IP address
- Service-specific credentials and paths
- Service-specific credentials and API keys
- Homepage widget API keys (40+ variables)
### Config Files
See `.env.example` for complete list.
Service configurations are stored in `config/service-name/`:
### Storage Strategy
**Small Data** (configs, databases < 10GB): `/opt/stacks/stack-name/`
```yaml
volumes:
- /opt/stacks/sonarr/config:/config
```
config/
├── plex/ # Plex configuration
├── sonarr/ # Sonarr configuration
├── grafana/ # Grafana dashboards
**Large Data** (media, downloads, backups): `/mnt/`
```yaml
volumes:
- /mnt/media:/media
- /mnt/downloads:/downloads
- /mnt/backups:/backups
```
The AI will suggest when to use `/mnt/` based on expected data size.
### Configuration Files
Service configurations stored in stack directories:
```
/opt/stacks/
├── traefik/
│ ├── docker-compose.yml
│ ├── traefik.yml # Static config
│ ├── dynamic/ # Dynamic routes
│ │ └── routes.yml
│ └── acme.json # SSL certificates
├── authelia/
│ ├── docker-compose.yml
│ ├── configuration.yml # Authelia settings
│ └── users_database.yml # User accounts
├── homepage/
│ ├── docker-compose.yml
│ └── config/
│ ├── services.yaml # Service definitions
│ ├── docker.yaml # Docker integration
│ ├── settings.yaml # Dashboard settings
│ └── widgets.yaml # Homepage widgets
└── ...
```
**Note**: Config directories are gitignored to prevent committing sensitive data.
Templates available in `config-templates/` directory.
## Security Best Practices
@@ -362,15 +607,51 @@ This project is provided as-is for personal homelab use.
## Getting Started Checklist
- [ ] Install Docker and Docker Compose
- [ ] Install Docker and Docker Compose V2
- [ ] Sign up for DuckDNS (free) and get your domain
- [ ] Get Surfshark VPN credentials (optional, for VPN features)
- [ ] Clone this repository
- [ ] Copy `.env.example` to `.env` and configure
- [ ] Create `homelab-network`: `docker network create homelab-network`
- [ ] Start infrastructure services: `docker compose -f docker-compose/infrastructure.yml up -d`
- [ ] Access Portainer at `http://server-ip:9000`
- [ ] Copy `.env.example` to `.env` and configure all values
- [ ] Create `/opt/stacks` directory: `sudo mkdir -p /opt/stacks && sudo chown $USER:$USER /opt/stacks`
- [ ] Create Docker networks: `docker network create traefik-network homelab-network media-network`
- [ ] Deploy DuckDNS stack
- [ ] Deploy Traefik stack (with config templates)
- [ ] Deploy Authelia stack (with config templates)
- [ ] Deploy infrastructure stack (Dockge)
- [ ] Access Dockge at `https://dockge.${DOMAIN}` and deploy remaining stacks
- [ ] Configure Homepage dashboard (copy templates to /opt/stacks/homepage/config/)
- [ ] Install VS Code with GitHub Copilot extension
- [ ] Open repository in VS Code and start using AI assistance
- [ ] Add more services as needed using AI guidance
## Proxying External Hosts
You can proxy services running on other devices (Raspberry Pi, routers, NAS) through Traefik:
**Example: Raspberry Pi Home Assistant**
```yaml
# In /opt/stacks/traefik/dynamic/external.yml
http:
routers:
ha-pi:
rule: "Host(`ha.yourdomain.duckdns.org`)"
entryPoints:
- websecure
service: ha-pi
tls:
certResolver: letsencrypt
services:
ha-pi:
loadBalancer:
servers:
- url: "http://192.168.1.50:8123"
```
See [docs/proxying-external-hosts.md](docs/proxying-external-hosts.md) for complete guide including:
- Three methods (file provider, Docker labels, hybrid)
- Authelia bypass configuration
- WebSocket support
- Examples for routers, NAS, cameras, Proxmox
## Support