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

Documentation update

Browse Source
This commit is contained in:
kelinfoxy
2026-01-21 15:54:58 -05:00
parent 47ffc28f0b
commit 2dc6bdec81
7 changed files with 321 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
docs/ai-management-prompts.md Normal file
View File

@@ -0,0 +1,177 @@
# AI Management Prompts
This guide provides example prompts you can use with GitHub Copilot to manage your homelab. These prompts leverage the AI assistant's knowledge of your infrastructure to perform common tasks.
## Container and Stack Management
### Starting Services
- "Start the media stack"
- "Deploy the monitoring services"
- "Launch the productivity applications"
- "Bring up the core infrastructure"
### Stopping Services
- "Stop the media stack"
- "Shut down the monitoring services"
- "Pause the productivity applications"
- "Take down the core infrastructure"
### Restarting Services
- "Restart the media stack"
- "Reload the monitoring services"
- "Reboot the productivity applications"
- "Refresh the core infrastructure"
### Status Checks
- "Show me the status of all containers"
- "Check if the media services are running"
- "List all deployed stacks"
- "Monitor container resource usage"
## Service Configuration
### Adding New Services
- "Add Plex to my media stack"
- "Install Nextcloud for file sharing"
- "Set up Grafana for monitoring"
- "Deploy Home Assistant for automation"
### Modifying Existing Services
- "Change the port for my Plex service"
- "Update the domain for Authelia"
- "Configure VPN routing for qBittorrent"
- "Add SSL certificate for new service"
### Network Configuration
- "Configure Traefik routing for my new service"
- "Set up Authelia protection for admin services"
- "Create external proxy for Raspberry Pi service"
- "Configure Sablier lazy loading"
## Troubleshooting
### Log Analysis
- "Check logs for the media stack"
- "Analyze errors in the monitoring services"
- "Review Traefik routing issues"
- "Examine Authelia authentication problems"
### Performance Issues
- "Monitor resource usage for containers"
- "Check for memory leaks in services"
- "Analyze network connectivity issues"
- "Review disk space usage"
### Configuration Problems
- "Validate Docker Compose syntax"
- "Check environment variable configuration"
- "Verify network connectivity between services"
- "Test SSL certificate validity"
## Backup and Recovery
### Creating Backups
- "Set up backup for my media files"
- "Configure automated backups for databases"
- "Create backup strategy for configurations"
- "Schedule regular system backups"
### Restoring Services
- "Restore from backup after failure"
- "Recover deleted configuration files"
- "Rebuild corrupted database"
- "Restore service from snapshot"
## Monitoring and Maintenance
### System Monitoring
- "Set up Grafana dashboards"
- "Configure Prometheus metrics"
- "Create uptime monitoring"
- "Set up log aggregation"
### Updates and Upgrades
- "Update all containers to latest versions"
- "Upgrade specific service to new version"
- "Check for security updates"
- "Apply system patches"
## Security Management
### Access Control
- "Add new user to Authelia"
- "Configure two-factor authentication"
- "Set up access policies"
- "Manage user permissions"
### SSL and Certificates
- "Renew SSL certificates"
- "Configure wildcard certificates"
- "Set up custom domains"
- "Troubleshoot certificate issues"
## Scaling and Optimization
### Resource Management
- "Optimize container resource limits"
- "Configure GPU access for services"
- "Set up load balancing"
- "Scale services horizontally"
### Storage Management
- "Configure additional storage drives"
- "Set up network storage"
- "Optimize disk usage"
- "Configure backup storage"
## Custom Configurations
### Advanced Setup
- "Create multi-server deployment"
- "Configure external service proxying"
- "Set up VPN routing for downloads"
- "Configure custom networking"
### Integration Tasks
- "Connect services to external APIs"
- "Configure webhook integrations"
- "Set up automated workflows"
- "Create custom monitoring alerts"
## Getting Help
### Documentation
- "Show me the service documentation"
- "Explain how Traefik routing works"
- "Guide me through SSL setup"
- "Help me understand Docker networking"
### Best Practices
- "Review my configuration for security"
- "Optimize my setup for performance"
- "Suggest backup improvements"
- "Recommend monitoring enhancements"
## Prompt Tips
### Be Specific
- Include service names: "Configure Plex, not just media service"
- Specify actions: "Add user" vs "Manage users"
- Mention locations: "In the media stack" vs "Somewhere"
### Provide Context
- "I'm getting error X when doing Y"
- "Service Z isn't starting after configuration change"
- "I need to connect service A to service B"
### Use Natural Language
- "Make my homelab more secure"
- "Help me set up backups"
- "Fix my broken service"
### Follow Up
- "That didn't work, try a different approach"
- "Show me the logs for that service"
- "Explain what that configuration does"
Remember: The AI assistant has full knowledge of your homelab architecture and can perform complex tasks. Start with simple requests and build up to more complex operations as you become comfortable with the system.

