wiki update
This commit is contained in:
kelinfoxy
@@ -4,9 +4,9 @@ This document provides a comprehensive overview of all 50+ pre-configured servic
|
|||||||
|
|
||||||
## Services Overview
|
## Services Overview
|
||||||
|
|
||||||
| Stacks (12) | Services (70 + 6db) | SSO | Storage | Access URLs |
|
| Stacks (12) | Services (50 + 6db) | SSO | Storage | Access URLs |
|
||||||
|-------|----------|-----|---------|-------------|
|
|-------|----------|-----|---------|-------------|
|
||||||
| **<EFBFBD> alternatives.yaml** (6 + 3 DBs) | | | | |
|
| **🔀 alternatives.yaml** (6 + 3 DBs) | | | | |
|
||||||
| ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/alternatives | dockge.${DOMAIN} |
|
| ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/alternatives | dockge.${DOMAIN} |
|
||||||
| ├─ Portainer | Container management | ✓ | /opt/stacks/alternatives | portainer.${DOMAIN} |
|
| ├─ Portainer | Container management | ✓ | /opt/stacks/alternatives | portainer.${DOMAIN} |
|
||||||
| ├─ Authentik Server | SSO with web UI | ✓ | /opt/stacks/alternatives | authentik.${DOMAIN} |
|
| ├─ Authentik Server | SSO with web UI | ✓ | /opt/stacks/alternatives | authentik.${DOMAIN} |
|
||||||
|
|||||||
146
wiki-check/Home.md
Normal file
146
wiki-check/Home.md
Normal file
@@ -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!
|
||||||
|
|
||||||
|
[](https://docker.com)
|
||||||
|
[](https://traefik.io)
|
||||||
|
[](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.*</content>
|
||||||
|
<parameter name="filePath">c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\Home.md
|
||||||
54
wiki-check/_Sidebar.md
Normal file
54
wiki-check/_Sidebar.md
Normal file
@@ -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.*</content>
|
||||||
|
<parameter name="filePath">c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\_Sidebar.md
|
||||||
299
wiki-update/AI-Management-Guide.md
Normal file
299
wiki-update/AI-Management-Guide.md
Normal file
@@ -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.</content>
|
||||||
|
<parameter name="filePath">c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\AI-Management-Guide.md
|
||||||
146
wiki-update/Home.md
Normal file
146
wiki-update/Home.md
Normal file
@@ -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!
|
||||||
|
|
||||||
|
[](https://docker.com)
|
||||||
|
[](https://traefik.io)
|
||||||
|
[](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.*</content>
|
||||||
|
<parameter name="filePath">c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\Home.md
|
||||||
292
wiki-update/README.md
Normal file
292
wiki-update/README.md
Normal file
@@ -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*
|
||||||
199
wiki-update/Service-Documentation.md
Normal file
199
wiki-update/Service-Documentation.md
Normal file
@@ -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.</content>
|
||||||
|
<parameter name="filePath">c:\Users\kelin\Documents\Apps\GitHub\AI-Homelab\wiki\Service-Documentation.md
|
||||||
229
wiki-update/Services-Overview.md
Normal file
229
wiki-update/Services-Overview.md
Normal file
@@ -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
|
||||||
|
|
||||||
Reference in New Issue
Block a user