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

Round 9: Complete documentation overhaul

Browse Source 
Major documentation updates reflecting current deployment state:

README.md:
✅ Updated features list with automated setup capabilities
✅ Accurate deployment workflow (12 containers, 7 additional stacks)
✅ Corrected setup script description (automated Authelia secrets)
✅ Removed manual secret generation steps
✅ Added note about optional image pre-pull
✅ Clarified .env requirements (Authelia secrets now automated)

docs/getting-started.md:
✅ Streamlined quick setup workflow (removed manual secrets)
✅ Comprehensive setup script capabilities list
✅ Detailed deployment script behavior
✅ Added interactive Authelia configuration details
✅ Clarified argon2id password hash generation process
✅ Updated login credentials location
✅ Removed outdated .env location warnings

docs/quick-reference.md:
✅ Added deployment scripts reference section
✅ Complete setup-homelab.sh documentation
✅ Complete deploy-homelab.sh documentation
✅ Added reset-test-environment.sh with warnings
✅ Updated stack overview with container counts
✅ Clarified which stacks deploy by default vs available in Dockge
✅ Noted Watchtower temporary disable status

docs/troubleshooting/COMMON-ISSUES.md (NEW):
✅ Installation issues (Docker permissions, timeouts, port conflicts)
✅ Deployment issues (Authelia loops, Watchtower status, Homepage URLs)
✅ Service-specific issues (Gluetun, Pi-hole, Dockge)
✅ Performance troubleshooting
✅ Reset and recovery procedures with warnings
✅ Complete getting help section with commands

Total changes: 456 additions, 71 modifications across 4 files
Documentation now accurately reflects Round 9 deployment capabilities
This commit is contained in:
kelin
2026-01-13 21:46:01 -05:00
parent 487f645652
commit afdc99a5a2
4 changed files with 458 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
README.md
View File