130
docs/ai-vscode-setup.md
View File

@@ -1,20 +1,20 @@
# AI-Assisted VS Code Setup # AI-Assisted VS Code Setup
This guide will help you set up VS Code with GitHub Copilot to manage your AI-Homelab using AI assistance. This guide shows you how to use VS Code with GitHub Copilot on your local PC to set up and manage your homelab server remotely. The AI assistant will help you configure your server from scratch.
## Prerequisites ## Prerequisites
- VS Code installed on your local machine - VS Code installed on your local PC
- GitHub Copilot extension installed - GitHub Copilot extension installed
- SSH access to your homelab server - SSH access to your homelab server (fresh Ubuntu/Debian install)
- Basic familiarity with VS Code - Basic familiarity with VS Code
## Step 1: Install Required Extensions ## Step 1: Install Required Extensions
1. Open VS Code 1. Open VS Code on your local PC
2. Go to Extensions (Ctrl+Shift+X) 2. Go to Extensions (Ctrl+Shift+X)
3. Search for and install: 3. Search for and install:
- **GitHub Copilot** (by GitHub) - **GitHub Copilot** (by GitHub) - AI assistant
- **Remote SSH** (by Microsoft) - for connecting to your server - **Remote SSH** (by Microsoft) - for connecting to your server
- **Docker** (by Microsoft) - for Docker support - **Docker** (by Microsoft) - for Docker support
- **YAML** (by Red Hat) - for editing compose files - **YAML** (by Red Hat) - for editing compose files
@@ -26,7 +26,24 @@ This guide will help you set up VS Code with GitHub Copilot to manage your AI-Ho
3. Enter your server's SSH details: `ssh user@your-server-ip` 3. Enter your server's SSH details: `ssh user@your-server-ip`
4. Authenticate with your password or SSH key 4. Authenticate with your password or SSH key
## Step 3: Open the AI-Homelab Repository ## Step 3: Use AI to Set Up Your Server
With VS Code connected to your server, you can now use GitHub Copilot to guide you through the entire setup process:
### Initial Server Setup
- **Clone repository**: Ask Copilot "Help me clone the AI-Homelab repository"
- **Configure environment**: "Guide me through setting up the .env file"
- **Run setup scripts**: "Walk me through running the setup-homelab.sh script"
- **Deploy services**: "Help me run the deployment script"
### AI-Assisted Configuration
The AI will help you:
- Generate secure passwords and API keys
- Configure domain settings and SSL certificates
- Set up user accounts and permissions
- Troubleshoot any issues that arise
## Step 4: Open the AI-Homelab Repository
1. Once connected to your server, open the terminal in VS Code (Ctrl+`) 1. Once connected to your server, open the terminal in VS Code (Ctrl+`)
2. Navigate to your repository: 2. Navigate to your repository:
@@ -35,36 +52,97 @@ This guide will help you set up VS Code with GitHub Copilot to manage your AI-Ho
``` ```
3. Open the folder in VS Code: `File > Open Folder` and select `/home/your-user/AI-Homelab` 3. Open the folder in VS Code: `File > Open Folder` and select `/home/your-user/AI-Homelab`
## Step 4: Enable GitHub Copilot ## Step 5: Enable GitHub Copilot
1. Make sure you're signed into GitHub in VS Code 1. Make sure you're signed into GitHub in VS Code
2. GitHub Copilot should activate automatically 2. GitHub Copilot should activate automatically
3. You can test it by opening a file and typing a comment or code 3. You can test it by opening a file and typing a comment or code
## Step 5: Use AI Assistance for Homelab Management ## How Services Get Added
The AI assistant is configured with comprehensive knowledge of your homelab architecture. You can ask it to: ### The AI Way (Recommended)
1. **Tell the AI**: "Add Plex to my media stack"
2. **AI Creates**: Docker Compose file with proper configuration
3. **AI Configures**: Traefik routing, Authelia protection, resource limits
4. **AI Deploys**: Service goes live with HTTPS and SSO
5. **AI Updates**: Homepage dashboard automatically
### Common Tasks ### Manual Way
- **Add new services**: "Add a new service to my media stack" 1. **Find Service**: Choose from 50+ pre-configured services
- **Modify configurations**: "Change the port for my Plex service" 2. **Upload to Dockge**: Use the web interface
- **Troubleshoot issues**: "Why isn't my service starting?" 3. **Configure**: Set environment variables and volumes
- **Update services**: "Update all services to latest versions" 4. **Deploy**: Click deploy and wait
- **Configure routing**: "Add Traefik routing for my new service" 5. **Access**: Service is immediately available at `https://servicename.yourdomain.duckdns.org`
### How to Interact **Note**: If your core stack (Traefik, Authelia) is on a separate server, you'll need to:
1. Open any relevant file (docker-compose.yml, configuration files) - Configure external routing in Traefik's dynamic configuration
2. Use comments to describe what you want: `# TODO: Add new service here` - Set up Sablier lazy loading rules for the remote server
3. Or use the chat interface: Ask questions in natural language - Ensure proper network connectivity between servers
4. The AI will suggest edits, create new files, or run commands
### Example Prompts ## Storage Strategy
- "Create a compose file for a new media service"
- "Help me configure Authelia for a new user"
- "Add VPN routing to my download service"
- "Set up monitoring for my new application"
## Step 6: Best Practices ### Configuration Files
- **Location**: `/opt/stacks/stack-name/config/`
- **Purpose**: Service settings, databases, user data
- **Backup**: Included in automatic backups
### Media & Large Data
- **Location**: `/mnt/media/`, `/mnt/downloads/`
- **Purpose**: Movies, TV shows, music, downloads
- **Performance**: Direct mounted drives for speed
- **Important**: You'll need additional physical drives mounted at these locations for media storage
## AI Features
### VS Code Integration
- **Copilot Chat**: Natural language commands for infrastructure management
- **File Editing**: AI modifies Docker Compose files, configuration YAML
- **Troubleshooting**: AI analyzes logs and suggests fixes
- **Documentation**: AI keeps docs synchronized with deployed services
- **Direct File Access**: You can view and modify files directly in VS Code
- **Manual Changes**: Tell the AI to check your manual changes: "Review the changes I just made to the compose file"
## Scaling & Customization
### Adding Services
- **Pre-built**: 50+ services ready to deploy
- **Custom**: AI can create configurations for any Docker service
- **External**: Proxy services on other devices (Raspberry Pi, NAS)
### Deploying Additional Servers
You can deploy multiple servers for different purposes:
#### Core Stack on Separate Server
- **Purpose**: Dedicated server for reverse proxy, authentication, and VPN
- **Deployment**: Deploy core stack first on the dedicated server
- **Impact on Other Servers**:
- **Traefik**: Configure external routing for services on other servers
- **Sablier**: Set up lazy loading rules for remote services
- **Compose Files**: Services reference the core server's Traefik network externally
#### Media Server Example
- **Server 1**: Core stack (Traefik, Authelia, Gluetun)
- **Server 2**: Media services (Plex, Sonarr, Radarr)
- **Configuration**: Media server compose files connect to core server's networks
## Port Forwarding Requirements
**Important**: You must forward ports 80 and 443 from your router to your homelab server for SSL certificates and web access to work.
### Router Configuration
1. Log into your router's admin interface
2. Find the port forwarding section
3. Forward:
- **Port 80** (HTTP) → Your server's IP address
- **Port 443** (HTTPS) → Your server's IP address
4. Save changes and test connectivity
### Why This Matters
- **SSL Certificates**: Let's Encrypt needs port 80 for domain validation
- **HTTPS Access**: All services use port 443 for secure connections
- **Wildcard Certificates**: Enables `*.yourdomain.duckdns.org` subdomains
## Best Practices
- **Always backup** before making changes - **Always backup** before making changes
- **Test in isolation** - deploy single services first - **Test in isolation** - deploy single services first

