From 331841fdbef9694af45cc6fff99fd927ce355d8c Mon Sep 17 00:00:00 2001 From: kelinfoxy <67766943+kelinfoxy@users.noreply.github.com> Date: Sun, 25 Jan 2026 12:35:16 -0500 Subject: [PATCH] wiki update --- docs/services-overview.md | 4 +- wiki-check/Home.md | 146 +++++++++++++ wiki-check/_Sidebar.md | 54 +++++ wiki-update/AI-Management-Guide.md | 299 +++++++++++++++++++++++++++ wiki-update/Home.md | 146 +++++++++++++ wiki-update/README.md | 292 ++++++++++++++++++++++++++ wiki-update/Service-Documentation.md | 199 ++++++++++++++++++ wiki-update/Services-Overview.md | 229 ++++++++++++++++++++ 8 files changed, 1367 insertions(+), 2 deletions(-) create mode 100644 wiki-check/Home.md create mode 100644 wiki-check/_Sidebar.md create mode 100644 wiki-update/AI-Management-Guide.md create mode 100644 wiki-update/Home.md create mode 100644 wiki-update/README.md create mode 100644 wiki-update/Service-Documentation.md create mode 100644 wiki-update/Services-Overview.md diff --git a/docs/services-overview.md b/docs/services-overview.md index 939511f..7318c4b 100644 --- a/docs/services-overview.md +++ b/docs/services-overview.md @@ -4,9 +4,9 @@ This document provides a comprehensive overview of all 50+ pre-configured servic ## Services Overview -| Stacks (12) | Services (70 + 6db) | SSO | Storage | Access URLs | +| Stacks (12) | Services (50 + 6db) | SSO | Storage | Access URLs | |-------|----------|-----|---------|-------------| -| **� alternatives.yaml** (6 + 3 DBs) | | | | | +| **🔀 alternatives.yaml** (6 + 3 DBs) | | | | | | ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/alternatives | dockge.${DOMAIN} | | ├─ Portainer | Container management | ✓ | /opt/stacks/alternatives | portainer.${DOMAIN} | | ├─ Authentik Server | SSO with web UI | ✓ | /opt/stacks/alternatives | authentik.${DOMAIN} | diff --git a/wiki-check/Home.md b/wiki-check/Home.md new file mode 100644 index 0000000..d4e322d --- /dev/null +++ b/wiki-check/Home.md @@ -0,0 +1,146 @@ +# EZ-Homelab Wiki + +Welcome to the **EZ-Homelab Wiki** - the complete guide for deploying and managing a production-ready homelab server with SSO, Reverse Proxy, DuckNS & LetsEncrypt. + +Deploy a secure homelab in Minutes! + +[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://docker.com) +[![Traefik](https://img.shields.io/badge/Traefik-24.0.0-24A1C6)](https://traefik.io) +[![Authelia](https://img.shields.io/badge/Authelia-4.38.0-113155)](https://www.authelia.com) + +## 📖 Wiki Overview + +This wiki serves as the **single source of truth** for the EZ-Homelab project, containing all documentation, guides, and reference materials needed to deploy and manage your homelab infrastructure. + +### 🎯 Key Features + +- **Production-Ready**: Automated SSL, SSO authentication, and VPN routing +- **AI-Manageable**: File-based architecture designed for AI assistance +- **Comprehensive**: 70+ services across 12 stacks +- **Secure by Default**: Authelia SSO protection with bypass options +- **Easy Management**: Dockge web UI for visual stack management + +### 🏗️ Architecture Overview + +The EZ-Homelab uses a layered architecture: + +1. **Core Infrastructure** (Deploy First) + - DuckDNS: Dynamic DNS with wildcard SSL + - Traefik: Reverse proxy with automatic HTTPS + - Authelia: Single Sign-On authentication + - Gluetun: VPN client for secure downloads + - Sablier: Lazy loading for resource efficiency + +2. **Service Layers** + - Infrastructure: Management and monitoring tools + - Dashboards: Homepage and Homarr interfaces + - Media: Plex, Jellyfin, and automation tools + - Productivity: Nextcloud, Gitea, documentation tools + - Home Automation: Home Assistant ecosystem + - Monitoring: Grafana, Prometheus, alerting + - Transcoders: Tdarr, Unmanic for media processing + - Wikis: DokuWiki, BookStack, MediaWiki platforms + - Utilities: Backup, security, and development tools + +## 🚀 Quick Start + +### Prerequisites +- Fresh Debian/Ubuntu server (or existing system) +- Root/sudo access +- Internet connection +- VS Code with GitHub Copilot (recommended) + +### Automated Deployment +```bash +git clone https://github.com/kelinfoxy/EZ-Homelab.git +cd EZ-Homelab +cp .env.example .env +nano .env # Configure your domain and tokens +sudo ./scripts/setup-homelab.sh +sudo ./scripts/deploy-homelab.sh +``` + +**Access your homelab:** +- **Dockge**: `https://dockge.yourdomain.duckdns.org` (primary management) +- **Homepage**: `https://homepage.yourdomain.duckdns.org` (service dashboard) +- **Authelia**: `https://auth.yourdomain.duckdns.org` (SSO login) + +## 📚 Documentation Structure + +### 🏁 Getting Started +- [[Getting Started Guide]] - Complete setup and deployment +- [[Environment Configuration]] - Required settings and tokens +- [[Automated Setup]] - One-click deployment process +- [[Manual Setup]] - Step-by-step manual installation +- [[Post-Setup Guide]] - What to do after deployment + +### 🏗️ Architecture & Design +- [[System Architecture]] - High-level component overview +- [[System Architecture#Network Architecture]] - Service communication patterns +- [[System Architecture#Security Model]] - Authentication and access control +- [[System Architecture#Storage Strategy]] - Data persistence and organization +- [[Docker Guidelines]] - Service management patterns + +### 💾 Backup & Recovery +- [[Backup Strategy]] - Restic + Backrest comprehensive guide + +### 📦 Services & Stacks +- [[Services Overview]] - All 70+ available services across 12 stacks +- [[Core Infrastructure]] - Essential services (deploy first) +- [[Infrastructure Services]] - Management and monitoring +- [[Service Documentation]] - Individual service guides + +### 🛠️ Operations & Management +- [[Quick Reference]] - Command cheat sheet +- [[Ports in Use]] - Complete port mapping reference +- [[Troubleshooting]] - Common issues and solutions +- [[SSL Certificates]] - HTTPS and certificate management +- [[Proxying External Hosts]] - Connect non-Docker services +- [[Resource Limits Template]] - Performance optimization + +### 🤖 AI & Automation +- [[AI Management Guide]] - Using AI for homelab management +- [[Copilot Instructions]] - AI assistant configuration +- [[AI VS Code Setup]] - Development environment +- [[AI Management Prompts]] - Sample AI interactions + +### 📋 Reference Materials +- [[Service Documentation]] - Individual service guides +- [[Quick Reference]] - Command cheat sheet +- [[Resource Limits Template]] - Performance optimization + +## 🔧 Development & Contribution + +### For Contributors +- [[Copilot Instructions]] - AI assistant configuration +- [[AI Management Guide]] - Development best practices + +### Repository Structure +``` +EZ-Homelab/ +├── docs/ # Documentation +├── docker-compose/ # Service definitions +├── config-templates/ # Configuration templates +├── scripts/ # Deployment scripts +├── .github/ # GitHub configuration +└── wiki/ # This wiki (source of truth) +``` + +## 📞 Support & Community + +- **Issues**: [GitHub Issues](https://github.com/kelinfoxy/EZ-Homelab/issues) +- **Discussions**: [GitHub Discussions](https://github.com/kelinfoxy/EZ-Homelab/discussions) +- **Documentation**: This wiki is the primary source of truth + +## 📈 Project Status + +- **Version**: 1.0.0 (Production Ready) +- **Services**: 70+ services across 12 stacks +- **Architecture**: File-based, AI-manageable +- **Management**: Dockge web UI +- **Security**: Authelia SSO with VPN routing + +--- + +*This wiki is automatically maintained and serves as the single source of truth for the EZ-Homelab project. All information is kept current with the latest documentation.* +c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\Home.md \ No newline at end of file diff --git a/wiki-check/_Sidebar.md b/wiki-check/_Sidebar.md new file mode 100644 index 0000000..52291d5 --- /dev/null +++ b/wiki-check/_Sidebar.md @@ -0,0 +1,54 @@ +# EZ-Homelab Wiki Navigation + +## 🚀 Getting Started +- [[Home]] - Wiki overview and navigation +- [[Getting Started Guide]] - Complete setup instructions +- [[Environment Configuration]] - Required settings and tokens +- [[Automated Setup]] - One-click deployment process +- [[Manual Setup]] - Step-by-step manual installation +- [[Post Setup Guide]] - After deployment configuration +- [[AI Management Guide]] - Using AI for homelab management + +## 🏗️ Architecture & Design +- [[System Architecture]] - High-level component overview +- [[System Architecture#Network Architecture]] - Service communication patterns +- [[System Architecture#Security Model]] - Authentication and access control +- [[System Architecture#Storage Strategy]] - Data persistence and organization +- [[Docker Guidelines]] - Service management patterns +- [[Ports in Use]] - Complete port mapping reference + +## 📦 Services & Stacks +- [[Services Overview]] - All available services catalog +- [[Core Infrastructure]] - Essential services (deploy first) +- [[Infrastructure Services]] - Management and monitoring +- [[Service Documentation]] - Individual service guides + +## 🛠️ Operations & Management +- [[Quick Reference]] - Command cheat sheet +- [[Backup Strategy]] - Restic + Backrest comprehensive guide +- [[SSL Certificates]] - HTTPS and certificate management +- [[Proxying-External-Hosts]] - Connect non-Docker services +- [[Resource Limits Template]] - Performance optimization +- [[Troubleshooting]] - Common issues and solutions + +## 🤖 AI & Automation +- [[Copilot Instructions]] - AI assistant configuration +- [[AI-VS-Code-Setup]] - Development environment +- [[AI-Management-Prompts]] - Sample AI interactions + +## 📋 Additional Resources +- [[How It Works]] - System architecture explanation +- [[On-Demand-Remote-Services]] - Lazy loading configuration +- [[Authelia Customization]] - SSO configuration options +- [[Core Stack README]] - Core infrastructure details + +## 📚 External Links +- [GitHub Repository](https://github.com/kelinfoxy/EZ-Homelab) +- [Docker Hub](https://hub.docker.com) +- [Traefik Documentation](https://doc.traefik.io/traefik/) +- [Authelia Documentation](https://www.authelia.com/) +- [DuckDNS](https://www.duckdns.org/) + +--- +*This wiki serves as the single source of truth for the EZ-Homelab project.* +c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\_Sidebar.md \ No newline at end of file diff --git a/wiki-update/AI-Management-Guide.md b/wiki-update/AI-Management-Guide.md new file mode 100644 index 0000000..5b988e9 --- /dev/null +++ b/wiki-update/AI-Management-Guide.md @@ -0,0 +1,299 @@ +# AI Management Guide + +## Overview + +The EZ-Homelab is designed for **AI-assisted management** using GitHub Copilot in VS Code. This guide explains how to leverage AI capabilities for deploying, configuring, and maintaining your homelab infrastructure. + +## AI Assistant Capabilities + +### 🤖 Copilot Integration +The AI assistant is specifically trained on the AI-Homelab architecture and can: + +- **Deploy Services**: Generate Docker Compose configurations +- **Configure Networks**: Set up proper network routing +- **Manage Authentication**: Configure Authelia SSO rules +- **Troubleshoot Issues**: Diagnose and fix common problems +- **Update Services**: Handle version updates and migrations +- **Create Documentation**: Generate service-specific guides + +### 🎯 AI-First Design +The entire system is built with AI management in mind: + +- **File-Based Configuration**: All settings in editable YAML files +- **Declarative Architecture**: Define desired state, AI handles implementation +- **Comprehensive Documentation**: AI can reference complete guides +- **Template System**: Ready-to-use configuration templates + +## Getting Started with AI Management + +### Prerequisites +1. **VS Code** with GitHub Copilot extension +2. **EZ-Homelab Repository** cloned locally +3. **Basic Understanding** of Docker concepts + +### Initial Setup +```bash +# Clone the repository +git clone https://github.com/kelinfoxy/EZ-Homelab.git +cd EZ-Homelab + +# AI will help with configuration +# Ask: "Help me configure the .env file" +``` + +## AI Management Workflows + +### 1. Service Deployment +**Ask the AI:** +- "Deploy Nextcloud with PostgreSQL database" +- "Add Jellyfin media server to my stack" +- "Create a monitoring stack with Grafana and Prometheus" + +**AI Will:** +- Generate appropriate Docker Compose files +- Configure Traefik labels for routing +- Set up Authelia authentication +- Add service to Homepage dashboard +- Provide deployment commands + +### 2. Configuration Management +**Ask the AI:** +- "Configure Authelia for two-factor authentication" +- "Set up VPN routing for qBittorrent" +- "Create backup strategy for my services" + +**AI Will:** +- Modify configuration files +- Update environment variables +- Generate security settings +- Create backup scripts + +### 3. Troubleshooting +**Ask the AI:** +- "Why isn't my service accessible?" +- "Fix SSL certificate issues" +- "Resolve port conflicts" + +**AI Will:** +- Analyze logs and configurations +- Identify root causes +- Provide step-by-step fixes +- Prevent future issues + +### 4. System Updates +**Ask the AI:** +- "Update all services to latest versions" +- "Migrate from old configuration format" +- "Add new features to existing services" + +**AI Will:** +- Check for updates +- Handle breaking changes +- Update configurations +- Test compatibility + +## AI Assistant Instructions + +The AI assistant follows these core principles: + +### Project Architecture Understanding +- **Core Infrastructure**: DuckDNS, Traefik, Authelia, Gluetun, Sablier (deploy first) +- **Service Categories**: 12 stacks with 50+ services +- **Network Model**: traefik-network primary, VPN routing for downloads +- **Security Model**: Authelia SSO by default, explicit bypasses + +### File Structure Standards +``` +docker-compose/ # Service templates +├── core/ # Core infrastructure +├── infrastructure/ # Management tools +├── media/ # Media services +└── ... + +/opt/stacks/ # Runtime deployments +├── core/ # Essential services +├── infrastructure/ # Management stack +├── media/ # Media stack +└── ... +``` + +### Critical Operational Principles + +#### 1. Security-First SSO Strategy +- **Default**: ALL services start with Authelia middleware +- **Bypass**: Only Plex and Jellyfin for app compatibility +- **Disabling**: Comment middleware line: `# - "traefik.http.routers.SERVICE.middlewares=authelia@docker"` + +#### 2. Traefik Label Patterns +Standard routing configuration: +```yaml +labels: + - "traefik.enable=true" + - "traefik.http.routers.SERVICE.rule=Host(`SERVICE.${DOMAIN}`)" + - "traefik.http.routers.SERVICE.entrypoints=websecure" + - "traefik.http.routers.SERVICE.tls.certresolver=letsencrypt" + - "traefik.http.routers.SERVICE.middlewares=authelia@docker" + - "traefik.http.services.SERVICE.loadbalancer.server.port=PORT" + - "x-dockge.url=https://SERVICE.${DOMAIN}" +``` + +#### 3. Resource Management +Apply limits to prevent resource exhaustion: +```yaml +deploy: + resources: + limits: + cpus: '2.0' # Max CPU cores + memory: 4G # Max memory + pids: 1024 # Max processes + reservations: + cpus: '0.5' # Guaranteed CPU + memory: 1G # Guaranteed memory +``` + +#### 4. Storage Strategy +- **Configs**: `./service/config:/config` relative to stack directory +- **Small Data**: Named volumes (databases, app data <50GB) +- **Large Data**: External mounts `/mnt/media`, `/mnt/downloads` +- **Secrets**: `.env` files in stack directories + +#### 5. LinuxServer.io Preference +- Use `lscr.io/linuxserver/*` images when available +- Standard environment: `PUID=1000`, `PGID=1000`, `TZ=${TZ}` + +### AI Management Capabilities + +The AI can manage the homelab by: +- **Creating services**: Generate compose files with proper Traefik labels +- **Modifying routes**: Edit Traefik labels in compose files +- **Managing external hosts**: Update Traefik dynamic configuration +- **Configuring Homepage**: Edit services.yaml for dashboard +- **Toggling SSO**: Add/remove Authelia middleware labels +- **Adding VPN routing**: Change network_mode and update Gluetun ports +- **Environment management**: Update .env (remind users to copy to stacks) + +## Practical AI Usage Examples + +### Deploying a New Service +``` +User: "Add a GitLab instance to my homelab" + +AI Response: +1. Creates /opt/stacks/development/docker-compose.yml +2. Configures PostgreSQL database +3. Sets up Traefik routing with Authelia +4. Adds to Homepage dashboard +5. Provides deployment commands +``` + +### Troubleshooting Issues +``` +User: "My Traefik isn't routing to new services" + +AI Response: +1. Checks Traefik configuration +2. Verifies network connectivity +3. Examines service labels +4. Provides specific fix commands +``` + +### Configuration Updates +``` +User: "Enable 2FA for all admin services" + +AI Response: +1. Updates Authelia configuration.yml +2. Modifies access control rules +3. Regenerates secrets if needed +4. Tests authentication flow +``` + +## AI vs Manual Management + +### When to Use AI +- **New Deployments**: Service setup and configuration +- **Complex Changes**: Multi-service modifications +- **Troubleshooting**: Issue diagnosis and resolution +- **Documentation**: Understanding system architecture +- **Updates**: Version upgrades and migrations + +### When to Use Manual Methods +- **Simple Tasks**: Basic Docker commands +- **Direct Access**: Container shell access +- **Performance Monitoring**: Real-time system checks +- **Emergency Recovery**: When AI access is unavailable + +## Best Practices for AI Management + +### 1. Clear Communication +- **Specific Requests**: "Add PostgreSQL database for Nextcloud" vs "Add database" +- **Context Provided**: Include current setup details +- **Expected Outcomes**: State what you want to achieve + +### 2. Iterative Approach +- **Start Small**: Deploy one service at a time +- **Test Incrementally**: Verify each change works +- **Backup First**: Create backups before major changes + +### 3. Documentation Integration +- **Reference Guides**: AI uses provided documentation +- **Update Records**: Keep change logs for troubleshooting +- **Share Knowledge**: Document custom configurations + +### 4. Security Awareness +- **Review Changes**: Always check AI-generated configurations +- **Access Control**: Understand authentication implications +- **Network Security**: Verify VPN and firewall rules + +## Advanced AI Features + +### Template System +- **Service Templates**: Pre-configured service definitions +- **Configuration Templates**: Ready-to-use config files +- **Environment Templates**: .env file examples + +### Integration Capabilities +- **Multi-Service**: Deploy complete stacks +- **Cross-Service**: Configure service interactions +- **External Services**: Proxy non-Docker services +- **Backup Integration**: Automated backup configurations + +### Learning and Adaptation +- **Pattern Recognition**: Learns from previous deployments +- **Error Prevention**: Avoids common configuration mistakes +- **Optimization**: Suggests performance improvements + +## Getting Help + +### AI Assistant Commands +- **General Help**: "Help me with EZ-Homelab management" +- **Specific Tasks**: "How do I deploy a new service?" +- **Troubleshooting**: "Why isn't my service working?" +- **Configuration**: "How do I configure Authelia?" + +### Documentation Resources +- **Copilot Instructions**: Detailed AI capabilities +- **Service Guides**: Individual service documentation +- **Troubleshooting**: Common issues and solutions +- **Quick Reference**: Command cheat sheet + +### Community Support +- **GitHub Issues**: Bug reports and feature requests +- **Discussions**: Community questions and answers +- **Wiki**: Comprehensive documentation + +## Future AI Enhancements + +### Planned Features +- **Automated Testing**: Service health verification +- **Performance Optimization**: Resource tuning recommendations +- **Security Auditing**: Configuration security checks +- **Backup Validation**: Automated backup testing + +### Integration Improvements +- **CI/CD Integration**: Automated deployment pipelines +- **Monitoring Integration**: AI-driven alerting +- **Cost Optimization**: Resource usage analysis + +The EZ-Homelab's AI-first design makes complex homelab management accessible to users of all skill levels while maintaining production-ready reliability and security. +c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\AI-Management-Guide.md \ No newline at end of file diff --git a/wiki-update/Home.md b/wiki-update/Home.md new file mode 100644 index 0000000..ddd7571 --- /dev/null +++ b/wiki-update/Home.md @@ -0,0 +1,146 @@ +# EZ-Homelab Wiki + +Welcome to the **EZ-Homelab Wiki** - the complete guide for deploying and managing a production-ready homelab server with SSO, Reverse Proxy, DuckNS & LetsEncrypt. + +Deploy a secure homelab in Minutes! + +[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://docker.com) +[![Traefik](https://img.shields.io/badge/Traefik-24.0.0-24A1C6)](https://traefik.io) +[![Authelia](https://img.shields.io/badge/Authelia-4.38.0-113155)](https://www.authelia.com) + +## 📖 Wiki Overview + +This wiki serves as the **single source of truth** for the EZ-Homelab project, containing all documentation, guides, and reference materials needed to deploy and manage your homelab infrastructure. + +### 🎯 Key Features + +- **Production-Ready**: Automated SSL, SSO authentication, and VPN routing +- **AI-Manageable**: File-based architecture designed for AI assistance +- **Comprehensive**: 50+ services across 12 stacks +- **Secure by Default**: Authelia SSO protection with bypass options +- **Easy Management**: Dockge web UI for visual stack management + +### 🏗️ Architecture Overview + +The EZ-Homelab uses a layered architecture: + +1. **Core Infrastructure** (Deploy First) + - DuckDNS: Dynamic DNS with wildcard SSL + - Traefik: Reverse proxy with automatic HTTPS + - Authelia: Single Sign-On authentication + - Gluetun: VPN client for secure downloads + - Sablier: Lazy loading for resource efficiency + +2. **Service Layers** + - Infrastructure: Management and monitoring tools + - Dashboards: Homepage and Homarr interfaces + - Media: Plex, Jellyfin, and automation tools + - Productivity: Nextcloud, Gitea, documentation tools + - Home Automation: Home Assistant ecosystem + - Monitoring: Grafana, Prometheus, alerting + - Transcoders: Tdarr, Unmanic for media processing + - Wikis: DokuWiki, BookStack, MediaWiki platforms + - Utilities: Backup, security, and development tools + +## 🚀 Quick Start + +### Prerequisites +- Fresh Debian/Ubuntu server (or existing system) +- Root/sudo access +- Internet connection +- VS Code with GitHub Copilot (recommended) + +### Automated Deployment +```bash +git clone https://github.com/kelinfoxy/EZ-Homelab.git +cd EZ-Homelab +cp .env.example .env +nano .env # Configure your domain and tokens +sudo ./scripts/setup-homelab.sh +sudo ./scripts/deploy-homelab.sh +``` + +**Access your homelab:** +- **Dockge**: `https://dockge.yourdomain.duckdns.org` (primary management) +- **Homepage**: `https://homepage.yourdomain.duckdns.org` (service dashboard) +- **Authelia**: `https://auth.yourdomain.duckdns.org` (SSO login) + +## 📚 Documentation Structure + +### 🏁 Getting Started +- [[Getting Started Guide]] - Complete setup and deployment +- [[Environment Configuration]] - Required settings and tokens +- [[Automated Setup]] - One-click deployment process +- [[Manual Setup]] - Step-by-step manual installation +- [[Post-Setup Guide]] - What to do after deployment + +### 🏗️ Architecture & Design +- [[System Architecture]] - High-level component overview +- [[System Architecture#Network Architecture]] - Service communication patterns +- [[System Architecture#Security Model]] - Authentication and access control +- [[System Architecture#Storage Strategy]] - Data persistence and organization +- [[Docker Guidelines]] - Service management patterns + +### 💾 Backup & Recovery +- [[Backup Strategy]] - Restic + Backrest comprehensive guide + +### 📦 Services & Stacks +- [[Services Overview]] - All 70+ available services across 12 stacks +- [[Core Infrastructure]] - Essential services (deploy first) +- [[Infrastructure Services]] - Management and monitoring +- [[Service Documentation]] - Individual service guides + +### 🛠️ Operations & Management +- [[Quick Reference]] - Command cheat sheet +- [[Ports in Use]] - Complete port mapping reference +- [[Troubleshooting]] - Common issues and solutions +- [[SSL Certificates]] - HTTPS and certificate management +- [[Proxying External Hosts]] - Connect non-Docker services +- [[Resource Limits Template]] - Performance optimization + +### 🤖 AI & Automation +- [[AI Management Guide]] - Using AI for homelab management +- [[Copilot Instructions]] - AI assistant configuration +- [[AI VS Code Setup]] - Development environment +- [[AI Management Prompts]] - Sample AI interactions + +### 📋 Reference Materials +- [[Service Documentation]] - Individual service guides +- [[Quick Reference]] - Command cheat sheet +- [[Resource Limits Template]] - Performance optimization + +## 🔧 Development & Contribution + +### For Contributors +- [[Copilot Instructions]] - AI assistant configuration +- [[AI Management Guide]] - Development best practices + +### Repository Structure +``` +EZ-Homelab/ +├── docs/ # Documentation +├── docker-compose/ # Service definitions +├── config-templates/ # Configuration templates +├── scripts/ # Deployment scripts +├── .github/ # GitHub configuration +└── wiki/ # This wiki (source of truth) +``` + +## 📞 Support & Community + +- **Issues**: [GitHub Issues](https://github.com/kelinfoxy/EZ-Homelab/issues) +- **Discussions**: [GitHub Discussions](https://github.com/kelinfoxy/EZ-Homelab/discussions) +- **Documentation**: This wiki is the primary source of truth + +## 📈 Project Status + +- **Version**: 1.0.0 (Production Ready) +- **Services**: 70+ services across 12 stacks +- **Architecture**: File-based, AI-manageable +- **Management**: Dockge web UI +- **Security**: Authelia SSO with VPN routing + +--- + +*This wiki is automatically maintained and serves as the single source of truth for the EZ-Homelab project. All information is kept current with the latest documentation.* +c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\Home.md \ No newline at end of file diff --git a/wiki-update/README.md b/wiki-update/README.md new file mode 100644 index 0000000..8820818 --- /dev/null +++ b/wiki-update/README.md @@ -0,0 +1,292 @@ +# EZ-Homelab Wiki + +This directory contains the **complete wiki documentation** for the EZ-Homelab project, serving as the **single source of truth** for all project information. + +## 📖 Wiki Structure + +### Core Documentation +- **`Home.md`** - Main wiki page with overview and navigation +- **`_Sidebar.md`** - Wiki navigation sidebar +- **`_Footer.md`** - Footer with quick links and project info + +### Getting Started +- **`Getting-Started-Guide.md`** - Complete setup instructions +- **`Environment-Configuration.md`** - Required settings and tokens +- **`Automated-Setup.md`** - One-click deployment process +- **`Manual-Setup.md`** - Step-by-step manual installation +- **`Post-Setup-Guide.md`** - Post-deployment configuration + +### Architecture & Design +- **`System-Architecture.md`** - High-level component overview +- **`Docker-Guidelines.md`** - Service management patterns +- **`Ports-in-Use.md`** - Complete port mapping reference +- **`SSL-Certificates.md`** - HTTPS and certificate management + +### Services & Documentation +- **`Services-Overview.md`** - All 50+ services catalog +- **`Service-Documentation.md`** - Individual service guides index +- **`service-docs/`** - Individual service documentation files +- **`Core-Infrastructure.md`** - Essential services guide +- **`Infrastructure-Services.md`** - Management tools guide + +### Operations & Management +- **`Quick-Reference.md`** - Command cheat sheet +- **`Backup-Strategy.md`** - Restic + Backrest comprehensive guide +- **`Proxying-External-Hosts.md`** - Connect non-Docker services +- **`Resource-Limits-Template.md`** - Performance optimization +- **`troubleshooting/`** - Issue resolution guides + +### AI & Automation +- **`AI-Management-Guide.md`** - Using AI for homelab management +- **`Copilot-Instructions.md`** - AI assistant configuration +- **`AI-VS-Code-Setup.md`** - Development environment setup +- **`AI-Management-Prompts.md`** - Sample AI interactions + +### Additional Resources +- **`How-It-Works.md`** - System architecture explanation +- **`Authelia-Customization.md`** - SSO configuration options +- **`On-Demand-Remote-Services.md`** - Lazy loading configuration +- **`action-reports/`** - Deployment logs and reports + +## 🎯 Purpose + +This wiki serves as the **authoritative source of truth** for the EZ-Homelab project, containing: + +- ✅ **Complete Documentation** - All setup guides, configuration options, and troubleshooting +- ✅ **Service Catalog** - Detailed information for all 50+ available services +- ✅ **Architecture Guides** - System design, network configuration, and security models +- ✅ **AI Integration** - Copilot instructions and AI management capabilities +- ✅ **Operational Guides** - Backup strategies, monitoring, and maintenance +- ✅ **Reference Materials** - Port mappings, resource limits, and quick references + +## 📋 Wiki Standards + +### Naming Convention +- Use `Title-Case-With-Dashes.md` for file names +- Match wiki link format: `[[Wiki Links]]` +- Descriptive, searchable titles + +### Content Organization +- **Headers**: Use `# ## ###` hierarchy +- **Links**: Use `[[Wiki Links]]` for internal references +- **Code**: Use backticks for commands and file paths +- **Lists**: Use bullet points for features/options + +### Maintenance +- **Single Source of Truth**: All information kept current +- **Comprehensive**: No missing critical information +- **Accurate**: Verified configurations and commands +- **Accessible**: Clear language, logical organization + +## 🔄 Synchronization + +This wiki is automatically synchronized with the main documentation in `../docs/` and should be updated whenever: + +- New services are added +- Configuration changes are made +- Documentation is updated +- New features are implemented + +## 📖 Usage + +### For Users +- Start with `Home.md` for overview +- Use `_Sidebar.md` for navigation +- Search for specific topics or services +- Reference individual service documentation + +### For Contributors +- Update wiki when modifying documentation +- Add new pages for new features +- Maintain link integrity +- Keep information current + +### For AI Management +- Copilot uses this wiki as reference +- Contains complete system knowledge +- Provides context for AI assistance +- Enables intelligent homelab management + +## 🤝 Contributing + +When contributing to the wiki: + +1. **Update Content**: Modify relevant pages with new information +2. **Check Links**: Ensure all internal links work +3. **Update Navigation**: Add new pages to `_Sidebar.md` if needed +4. **Verify Accuracy**: Test commands and configurations +5. **Maintain Standards**: Follow naming and formatting conventions + +## 📊 Wiki Statistics + +- **Total Pages**: 25+ main pages +- **Service Docs**: 50+ individual service guides +- **Categories**: 10 service categories +- **Topics Covered**: Setup, configuration, troubleshooting, architecture +- **Last Updated**: January 21, 2026 + +--- + +*This wiki represents the complete knowledge base for the EZ-Homelab project and serves as the primary reference for all users and contributors.* + +### 📦 Services & Stacks + +#### Core Infrastructure (Deploy First) +Essential services that everything else depends on: +- **[DuckDNS](service-docs/duckdns.md)** - Dynamic DNS updates +- **[Traefik](service-docs/traefik.md)** - Reverse proxy & SSL termination +- **[Authelia](service-docs/authelia.md)** - Single Sign-On authentication +- **[Gluetun](service-docs/gluetun.md)** - VPN client for secure downloads +- **[Sablier](service-docs/sablier.md)** - Lazy loading service for on-demand containers + +#### Management & Monitoring +- **[Dockge](service-docs/dockge.md)** - Primary stack management UI +- **[Homepage](service-docs/homepage.md)** - Service dashboard (AI-configurable) +- **[Homarr](service-docs/homarr.md)** - Alternative modern dashboard +- **[Dozzle](service-docs/dozzle.md)** - Real-time log viewer +- **[Glances](service-docs/glances.md)** - System monitoring +- **[Pi-hole](service-docs/pihole.md)** - DNS & ad blocking + +#### Media Services +- **[Jellyfin](service-docs/jellyfin.md)** - Open-source media streaming +- **[Plex](service-docs/plex.md)** - Popular media server (alternative) +- **[qBittorrent](service-docs/qbittorrent.md)** - Torrent client (VPN-routed) +- **[Calibre-Web](service-docs/calibre-web.md)** - Ebook reader & server + +#### Media Management (Arr Stack) +- **[Sonarr](service-docs/sonarr.md)** - TV show automation +- **[Radarr](service-docs/radarr.md)** - Movie automation +- **[Prowlarr](service-docs/prowlarr.md)** - Indexer management +- **[Readarr](service-docs/readarr.md)** - Ebook/audiobook automation +- **[Lidarr](service-docs/lidarr.md)** - Music library management +- **[Bazarr](service-docs/bazarr.md)** - Subtitle automation +- **[Jellyseerr](service-docs/jellyseerr.md)** - Media request interface + +#### Home Automation +- **[Home Assistant](service-docs/home-assistant.md)** - Smart home platform +- **[Node-RED](service-docs/node-red.md)** - Flow-based programming +- **[Zigbee2MQTT](service-docs/zigbee2mqtt.md)** - Zigbee device integration +- **[ESPHome](service-docs/esphome.md)** - ESP device firmware +- **[TasmoAdmin](service-docs/tasmoadmin.md)** - Tasmota device management +- **[MotionEye](service-docs/motioneye.md)** - Video surveillance + +#### Productivity & Collaboration +- **[Nextcloud](service-docs/nextcloud.md)** - Self-hosted cloud storage +- **[Gitea](service-docs/gitea.md)** - Git service (GitHub alternative) +- **[BookStack](service-docs/bookstack.md)** - Documentation/wiki platform +- **[WordPress](service-docs/wordpress.md)** - Blog/CMS platform +- **[MediaWiki](service-docs/mediawiki.md)** - Wiki platform +- **[DokuWiki](service-docs/dokuwiki.md)** - Simple wiki +- **[Excalidraw](service-docs/excalidraw.md)** - Collaborative drawing + +#### Development Tools +- **[Code Server](service-docs/code-server.md)** - VS Code in the browser +- **[GitLab](service-docs/gitlab.md)** - Complete DevOps platform +- **[Jupyter](service-docs/jupyter.md)** - Interactive computing +- **[pgAdmin](service-docs/pgadmin.md)** - PostgreSQL administration + +#### Monitoring & Observability +- **[Grafana](service-docs/grafana.md)** - Metrics visualization +- **[Prometheus](service-docs/prometheus.md)** - Metrics collection +- **[Uptime Kuma](service-docs/uptime-kuma.md)** - Uptime monitoring +- **[Loki](service-docs/loki.md)** - Log aggregation +- **[Promtail](service-docs/promtail.md)** - Log shipping +- **[Node Exporter](service-docs/node-exporter.md)** - System metrics +- **[cAdvisor](service-docs/cadvisor.md)** - Container metrics + +#### Utilities & Tools +- **[Backrest](service-docs/backrest.md)** - Backup management (Restic-based, default) +- **[Duplicati](service-docs/duplicati.md)** - Alternative backup solution +- **[FreshRSS](service-docs/freshrss.md)** - RSS feed reader +- **[Wallabag](service-docs/wallabag.md)** - Read-it-later service +- **[Watchtower](service-docs/watchtower.md)** - Automatic updates +- **[Vaultwarden](service-docs/vaultwarden.md)** - Password manager + +#### Alternative Services +Services that provide alternatives to the defaults: +- **[Portainer](service-docs/portainer.md)** - Alternative container management +- **[Authentik](service-docs/authentik.md)** - Alternative SSO with web UI + +### 🛠️ Development & Operations + +#### Docker & Container Management +- **[Docker Guidelines](docker-guidelines.md)** - Complete service management guide +- **[Service Creation](docker-guidelines.md#service-creation-guidelines)** - How to add new services +- **[Service Modification](docker-guidelines.md#service-modification-guidelines)** - Updating existing services +- **[Resource Limits](resource-limits-template.md)** - CPU/memory management +- **[Troubleshooting](docker-guidelines.md#troubleshooting)** - Common issues & fixes + +#### External Service Integration +- **[Proxying External Hosts](proxying-external-hosts.md)** - Route non-Docker services through Traefik +- **[External Host Examples](proxying-external-hosts.md#common-external-services-to-proxy)** - Raspberry Pi, NAS, etc. + +#### AI & Automation +- **[Copilot Instructions](.github/copilot-instructions.md)** - AI agent guidelines for this codebase +- **[AI Management Capabilities](.github/copilot-instructions.md#ai-management-capabilities)** - What the AI can help with + +### 📋 Quick References + +#### Commands & Operations +- **[Quick Reference](quick-reference.md)** - Essential commands and workflows +- **[Stack Management](quick-reference.md#service-management)** - Start/stop/restart services +- **[Deployment Scripts](quick-reference.md#deployment-scripts)** - Setup and deployment automation + +#### Troubleshooting +- **[Common Issues](quick-reference.md#troubleshooting)** - SSL, networking, permissions +- **[Service Won't Start](quick-reference.md#service-wont-start)** - Debugging steps +- **[Traefik Routing](quick-reference.md#traefik-not-routing)** - Route configuration issues +- **[VPN Problems](quick-reference.md#vpn-not-working-gluetun)** - Gluetun troubleshooting + +### 📖 Advanced Topics + +#### SSL & Certificates +- **[Wildcard SSL Setup](getting-started.md#notes-about-ssl-certificates-from-letsencrypt-with-duckdns)** - How SSL certificates work +- **[Certificate Troubleshooting](getting-started.md#certificate-troubleshooting)** - SSL issues and fixes +- **[DNS Challenge Process](getting-started.md#dns-challenge-process)** - How domain validation works + +#### Security & Access Control +- **[Authelia Configuration](service-docs/authelia.md)** - SSO setup and customization +- **[Bypass Rules](docker-guidelines.md#when-to-use-authelia-sso)** - When to skip authentication +- **[2FA Setup](getting-started.md#set-up-2fa-with-authelia)** - Two-factor authentication + +#### Backup & Recovery +- **[Backup Strategies](service-docs/duplicati.md)** - Data protection approaches +- **[Service Backups](service-docs/backrest.md)** - Database backup solutions +- **[Configuration Backup](quick-reference.md#backup-commands)** - Config file preservation + +### 🔧 Development & Contributing + +#### Repository Structure +- **[File Organization](.github/copilot-instructions.md#file-structure-standards)** - How files are organized +- **[Service Documentation](service-docs/)** - Individual service guides +- **[Configuration Templates](config-templates/)** - Reusable configurations +- **[Scripts](scripts/)** - Automation and deployment tools + +#### Development Workflow +- **[Adding Services](docker-guidelines.md#service-creation-guidelines)** - New service integration +- **[Testing Changes](.github/copilot-instructions.md#testing-changes)** - Validation procedures +- **[Resource Limits](resource-limits-template.md)** - Performance management + +### 📚 Additional Resources + +- **[GitHub Repository](https://github.com/kelinfoxy/EZ-Homelab)** - Source code and issues +- **[Docker Hub](https://hub.docker.com)** - Container images +- **[Traefik Documentation](https://doc.traefik.io/traefik/)** - Official reverse proxy docs +- **[Authelia Documentation](https://www.authelia.com/)** - SSO documentation +- **[DuckDNS](https://www.duckdns.org/)** - Dynamic DNS service + +--- + +## 🎯 Quick Navigation + +**New to EZ-Homelab?** → [Getting Started](getting-started.md) + +**Need to add a service?** → [Service Creation Guide](docker-guidelines.md#service-creation-guidelines) + +**Having issues?** → [Troubleshooting](quick-reference.md#troubleshooting) + +**Want to contribute?** → [Development Workflow](docker-guidelines.md#service-creation-guidelines) + +--- + +*This documentation is maintained by AI and community contributors. Last updated: January 20, 2026* \ No newline at end of file diff --git a/wiki-update/Service-Documentation.md b/wiki-update/Service-Documentation.md new file mode 100644 index 0000000..0027bb6 --- /dev/null +++ b/wiki-update/Service-Documentation.md @@ -0,0 +1,199 @@ +# Service Documentation + +## Overview + +This section contains detailed documentation for all 50+ services available in the EZ-Homelab. Each service has its own documentation page with setup instructions, configuration options, and troubleshooting guides. + +## Service Categories + +### Core Infrastructure (Essential - Deploy First) +- [[DuckDNS]] - Dynamic DNS with wildcard SSL +- [[Traefik]] - Reverse proxy and SSL termination +- [[Authelia]] - Single Sign-On authentication +- [[Gluetun]] - VPN client for secure downloads +- [[Sablier]] - Lazy loading service + +### Infrastructure & Management +- [[Dockge]] - Primary stack management UI +- [[Portainer]] - Advanced container management +- [[Authentik]] - Alternative SSO with web UI +- [[Pi-hole]] - DNS and ad blocking +- [[Dozzle]] - Real-time log viewer +- [[Glances]] - System monitoring +- [[Watchtower]] - Automatic updates +- [[Docker Proxy]] - Secure Docker API access + +### Dashboards & Interfaces +- [[Homepage]] - Service dashboard (AI-configurable) +- [[Homarr]] - Modern dashboard alternative + +### Media Services +- [[Plex]] - Popular media server +- [[Jellyfin]] - Open-source media streaming +- [[Calibre-Web]] - Ebook reader and server + +### Media Management (*Arr Stack) +- [[Sonarr]] - TV show automation +- [[Radarr]] - Movie automation +- [[Prowlarr]] - Indexer management +- [[Readarr]] - Ebook/audiobook automation +- [[Lidarr]] - Music management +- [[Bazarr]] - Subtitle management +- [[Mylar3]] - Comic book management +- [[Lazy Librarian]] - Book automation + +### Download Services +- [[qBittorrent]] - Torrent client (VPN-routed) +- [[FlareSolverr]] - Cloudflare bypass for indexers + +### Home Automation +- [[Home Assistant]] - Smart home platform +- [[ESPHome]] - ESP device firmware +- [[TasmoAdmin]] - Tasmota device management +- [[Node-RED]] - Automation workflows +- [[Mosquitto]] - MQTT broker +- [[Zigbee2MQTT]] - Zigbee bridge +- [[MotionEye]] - Video surveillance + +### Productivity & Collaboration +- [[Nextcloud]] - File sync and collaboration +- [[Gitea]] - Git service +- [[BookStack]] - Documentation platform +- [[DokuWiki]] - Wiki platform +- [[MediaWiki]] - Advanced wiki +- [[WordPress]] - Blog platform +- [[Form.io]] - Form builder + +### Development Tools +- [[GitLab]] - Complete DevOps platform +- [[PostgreSQL]] - SQL database +- [[Redis]] - In-memory data store +- [[pgAdmin]] - PostgreSQL management +- [[Jupyter Lab]] - Interactive notebooks +- [[Code Server]] - VS Code in browser + +### Monitoring & Observability +- [[Prometheus]] - Metrics collection +- [[Grafana]] - Visualization and dashboards +- [[Loki]] - Log aggregation +- [[Promtail]] - Log shipping +- [[Node Exporter]] - System metrics +- [[cAdvisor]] - Container metrics +- [[Alertmanager]] - Alert management +- [[Uptime Kuma]] - Uptime monitoring + +### Utilities & Tools +- [[Vaultwarden]] - Password manager +- [[Duplicati]] - Encrypted backups +- [[Backrest]] - Restic backup UI +- [[FreshRSS]] - RSS feed reader +- [[Wallabag]] - Read-it-later service +- [[Unmanic]] - Media optimization +- [[Tdarr]] - Video transcoding +- [[Jellyseerr]] - Media requests + +## Documentation Structure + +Each service documentation page includes: + +### 📋 Service Information +- **Purpose**: What the service does +- **URL**: Access URL after deployment +- **Authentication**: SSO protection status +- **Dependencies**: Required services or configurations + +### ⚙️ Configuration +- **Environment Variables**: Required settings +- **Volumes**: Data persistence configuration +- **Networks**: Docker network connections +- **Ports**: Internal port mappings + +### 🚀 Deployment +- **Stack Location**: Where to deploy +- **Compose File**: Docker Compose configuration +- **Resource Limits**: Recommended CPU/memory limits +- **Health Checks**: Service health verification + +### 🔧 Management +- **Updates**: How to update the service +- **Backups**: Data backup procedures +- **Monitoring**: Health check commands +- **Logs**: Log location and viewing + +### 🐛 Troubleshooting +- **Common Issues**: Frequent problems and solutions +- **Error Messages**: Specific error resolution +- **Performance**: Optimization tips +- **Recovery**: Service restoration procedures + +## Quick Reference + +### By Port Number +- **3000**: Grafana, Homarr, Gitea +- **3001**: Uptime Kuma +- **5050**: pgAdmin +- **5055**: Jellyseerr +- **8080**: Code Server, Nextcloud, Traefik dashboard +- **8081**: qBittorrent, MotionEye +- **8083**: Calibre-Web +- **8096**: Jellyfin +- **8123**: Home Assistant, Zigbee2MQTT +- **8200**: Duplicati +- **8888**: Jupyter Lab +- **8989**: Sonarr +- **9090**: Prometheus +- **9696**: Prowlarr +- **9700**: FlareSolverr + +### By Category +- **Media Streaming**: Plex (32400), Jellyfin (8096) +- **Automation**: Sonarr (8989), Radarr (7878), Prowlarr (9696) +- **Databases**: PostgreSQL (5432), MariaDB (3306), Redis (6379) +- **Development**: GitLab (80/443), Gitea (3000), Code Server (8080) +- **Monitoring**: Grafana (3000), Prometheus (9090), Uptime Kuma (3001) + +## Deployment Guidelines + +### Service Dependencies +Some services require others to be running first: + +**Required First:** +- Core Infrastructure (DuckDNS, Traefik, Authelia) + +**Common Dependencies:** +- **Databases**: PostgreSQL, MariaDB, Redis for data persistence +- **VPN**: Gluetun for download services +- **Reverse Proxy**: Traefik for all web services +- **Authentication**: Authelia for SSO protection + +### Resource Requirements +- **Lightweight** (< 256MB RAM): DNS, monitoring, authentication +- **Standard** (256MB - 1GB RAM): Web apps, dashboards, simple services +- **Heavy** (> 1GB RAM): Media servers, databases, development tools +- **Specialized**: GPU-enabled services, high-I/O applications + +### Network Security +- **SSO Protected**: Most services require Authelia authentication +- **Bypass Allowed**: Media services (Plex, Jellyfin) for app access +- **VPN Routed**: Download services for IP protection +- **Internal Only**: Databases and supporting services + +## Finding Service Documentation + +### By Service Name +Use the alphabetical list above or search for the specific service. + +### By Function +- **Want to stream media?** → [[Plex]], [[Jellyfin]] +- **Need automation?** → [[Sonarr]], [[Radarr]], [[Prowlarr]] +- **File sharing?** → [[Nextcloud]], [[Gitea]] +- **Monitoring?** → [[Grafana]], [[Prometheus]], [[Uptime Kuma]] +- **Development?** → [[GitLab]], [[Code Server]], [[Jupyter Lab]] + +### By Complexity +- **Beginner**: Homepage, Dozzle, Glances +- **Intermediate**: Nextcloud, Gitea, BookStack +- **Advanced**: GitLab, Home Assistant, Prometheus + +Each service page provides complete setup instructions and is designed to work with the EZ-Homelab's file-based, AI-manageable architecture. +c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\Service-Documentation.md \ No newline at end of file diff --git a/wiki-update/Services-Overview.md b/wiki-update/Services-Overview.md new file mode 100644 index 0000000..7318c4b --- /dev/null +++ b/wiki-update/Services-Overview.md @@ -0,0 +1,229 @@ +# Services Overview + +This document provides a comprehensive overview of all 50+ pre-configured services available in the AI-Homelab repository. + +## Services Overview + +| Stacks (12) | Services (50 + 6db) | SSO | Storage | Access URLs | +|-------|----------|-----|---------|-------------| +| **🔀 alternatives.yaml** (6 + 3 DBs) | | | | | +| ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/alternatives | dockge.${DOMAIN} | +| ├─ Portainer | Container management | ✓ | /opt/stacks/alternatives | portainer.${DOMAIN} | +| ├─ Authentik Server | SSO with web UI | ✓ | /opt/stacks/alternatives | authentik.${DOMAIN} | +| │ ├─ authentik-worker | Background tasks | - | /opt/stacks/alternatives | No UI | +| │ ├─ authentik-db | PostgreSQL | - | /opt/stacks/alternatives | No UI | +| │ └─ authentik-redis | Cache/messaging | - | /opt/stacks/alternatives | No UI | +| └─ Plex | Media server | ✗ | /mnt/media, /mnt/transcode | plex.${DOMAIN} | +| **📦 core.yaml (4)** | **Deploy First** | | | | +| ├─ DuckDNS | Dynamic DNS updater | - | /opt/stacks/core/duckdns | No UI | +| ├─ Traefik | Reverse proxy + SSL | ✓ | /opt/stacks/core/traefik | traefik.${DOMAIN} | +| ├─ Authelia | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} | +| └─ Sablier | Lazy loading service | - | /opt/stacks/core/sablier | No UI | +| **📊 dashboards.yaml** (2) | | | | | +| ├─ Homepage | App dashboard (AI cfg) | ✓ | /opt/stacks/dashboards | home.${DOMAIN} | +| └─ Homarr | Modern dashboard | ✓ | /opt/stacks/dashboards | homarr.${DOMAIN} | +| **🏠 homeassistant.yaml** (7) | | | | | +| ├─ Home Assistant | HA platform | ✗ | /opt/stacks/homeassistant | ha.${DOMAIN} | +| ├─ ESPHome | ESP firmware mgr | ✓ | /opt/stacks/homeassistant | esphome.${DOMAIN} | +| ├─ TasmoAdmin | Tasmota device mgr | ✓ | /opt/stacks/homeassistant | tasmoadmin.${DOMAIN} | +| ├─ Node-RED | Automation flows | ✓ | /opt/stacks/homeassistant | nodered.${DOMAIN} | +| ├─ Mosquitto | MQTT broker | - | /opt/stacks/homeassistant | Ports 1883, 9001 | +| ├─ Zigbee2MQTT | Zigbee bridge | ✓ | /opt/stacks/homeassistant | zigbee2mqtt.${DOMAIN} | +| └─ MotionEye | Video surveillance | ✓ | /opt/stacks/homeassistant, /mnt/surveillance | motioneye.${DOMAIN} | +| **🔧 infrastructure.yaml** (6)** | | | | | +| ├─ Pi-hole | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} | +| ├─ Watchtower | Auto container updates | - | /opt/stacks/infrastructure | No UI | +| ├─ Dozzle | Docker log viewer | ✓ | /opt/stacks/infrastructure | dozzle.${DOMAIN} | +| ├─ Glances | System monitoring | ✓ | /opt/stacks/infrastructure | glances.${DOMAIN} | +| ├─ Code Server | VS Code in browser | ✓ | /opt/stacks/infrastructure | code.${DOMAIN} | +| └─ Docker Proxy | Secure socket access | - | /opt/stacks/infrastructure | No UI | +| **📺 media-management.yaml** (9) | | | | | +| ├─ Sonarr | TV automation | ✓ | /opt/stacks/media-management, /mnt/media | sonarr.${DOMAIN} | +| ├─ Radarr | Movie automation | ✓ | /opt/stacks/media-management, /mnt/media | radarr.${DOMAIN} | +| ├─ Prowlarr | Indexer manager | ✓ | /opt/stacks/media-management | prowlarr.${DOMAIN} | +| ├─ Readarr | Ebooks/Audiobooks | ✓ | /opt/stacks/media-management, /mnt/media | readarr.${DOMAIN} | +| ├─ Lidarr | Music manager | ✓ | /opt/stacks/media-management, /mnt/media | lidarr.${DOMAIN} | +| ├─ Lazy Librarian | Book automation | ✓ | /opt/stacks/media-management, /mnt/media | lazylibrarian.${DOMAIN} | +| ├─ Mylar3 | Comic manager | ✓ | /opt/stacks/media-management, /mnt/media | mylar.${DOMAIN} | +| ├─ Jellyseerr | Media requests | ✓ | /opt/stacks/media-management | jellyseerr.${DOMAIN} | +| └─ FlareSolverr | Cloudflare bypass | - | /opt/stacks/media-management | No UI | +| **🎬 media.yaml** (2) | | | | | +| ├─ Jellyfin | Media server (OSS) | ✗ | /mnt/media, /mnt/transcode | jellyfin.${DOMAIN} | +| └─ Calibre-Web | Ebook reader | ✓ | /opt/stacks/media, /mnt/media | calibre.${DOMAIN} | +| **📈 monitoring.yaml** (8) | | | | | +| ├─ Prometheus | Metrics collection | ✓ | /opt/stacks/monitoring | prometheus.${DOMAIN} | +| ├─ Grafana | Visualization | ✓ | /opt/stacks/monitoring | grafana.${DOMAIN} | +| ├─ Loki | Log aggregation | - | /opt/stacks/monitoring | Via Grafana | +| ├─ Promtail | Log shipper | - | /opt/stacks/monitoring | No UI | +| ├─ Node Exporter | Host metrics | - | /opt/stacks/monitoring | No UI | +| ├─ cAdvisor | Container metrics | - | /opt/stacks/monitoring | Internal :8080 | +| └─ Uptime Kuma | Uptime monitoring | ✓ | /opt/stacks/monitoring | status.${DOMAIN} | +| **💼 productivity.yaml** (5 + 4 DBs) | | | | | +| ├─ Nextcloud | File sync platform | ✓ | /opt/stacks/productivity, /mnt/nextcloud | nextcloud.${DOMAIN} | +| │ └─ nextcloud-db | MariaDB | - | /opt/stacks/productivity | No UI | +| ├─ Mealie | Recipe manager | ✗ | /opt/stacks/productivity | mealie.${DOMAIN} | +| ├─ WordPress | Blog platform | ✗ | /opt/stacks/productivity | blog.${DOMAIN} | +| │ └─ wordpress-db | MariaDB | - | /opt/stacks/productivity | No UI | +| ├─ Gitea | Git service | ✓ | /opt/stacks/productivity, /mnt/git | git.${DOMAIN} | +| │ └─ gitea-db | PostgreSQL | - | /opt/stacks/productivity | No UI | +| └─ Jupyter Lab | Notebooks | ✓ | /opt/stacks/productivity | jupyter.${DOMAIN} | +| **🔄 transcoders.yaml** (3) | | | | | +| ├─ Tdarr Server | Transcoding server | ✓ | /opt/stacks/transcoders, /mnt/transcode | tdarr.${DOMAIN} | +| ├─ Tdarr Node | Transcoding worker | - | /mnt/transcode-cache | No UI | +| └─ Unmanic | Library optimizer | ✓ | /opt/stacks/transcoders, /mnt/transcode | unmanic.${DOMAIN} | +| **🛠️ utilities.yaml** (7) | | | | | +| ├─ Vaultwarden | Password manager | ✗ | /opt/stacks/utilities | bitwarden.${DOMAIN} | +| ├─ Backrest | Backup (restic) | ✓ | /opt/stacks/utilities, /mnt/backups | backrest.${DOMAIN} | +| ├─ Duplicati | Encrypted backups | ✓ | /opt/stacks/utilities, /mnt/backups | duplicati.${DOMAIN} | +| ├─ Code Server | VS Code in browser | ✓ | /opt/stacks/utilities | code.${DOMAIN} | +| ├─ Form.io | Form platform | ✓ | /opt/stacks/utilities | forms.${DOMAIN} | +| │ └─ formio-mongo | MongoDB | - | /opt/stacks/utilities | No UI | +| └─ Authelia-Redis | Session storage | - | /opt/stacks/utilities | No UI | +| **🔒 vpn.yaml (2)** | **VPN Services** | | | | +| ├─ Gluetun | VPN (Surfshark) | - | /opt/stacks/vpn/gluetun | No UI | +| └─ qBittorrent | Torrent (via VPN) | ✓ | /mnt/downloads | qbit.${DOMAIN} | +| **📖 wikis.yaml** (4) | | | | | +| ├─ DokuWiki | File-based wiki | ✓ | /opt/stacks/wikis | dokuwiki.${DOMAIN} | +| ├─ BookStack | Documentation | ✓ | /opt/stacks/wikis | docs.${DOMAIN} | +| │ └─ bookstack-db | MariaDB | - | /opt/stacks/wikis | No UI | +| └─ MediaWiki | Wiki platform | ✓ | /opt/stacks/wikis | mediawiki.${DOMAIN} | + +**Legend:** ✓ = Protected by SSO | ✗ = Bypasses SSO | - = No web UI + +## Quick Deployment Order + +1. **Create Networks** (one-time setup) + ```bash + docker network create traefik-network + docker network create homelab-network + docker network create dockerproxy-network + ``` + +2. **Deploy Core Stack** (required first) + ```bash + cd /opt/stacks/core/ + docker compose up -d + ``` + +3. **Deploy Infrastructure** + ```bash + cd /opt/stacks/infrastructure/ + docker compose up -d + ``` + +4. **Deploy Dashboards** + ```bash + cd /opt/stacks/dashboards/ + docker compose up -d + ``` + +5. **Deploy Additional Stacks** (as needed) + - Alternatives: `/opt/stacks/alternatives/` + - Core: `/opt/stacks/core/` (deploy first) + - Dashboards: `/opt/stacks/dashboards/` + - Home Automation: `/opt/stacks/homeassistant/` + - Infrastructure: `/opt/stacks/infrastructure/` + - Media: `/opt/stacks/media/` + - Media Management: `/opt/stacks/media-management/` + - Monitoring: `/opt/stacks/monitoring/` + - Productivity: `/opt/stacks/productivity/` + - Transcoders: `/opt/stacks/transcoders/` + - Utilities: `/opt/stacks/utilities/` + - VPN: `/opt/stacks/vpn/` + - Wikis: `/opt/stacks/wikis/` + +## Toggling SSO (Authelia) On/Off + +You can easily enable or disable SSO protection for any service by modifying its Traefik labels in the docker-compose.yml file. + +### To Enable SSO on a Service + +Add the Authelia middleware to the service's Traefik labels: + +```yaml +labels: + - "traefik.enable=true" + - "traefik.http.routers.servicename.rule=Host(`servicename.${DOMAIN}`)" + - "traefik.http.routers.servicename.entrypoints=websecure" + - "traefik.http.routers.servicename.tls.certresolver=letsencrypt" + - "traefik.http.routers.servicename.middlewares=authelia@docker" # ← Add this line + - "traefik.http.services.servicename.loadbalancer.server.port=8080" +``` + +### To Disable SSO on a Service + +Comment out (don't remove) the middleware line: + +```yaml +labels: + - "traefik.enable=true" + - "traefik.http.routers.servicename.rule=Host(`servicename.${DOMAIN}`)" + - "traefik.http.routers.servicename.entrypoints=websecure" + - "traefik.http.routers.servicename.tls.certresolver=letsencrypt" + # - "traefik.http.routers.servicename.middlewares=authelia@docker" # ← Commented out (not removed) + - "traefik.http.services.servicename.loadbalancer.server.port=8080" +``` + +After making changes, redeploy the service: + +```bash +# From inside the stack directory +cd /opt/stacks/stack-name/ +docker compose up -d + +# Or from anywhere, using the full path +docker compose -f /opt/stacks/stack-name/docker-compose.yml up -d +``` + +**Stopping a Service:** + +```bash +# From inside the stack directory +cd /opt/stacks/stack-name/ +docker compose down + +# Or from anywhere, using the full path +docker compose -f /opt/stacks/stack-name/docker-compose.yml down +``` + +**Use Cases for Development/Production:** +- **Security First**: All services start with SSO enabled by default for maximum security +- **Development**: Keep SSO enabled to protect services during testing +- **Production**: Disable SSO only for services needing direct app/API access (Plex, Jellyfin) +- **Gradual Exposure**: Comment out SSO only when ready to expose a service +- **Quick Toggle**: AI assistant can modify these labels automatically when you ask + +## Storage Recommendations + +| Data Type | Recommended Location | Reason | +|-----------|---------------------|--------| +| Configuration files | `/opt/stacks/stack-name/` | Easy access, version control | +| Small databases (< 10GB) | `/opt/stacks/stack-name/db/` | Manageable on system drive | +| Media files (movies, TV, music) | `/mnt/media/` | Large, continuous growth | +| Downloads | `/mnt/downloads/` | Temporary, high throughput | +| Backups | `/mnt/backups/` | Large, separate from system | +| Surveillance footage | `/mnt/surveillance/` | Continuous recording | +| Large databases (> 10GB) | `/mnt/databases/` | Growth over time | +| Transcoding cache | `/mnt/transcode-cache/` | High I/O, large temporary files | +| Git repositories | `/mnt/git/` | Can grow large | +| Nextcloud data | `/mnt/nextcloud/` | User files, photos | + +## Configuration Templates + +All configuration templates are available in `config-templates/`: +- `traefik/` - Static and dynamic Traefik configuration +- `authelia/` - Complete Authelia setup with user database +- `homepage/` - Dashboard services, widgets, and Docker integration +- `prometheus/` - Metrics scrape configurations +- `loki/` - Log aggregation settings +- `promtail/` - Log shipping configuration +- `redis/` - Redis server configuration + +## Additional Resources + +- **Getting Started**: See [docs/getting-started.md](getting-started.md) for detailed deployment +- **Docker Guidelines**: See [docs/docker-guidelines.md](docker-guidelines.md) for management patterns +- **Quick Reference**: See [docs/quick-reference.md](quick-reference.md) for common commands +- **Proxying External Hosts**: See [docs/proxying-external-hosts.md](proxying-external-hosts.md) for Raspberry Pi, NAS, etc. +- **AI Assistant**: Use GitHub Copilot in VS Code with `.github/copilot-instructions.md` for intelligent homelab management +