@@ -21,15 +21,16 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
## Features
- **AI-Powered Management**: GitHub Copilot integration with specialized instructions for Docker service management
- **Dockge Structure**: All stacks organized in `/opt/stacks/` for easy management via Dockge
- **Automated Setup & Deployment**: Two-script installation process with intelligent error handling
- **Dockge Structure**: All stacks organized in `/opt/stacks/` for easy management via Dockge web UI
- **40+ Pre-configured Services**: Production-ready compose files across infrastructure, media, home automation, productivity, and monitoring
- **Traefik Reverse Proxy**: Automatic HTTPS with Let's Encrypt via file-based configuration (no web UI needed)
- **Authelia SSO**: Single Sign-On protection for all admin interfaces with smart bypass rules for media apps
- **Authelia SSO**: Single Sign-On protection for all admin interfaces with automated password generation
- **Gluetun VPN**: Surfshark WireGuard integration for secure downloads
- **Homepage Dashboard**: AI-configurable dashboard with Docker integration and service widgets
- **Homepage Dashboard**: AI-configurable dashboard with automatic domain variable replacement
- **External Host Proxying**: Proxy external services (Raspberry Pi, routers, NAS) through Traefik
- **Stack-Aware Changes**: AI considers the entire infrastructure when making changes
- **Comprehensive Documentation**: Detailed guidelines including proxying external hosts
- **Comprehensive Documentation**: Detailed guidelines including proxying external hosts and troubleshooting
- **File-Based Configuration**: Everything managed via YAML files - no web UI dependencies
## Documentation
@@ -62,13 +63,23 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
cd AI-Homelab
```
2. **(Optional) Run first-run setup script:**
2. **Run first-run setup script:**
For fresh Debian installations only, this automated script will install Docker Engine + Compose V2, configure user groups, detect NVIDIA GPU, and create directory structure.
This automated script handles system preparation and Authelia configuration. Safe to run on partially configured systems - it skips completed steps.
```bash
sudo ./scripts/setup-homelab.sh
```
The script will:
- Install Docker Engine + Compose V2 (if needed)
- Configure user groups and firewall
- Detect NVIDIA GPU and offer driver installation
- **Generate Authelia secrets automatically**
- **Create admin user and password hash**
- Set up directory structure and Docker networks
**Important:** Log out and back in (or run `newgrp docker`) after setup completes.
3. **Create and configure environment file:**
```bash
@@ -81,41 +92,46 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
**Required variables:**
- `DOMAIN` - Your DuckDNS domain (e.g., yourdomain.duckdns.org)
- `DUCKDNS_TOKEN` - Your DuckDNS token
- `DUCKDNS_TOKEN` - Your DuckDNS token from [duckdns.org](https://www.duckdns.org/)
- `ACME_EMAIL` - Your email for Let's Encrypt certificates
- `AUTHELIA_JWT_SECRET` - Generate with: `openssl rand -hex 64`
- `AUTHELIA_SESSION_SECRET` - Generate with: `openssl rand -hex 64`
- `AUTHELIA_STORAGE_ENCRYPTION_KEY` - Generate with: `openssl rand -hex 64`
- `SURFSHARK_USERNAME` and `SURFSHARK_PASSWORD` - If using VPN
- `SURFSHARK_USERNAME` and `SURFSHARK_PASSWORD` - If using VPN features
**Note:** Authelia secrets (`AUTHELIA_JWT_SECRET`, `AUTHELIA_SESSION_SECRET`, `AUTHELIA_STORAGE_ENCRYPTION_KEY`) are automatically generated by the setup script. You can pre-generate them if desired using `openssl rand -hex 64`.
> See [Getting Started](docs/getting-started.md) for detailed instructions
4. **Run deployment script:**
This automated script will:
- Create Docker networks
- Configure Traefik with your email
- Generate Authelia admin password (saved to `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt`)
- Deploy core stack (DuckDNS, Traefik, Authelia, Gluetun)
- Deploy infrastructure stack (Dockge, Pi-hole, monitoring tools)
- Deploy dashboards stack (Homepage, Homarr)
- Configure Traefik with your email and domain
- Deploy admin password from setup script
- Deploy core stack (DuckDNS, Traefik, Authelia, Gluetun) - 4 services
- Deploy infrastructure stack (Dockge, Pi-hole, monitoring) - 6 services
- Deploy dashboards stack (Homepage with configured URLs, Homarr) - 2 services
- **Prepare 7 additional stacks in Dockge** (not started, ready to deploy)
- Wait for services to be healthy
- Open Dockge in your browser
```bash
./scripts/deploy-homelab.sh
```
**Login credentials:** Username: `admin` | Password: Check `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt`
**Login credentials:** Check script output or `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt`
**Note:** The script will prompt to optionally pre-pull images for additional stacks. This takes time but speeds up future deployments. Default is no.
5. **Deploy additional stacks through Dockge:**
Log in to Dockge at `https://dockge.yourdomain.duckdns.org` and deploy additional stacks from the repository's `docker-compose/` directory:
- `media.yml` - Plex, Jellyfin, Sonarr, Radarr, etc.
- `media-extended.yml` - Readarr, Lidarr, etc.
- `homeassistant.yml` - Home Assistant and accessories
- `productivity.yml` - Nextcloud, Gitea, wikis
- `monitoring.yml` - Grafana, Prometheus, etc.
- `utilities.yml` - Backups, code editors, etc.
Log in to Dockge at `https://dockge.yourdomain.duckdns.org` - all stacks are already loaded and ready to deploy:
- **media** - Plex, Jellyfin, Sonarr, Radarr, Prowlarr, qBittorrent
- **media-extended** - Readarr, Lidarr, Mylar, Calibre
- **homeassistant** - Home Assistant, Node-RED, Zigbee2MQTT, ESPHome
- **productivity** - Nextcloud, Gitea, Bookstack, Outline, Excalidraw
- **monitoring** - Grafana, Prometheus, Uptime Kuma, Netdata
- **utilities** - Duplicati, Code Server, FreshRSS, Wallabag
- **alternatives** - Portainer, Authentik (alternative to Dockge/Authelia)
Simply click any stack in Dockge and press "Start" to deploy it.
6. **Configure VS Code to control the server via GitHub Copilot**