1
docs/automated-setup.md
View File

@@ -6,6 +6,7 @@ For most users, the automated setup script handles everything from system prepar
- **Fresh Debian/Ubuntu server** (or existing system) - **Fresh Debian/Ubuntu server** (or existing system)
- **Root/sudo access** - **Root/sudo access**
- **Internet connection** - **Internet connection**
- **Ports 80 and 443 forwarded** from your router to your server (required for SSL certificates)
- **VS Code with GitHub Copilot** (for AI assistance) - **VS Code with GitHub Copilot** (for AI assistance)
## Simple Setup ## Simple Setup

6
docs/getting-started.md
View File

@@ -1,6 +1,6 @@
# Getting Started Guide # Getting Started Guide
Welcome to your AI-powered homelab! This guide will walk you through setting up your production-ready infrastructure with Dockge, Traefik, Authelia, and 50+ services. Welcome to your AI-powered homelab! This guide will walk you through setting up your production-ready infrastructure with Dockge, Traefik, Authelia, and [50+ services](services-overview.md).
## Getting Started Checklist ## Getting Started Checklist
- [ ] Clone this repository to your home folder - [ ] Clone this repository to your home folder
@@ -11,7 +11,7 @@ Welcome to your AI-powered homelab! This guide will walk you through setting up
- [ ] Access Dockge web UI ([https://dockge.yourdomain.duckdns.org](https://dockge.yourdomain.duckdns.org)) - [ ] Access Dockge web UI ([https://dockge.yourdomain.duckdns.org](https://dockge.yourdomain.duckdns.org))
- [ ] Set up 2FA with Authelia ([Authelia setup guide](service-docs/authelia.md)) - [ ] Set up 2FA with Authelia ([Authelia setup guide](service-docs/authelia.md))
- [ ] (optional) Deploy additional stacks as needed via Dockge ([services overview](services-overview.md)) - [ ] (optional) Deploy additional stacks as needed via Dockge ([services overview](services-overview.md))
- [ ] Configure and use VS Code with Github Copilot to manage the server ([AI management](.github/copilot-instructions.md)) - [ ] Configure and use VS Code with Github Copilot to manage the server ([AI management](.github/copilot-instructions.md) | [Example prompts](ai-management-prompts.md))
## Setup Options ## Setup Options
@@ -36,7 +36,7 @@ Your homelab uses Let's Encrypt for automatic HTTPS certificates. See [SSL Certi
## What Comes Next ## What Comes Next
After setup, learn what to do with your running homelab. See [Post-Setup Next Steps](post-setup-next-steps.md) for accessing services, customization, and maintenance. After setup, learn what to do with your running homelab. See [Post-Setup Guide](post-setup.md) for accessing services, customization, and maintenance.
## On-Demand Remote Services ## On-Demand Remote Services

26
docs/how-it-works.md
View File

@@ -21,35 +21,41 @@ Your central hub for accessing all services. Think of it as the "start menu" for
- **What it does**: Shows all your deployed services with quick links - **What it does**: Shows all your deployed services with quick links
- **AI Integration**: The AI can automatically add new services and configure widgets - **AI Integration**: The AI can automatically add new services and configure widgets
- **Customization**: Add weather, system stats, and service-specific widgets - **Customization**: Add weather, system stats, and service-specific widgets
- **Configuration**: [docker-compose/dashboards/](docker-compose/dashboards/) | [service-docs/homepage.md](service-docs/homepage.md)
### 🐳 **Dockge** (`https://dockge.yourdomain.duckdns.org`) ### 🐳 **Dockge** (`https://dockge.yourdomain.duckdns.org`)
Your primary management interface for deploying and managing services. Your primary management interface for deploying and managing services.
- **What it does**: Web-based Docker Compose manager - **What it does**: Web-based Docker Compose manager
- **Stacks**: Groups services into logical units (media, monitoring, productivity) - **Stacks**: Groups services into logical units (media, monitoring, productivity)
- **One-Click Deploy**: Upload compose files and deploy instantly - **One-Click Deploy**: Upload compose files and deploy instantly
- **Configuration**: [docker-compose/infrastructure/](docker-compose/infrastructure/) | [service-docs/dockge.md](service-docs/dockge.md)
### 🔐 **Authelia** (`https://auth.yourdomain.duckdns.org`) ### 🔐 **Authelia** (`https://auth.yourdomain.duckdns.org`)
Your security gatekeeper that protects sensitive services. Your security gatekeeper that protects sensitive services.
- **What it does**: Single sign-on (SSO) authentication - **What it does**: Single sign-on (SSO) authentication
- **Security**: Two-factor authentication, session management - **Security**: Two-factor authentication, session management
- **Smart Bypass**: Automatically bypasses auth for media apps (Plex, Jellyfin) - **Smart Bypass**: Automatically bypasses auth for media apps (Plex, Jellyfin)
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/authelia.md](service-docs/authelia.md)
### 🌐 **Traefik** (`https://traefik.yourdomain.duckdns.org`) ### 🌐 **Traefik** (`https://traefik.yourdomain.duckdns.org`)
Your intelligent traffic director and SSL certificate manager. Your intelligent traffic director and SSL certificate manager.
- **What it does**: Reverse proxy that routes web traffic to the right services - **What it does**: Reverse proxy that routes web traffic to the right services
- **SSL**: Automatically obtains and renews free HTTPS certificates - **SSL**: Automatically obtains and renews free HTTPS certificates
- **Labels**: Services "advertise" themselves to Traefik via Docker labels - **Labels**: Services "advertise" themselves to Traefik via Docker labels
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/traefik.md](service-docs/traefik.md)
### 🦆 **DuckDNS** ### 🦆 **DuckDNS**
Your dynamic DNS service that gives your homelab a consistent domain name. Your dynamic DNS service that gives your homelab a consistent domain name.
- **What it does**: Updates `yourdomain.duckdns.org` to point to your home IP - **What it does**: Updates `yourdomain.duckdns.org` to point to your home IP
- **Integration**: Works with Traefik to get wildcard SSL certificates - **Integration**: Works with Traefik to get wildcard SSL certificates
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/duckdns.md](service-docs/duckdns.md)
### 🛡️ **Gluetun (VPN)** ### 🛡️ **Gluetun (VPN)**
Your download traffic protector. Your download traffic protector.
- **What it does**: Routes torrent and download traffic through VPN - **What it does**: Routes torrent and download traffic through VPN
- **Security**: Prevents ISP throttling and hides your IP for downloads - **Security**: Prevents ISP throttling and hides your IP for downloads
- **Integration**: Download services connect through Gluetun's network - **Integration**: Download services connect through Gluetun's network
- **Configuration**: [docker-compose/core/](docker-compose/core/) | [service-docs/gluetun.md](service-docs/gluetun.md)
## How Services Get Added ## How Services Get Added
@@ -148,7 +154,7 @@ Some services start **on-demand** to save resources:
## Scaling & Customization ## Scaling & Customization
### Adding Services ### Adding Services
- **Pre-built**: 50+ services ready to deploy - **Pre-built**: [50+ services](services-overview.md) ready to deploy
- **Custom**: AI can create configurations for any Docker service - **Custom**: AI can create configurations for any Docker service
- **External**: Proxy services on other devices (Raspberry Pi, NAS) - **External**: Proxy services on other devices (Raspberry Pi, NAS)
@@ -159,25 +165,19 @@ Some services start **on-demand** to save resources:
## Troubleshooting Philosophy ## Troubleshooting Philosophy
### Logs First - **Logs First**: Every service provides detailed logs. The AI can help analyze them.
Every service provides detailed logs. The AI can help analyze them. - **Isolation Testing**: Deploy services one at a time to identify conflicts.
- **Configuration Validation**: AI validates Docker Compose syntax before deployment.
### Isolation Testing - **Rollback Ready**: Previous configurations are preserved for quick recovery.
Deploy services one at a time to identify conflicts.
### Configuration Validation
AI validates Docker Compose syntax before deployment.
### Rollback Ready
Previous configurations are preserved for quick recovery.
## Getting Help ## Getting Help
### Documentation Links ### Documentation Links
- **[Automated Setup](automated-setup.md)**: Step-by-step deployment - **[Automated Setup](automated-setup.md)**: Step-by-step deployment
- **[SSL Certificates](ssl-certificates.md)**: HTTPS configuration details - **[SSL Certificates](ssl-certificates.md)**: HTTPS configuration details
- **[Post-Setup](post-setup-next-steps.md)**: What to do after deployment - **[Post-Setup](post-setup.md)**: What to do after deployment
- **[AI VS Code Setup](ai-vscode-setup.md)**: Configure AI assistance - **[AI VS Code Setup](ai-vscode-setup.md)**: Configure AI assistance
- **[AI Management Prompts](ai-management-prompts.md)**: Example commands for AI assistant
- **[Services Overview](../docs/services-overview.md)**: All available services - **[Services Overview](../docs/services-overview.md)**: All available services
- **[Docker Guidelines](../docs/docker-guidelines.md)**: Technical details - **[Docker Guidelines](../docs/docker-guidelines.md)**: Technical details

