diff --git a/wiki-check/Home.md b/wiki-check/Home.md deleted file mode 100644 index d4e322d..0000000 --- a/wiki-check/Home.md +++ /dev/null @@ -1,146 +0,0 @@ -# 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 deleted file mode 100644 index 52291d5..0000000 --- a/wiki-check/_Sidebar.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 deleted file mode 100644 index 5b988e9..0000000 --- a/wiki-update/AI-Management-Guide.md +++ /dev/null @@ -1,299 +0,0 @@ -# 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 deleted file mode 100644 index ddd7571..0000000 --- a/wiki-update/Home.md +++ /dev/null @@ -1,146 +0,0 @@ -# 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 deleted file mode 100644 index 8820818..0000000 --- a/wiki-update/README.md +++ /dev/null @@ -1,292 +0,0 @@ -# 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 deleted file mode 100644 index 0027bb6..0000000 --- a/wiki-update/Service-Documentation.md +++ /dev/null @@ -1,199 +0,0 @@ -# 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 deleted file mode 100644 index 7318c4b..0000000 --- a/wiki-update/Services-Overview.md +++ /dev/null @@ -1,229 +0,0 @@ -# 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 -