0
docs/post-setup-next-steps.md → docs/post-setup.md
View File

28
docs/ssl-certificates.md
View File

@@ -138,9 +138,27 @@ echo | openssl s_client -connect yourdomain.duckdns.org:443 -servername any-subd
- HTTPS provides encryption in transit - HTTPS provides encryption in transit
- Consider additional security headers in Traefik - Consider additional security headers in Traefik
## Certificate Lifecycle ## Port Forwarding Requirements
- **Validity**: 90 days **Critical**: SSL certificates require ports 80 and 443 to be forwarded from your router to your homelab server.
- **Renewal**: Automatic, 30 days before expiration
- **Storage**: Persistent across container restarts ### Router Configuration
- **Backup**: Include in your homelab backup strategy 1. Log into your router's admin interface (usually 192.168.1.1)
2. Find the "Port Forwarding" or "NAT" section
3. Create forwarding rules:
- **External Port**: 80 → **Internal IP**: your-server-ip **Internal Port**: 80
- **External Port**: 443 → **Internal IP**: your-server-ip **Internal Port**: 443
4. Protocol: TCP for both
5. Save changes
### Why This Is Required
- **Port 80**: Used by Let's Encrypt for domain ownership verification (HTTP-01 challenge)
- **Port 443**: Used for all HTTPS traffic to your services
- **Wildcard Certificates**: Enables automatic SSL for all `*.yourdomain.duckdns.org` subdomains
### Testing Port Forwarding
```bash
# Test from external network (not your local network)
curl -I http://yourdomain.duckdns.org
# Should return HTTP 200 or redirect to HTTPS
```