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

docs: implement user feedback from tasks.txt

Browse Source 
- README.md: Fixed .env step order, updated to 60+ services
- getting-started.md: Service count updates, credential clarifications, moved Manual Setup to separate file
- manual-setup.md: Created comprehensive manual setup guide
- authelia-customization.md: Moved Authelia customization from services-overview
- services-overview.md: Added clickable links to service docs, removed disabled section and Quick Deployment
- quick-reference.md: Linked to scripts/README.md instead of duplicating content
- Removed services-reference.md as requested
This commit is contained in:
kelin
2026-01-13 22:36:37 -05:00
parent ea4af44726
commit 3bad39567d
8 changed files with 565 additions and 341 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
README.md
View File

@@ -4,7 +4,7 @@ Leverage Github Copilot in VS Code as a complete homelab management interface.
## Overview
This repository provides a comprehensive, production-ready homelab infrastructure using Docker Compose with Dockge, featuring 40+ pre-configured services. Integrated AI assistance through GitHub Copilot helps you create, modify, and manage Docker services while maintaining consistency across your entire server stack.
This repository provides a comprehensive, production-ready homelab infrastructure using Docker Compose with Dockge, featuring 60+ pre-configured services. Integrated AI assistance through GitHub Copilot helps you create, modify, and manage Docker services while maintaining consistency across your entire server stack.
The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia for Single Sign-On, Gluetun for VPN routing, and DuckDNS for dynamic DNS - all managed through file-based configurations that the AI can manage.
@@ -23,7 +23,7 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
- **AI-Powered Management**: GitHub Copilot integration with specialized instructions for Docker service management
- **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
- **60+ 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 automated password generation
- **Gluetun VPN**: Surfshark WireGuard integration for secure downloads
@@ -63,7 +63,26 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
cd AI-Homelab
```
2. **Run first-run setup script:**
2. **Create and configure environment file:**
```bash
cp .env.example .env
nano .env # Edit with your domain, API keys, and passwords
```
> Alternatively you can ssh in from VS Code using the Remote-SSH plugin and edit in a nice editor
**IMPORTANT:** Keep your `.env` file in the repository folder (`~/AI-Homelab/.env`). The deploy script will automatically copy it where needed.
**Required variables:**
- `DOMAIN` - Your DuckDNS domain (e.g., yourdomain.duckdns.org)
- `DUCKDNS_TOKEN` - Your DuckDNS token from [duckdns.org](https://www.duckdns.org/)
- `ACME_EMAIL` - Your email for Let's Encrypt certificates
- `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, leave default values for now.
> See [Getting Started](docs/getting-started.md) for detailed instructions
3. **Run first-run setup script:**
This automated script handles system preparation and Authelia configuration. Safe to run on partially configured systems - it skips completed steps.
@@ -81,25 +100,6 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
**Important:** Log out and back in (or run `newgrp docker`) after setup completes.
3. **Create and configure environment file:**
```bash
cp .env.example .env
nano .env # Edit with your domain, API keys, and passwords
```
> Alternatively you can ssh in from VS Code using the Remote-SSH plugin and edit in a nice editor
**IMPORTANT:** Keep your `.env` file in the repository folder (`~/AI-Homelab/.env`). The deploy script will automatically copy it where needed.
**Required variables:**
- `DOMAIN` - Your DuckDNS domain (e.g., yourdomain.duckdns.org)
- `DUCKDNS_TOKEN` - Your DuckDNS token from [duckdns.org](https://www.duckdns.org/)
- `ACME_EMAIL` - Your email for Let's Encrypt certificates
- `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:
@@ -116,8 +116,6 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
./scripts/deploy-homelab.sh
```
**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:**

256
docs/authelia-customization.md Normal file
View File

@@ -0,0 +1,256 @@
# Authelia Customization Guide
This guide covers how to customize Authelia for your specific needs.
## Available Customization Options
### 1. Branding and Appearance
Edit `/opt/stacks/core/authelia/configuration.yml`:
```yaml
# Custom logo and branding
theme: dark # Options: light, dark, grey, auto
# No built-in web UI for configuration
# All settings managed via YAML files
```
### 2. User Management
Users are managed in `/opt/stacks/core/authelia/users_database.yml`:
```yaml
users:
username:
displayname: "Display Name"
password: "$argon2id$v=19$m=65536..." # Generated with authelia hash-password
email: user@example.com
groups:
- admins
- users
```
Generate password hash:
```bash
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'yourpassword'
```
### 3. Access Control Rules
Customize who can access what in `configuration.yml`:
```yaml
access_control:
default_policy: deny
rules:
# Public services (no auth)
- domain:
- "jellyfin.yourdomain.com"
- "plex.yourdomain.com"
policy: bypass
# Admin only services
- domain:
- "dockge.yourdomain.com"
- "portainer.yourdomain.com"
policy: two_factor
subject:
- "group:admins"
# All authenticated users
- domain: "*.yourdomain.com"
policy: one_factor
```
### 4. Two-Factor Authentication (2FA)
- TOTP (Time-based One-Time Password) via apps like Google Authenticator, Authy
- Configure in `configuration.yml` under `totp:` section
- Per-user enrollment via Authelia UI at `https://auth.${DOMAIN}`
### 5. Session Management
Edit `configuration.yml`:
```yaml
session:
name: authelia_session
expiration: 1h # How long before re-login required
inactivity: 5m # Timeout after inactivity
remember_me_duration: 1M # "Remember me" checkbox duration
```
### 6. Notification Settings
Email notifications for password resets, 2FA enrollment:
```yaml
notifier:
smtp:
host: smtp.gmail.com
port: 587
username: your-email@gmail.com
password: app-password
sender: authelia@yourdomain.com
```
## No Web UI for Configuration
⚠️ **Important**: Authelia does **not** have a configuration web UI. All configuration is done via YAML files:
- `/opt/stacks/core/authelia/configuration.yml` - Main settings
- `/opt/stacks/core/authelia/users_database.yml` - User accounts
This is **by design** and makes Authelia perfect for AI management and security-first approach:
- AI can read and modify YAML files
- Version control friendly
- No UI clicks required
- Infrastructure as code
- Secure by default
**Web UI Available For:**
- Login page: `https://auth.${DOMAIN}`
- User profile: Change password, enroll 2FA
- Device enrollment: Manage trusted devices
## Alternative with Web UI: Authentik
If you need a web UI for user management, Authentik is included in the infrastructure stack:
- **Authentik**: Full-featured SSO with web UI for user/group management
- Access at: `https://authentik.${DOMAIN}`
- Includes PostgreSQL database and Redis cache
- More complex but offers GUI-based configuration
- Deploy only if you need web-based user management
**Other Alternatives:**
- **Keycloak**: Enterprise-grade SSO with web UI
- **Authelia + LDAP**: Use LDAP with web management (phpLDAPadmin, etc.)
## Quick Configuration with AI
Since all Authelia configuration is file-based, you can use the AI assistant to:
- Add/remove users
- Modify access rules
- Change session settings
- Update branding
- Enable/disable features
Just ask: "Add a new user to Authelia" or "Change session timeout to 2 hours"
## Common Customizations
### Adding a New User
1. Generate password hash:
```bash
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'newuserpassword'
```
2. Edit `/opt/stacks/core/authelia/users_database.yml`:
```yaml
users:
admin:
# existing admin user...
newuser:
displayname: "New User"
password: "$argon2id$v=19$m=65536..." # paste generated hash
email: newuser@example.com
groups:
- users
```
3. Restart Authelia:
```bash
cd /opt/stacks/core
docker compose restart authelia
```
### Bypass SSO for Specific Service
Edit the service's Traefik labels to remove the Authelia middleware:
```yaml
# Before (SSO protected)
labels:
- "traefik.http.routers.service.middlewares=authelia@docker"
# After (bypass SSO)
labels:
# - "traefik.http.routers.service.middlewares=authelia@docker" # commented out
```
### Change Session Timeout
Edit `/opt/stacks/core/authelia/configuration.yml`:
```yaml
session:
expiration: 12h # Changed from 1h to 12h
inactivity: 30m # Changed from 5m to 30m
```
Restart Authelia to apply changes.
### Enable SMTP Notifications
Edit `/opt/stacks/core/authelia/configuration.yml`:
```yaml
notifier:
smtp:
host: smtp.gmail.com
port: 587
username: your-email@gmail.com
password: your-app-password # Use app-specific password
sender: authelia@yourdomain.com
subject: "[Authelia] {title}"
```
### Create Admin-Only Access Rule
Edit `/opt/stacks/core/authelia/configuration.yml`:
```yaml
access_control:
rules:
# Admin-only services
- domain:
- "dockge.yourdomain.duckdns.org"
- "traefik.yourdomain.duckdns.org"
- "portainer.yourdomain.duckdns.org"
policy: two_factor
subject:
- "group:admins"
# All other services - any authenticated user
- domain: "*.yourdomain.duckdns.org"
policy: one_factor
```
Restart Authelia after changes.
## Troubleshooting
### User Can't Log In
1. Check password hash format in users_database.yml
2. Verify email address matches
3. Check Authelia logs: `docker logs authelia`
### 2FA Not Working
1. Ensure time sync on server: `timedatectl`
2. Check TOTP configuration in configuration.yml
3. Regenerate QR code for user
### Sessions Expire Too Quickly
Increase session expiration in configuration.yml:
```yaml
session:
expiration: 24h
inactivity: 1h
```
### Can't Access Specific Service
Check access control rules - service domain may be blocked by default_policy: deny
## Additional Resources
- [Authelia Documentation](https://www.authelia.com/docs/)
- [Authelia Service Docs](service-docs/authelia.md)
- [Getting Started Guide](getting-started.md)

100
docs/getting-started.md
View File

@@ -1,6 +1,6 @@
# 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 40+ services.
Welcome to your AI-powered homelab! This guide will walk you through setting up your production-ready infrastructure with Dockge, Traefik, Authelia, and 60+ services.
## Quick Setup (Recommended)
@@ -36,7 +36,7 @@ For most users, the automated setup script handles everything:
- `ACME_EMAIL` - Your email for Let's Encrypt certificates
- `SURFSHARK_USERNAME` and `SURFSHARK_PASSWORD` - If using VPN
**Note:** The `.env` file stays in the repository folder (`~/AI-Homelab/.env`). The deploy script copies it to stack directories automatically. Authelia secrets are generated by the setup script.
**Note:** The `.env` file stays in the repository folder (`~/AI-Homelab/.env`). The deploy script copies it to stack directories automatically. Authelia secrets (JWT, session, encryption key) are auto-generated by the setup script - leave them with default values for now.
5. **Run the setup script:**
```bash
@@ -56,8 +56,6 @@ For most users, the automated setup script handles everything:
- Set up Docker networks (homelab, traefik, dockerproxy, media)
- Detect NVIDIA GPU and offer driver installation
**Important:** The script generates a secure admin password hash that will be used during deployment. Credentials are displayed at the end and saved to a temporary file.
6. **Log out and back in** (or run `newgrp docker`)
> Don't skip this step! Required for Docker group permissions.
@@ -76,8 +74,8 @@ For most users, the automated setup script handles everything:
- Opens Dockge in your browser
**Login credentials:**
- Username: `admin`
- Password: Check `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt` or see script output
- Username: `admin` (default username - or the custom username you specified during setup)
- Password: The secure password you created when prompted by the setup script
**That's it!** Your homelab is ready. Access Dockge at `https://dockge.yourdomain.duckdns.org`
@@ -116,97 +114,30 @@ The `setup-homelab.sh` script is a comprehensive first-run configuration tool:
## Manual Setup (Alternative)
If you prefer manual control or the script fails, follow these steps:
If you prefer manual control or the automated script fails, see the [Manual Setup Guide](manual-setup.md) for step-by-step instructions on installing Docker, configuring services, and deploying the homelab manually.
### Step 1: System Preparation
```bash
# Update system
sudo apt update && sudo apt upgrade -y
# Install required packages
sudo apt install -y curl wget git ufw openssh-server
# Enable firewall
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
```
### Step 2: Install Docker
```bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Add user to docker group
sudo usermod -aG docker $USER
sudo usermod -aG sudo $USER
# Log out and back in, or run: newgrp docker
```
### Step 3: Clone Repository
```bash
cd ~
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab
```
### Step 4: Configure Environment
```bash
cp .env.example .env
nano .env # Edit all required variables
```
### Step 5: Create Infrastructure
```bash
# Create directories
sudo mkdir -p /opt/stacks /mnt/{media,database,downloads,backups}
sudo chown -R $USER:$USER /opt/stacks /mnt
# Create networks
docker network create traefik-network
docker network create homelab-network
docker network create media-network
```
### Step 6: Deploy Services
```bash
# Deploy core infrastructure
sudo mkdir -p /opt/stacks/core
cp docker-compose/core.yml /opt/stacks/core/
cp -r config-templates/traefik /opt/stacks/core/
cp -r config-templates/authelia /opt/stacks/core/
cp .env /opt/stacks/core/
cd /opt/stacks/core
docker compose up -d
# Deploy infrastructure stack
sudo mkdir -p /opt/stacks/infrastructure
cp ../docker-compose/infrastructure.yml /opt/stacks/infrastructure/
cp ../.env /opt/stacks/infrastructure/
cd /opt/stacks/infrastructure
docker compose up -d
```
## Post-Setup Configuration
## Post-Setup Next Steps
### Access Your Services
- **Dockge**: `https://dockge.yourdomain.duckdns.org`
- **Authelia**: `https://auth.yourdomain.duckdns.org`
- **Traefik**: `https://traefik.yourdomain.duckdns.org`
### Configure Authelia
### Set Up 2FA with Authelia
1. Access `https://auth.yourdomain.duckdns.org`
2. Set up your admin user
3. Configure 2FA for security
### Deploy Additional Stacks
Use Dockge to deploy stacks like:
- `dashboards.yml` - Homepage and Homarr
- `media.yml` - Plex, Jellyfin, Sonarr, Radarr
- `productivity.yml` - Nextcloud, Gitea, wikis
- `arr-apps.yml` - Media management (Radarr, Sonarr, Prowlarr, etc.)
- `media-servers.yml` - Plex and Jellyfin
- `downloaders.yml` - qBittorrent, Transmission, etc.
- `monitoring.yml` - Uptime Kuma and metrics
- `system-tools.yml` - Utility services
- `automation.yml` - Automated workflows
**Note:** The dashboards stack (Homepage and Homarr) is already deployed during initial setup.
### Set Up Homepage Widgets
1. Access Homepage dashboard
@@ -236,6 +167,7 @@ Use Dockge to deploy stacks like:
- View logs: `docker exec traefik tail -50 /var/log/traefik/traefik.log | grep certificate`
- **Authelia login fails**: Check user database configuration at `/opt/stacks/core/authelia/users_database.yml`
- **"Not secure" warnings**: Clear browser cache or wait for DNS propagation (up to 5 minutes)
- **Check logs**: Use Dozzle web interface at `https://dozzle.yourdomain.duckdns.org` or run `docker logs <container-name>`
### Common Fixes
```bash

216
docs/manual-setup.md Normal file
View File

@@ -0,0 +1,216 @@
# Manual Setup Guide
If you prefer manual control or the automated script fails, follow these steps for manual installation.
## Prerequisites
- Fresh Debian/Ubuntu server or existing system
- Root/sudo access
- Internet connection
## Step 1: Update System
```bash
sudo apt update && sudo apt upgrade -y
```
## Step 2: Install Docker
```bash
# Install dependencies
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# Set up repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# Or use convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Add user to docker group
sudo usermod -aG docker $USER
sudo usermod -aG sudo $USER
# Log out and back in, or run: newgrp docker
```
## Step 3: Clone Repository
```bash
cd ~
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab
```
## Step 4: Configure Environment
```bash
cp .env.example .env
nano .env # Edit all required variables
```
**Required variables:**
- `DOMAIN` - Your DuckDNS domain
- `DUCKDNS_TOKEN` - Your DuckDNS token
- `ACME_EMAIL` - Your email for Let's Encrypt
- `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
## Step 5: Create Infrastructure
```bash
# Create directories
sudo mkdir -p /opt/stacks /mnt/{media,database,downloads,backups}
sudo chown -R $USER:$USER /opt/stacks /mnt
# Create networks
docker network create traefik-network
docker network create homelab-network
docker network create dockerproxy-network
docker network create media-network
```
## Step 6: Generate Authelia Password Hash
```bash
# Generate password hash (takes 30-60 seconds)
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'YourSecurePassword'
# Copy the hash starting with $argon2id$...
```
## Step 7: Configure Authelia
```bash
# Copy Authelia config templates
mkdir -p /opt/stacks/core/authelia
cp config-templates/authelia/* /opt/stacks/core/authelia/
# Edit users_database.yml
nano /opt/stacks/core/authelia/users_database.yml
# Replace password hash and email in the users section:
users:
admin:
displayname: "Admin User"
password: "$argon2id$v=19$m=65536,t=3,p=4$..." # Your hash here
email: your.email@example.com
groups:
- admins
- users
```
## Step 8: Deploy Core Services
```bash
# Deploy core infrastructure
sudo mkdir -p /opt/stacks/core
cp docker-compose/core.yml /opt/stacks/core/docker-compose.yml
cp -r config-templates/traefik /opt/stacks/core/
cp .env /opt/stacks/core/
# Update Traefik email
sed -i "s/admin@example.com/$ACME_EMAIL/" /opt/stacks/core/traefik/traefik.yml
cd /opt/stacks/core
docker compose up -d
```
## Step 9: Deploy Infrastructure Stack
```bash
sudo mkdir -p /opt/stacks/infrastructure
cp docker-compose/infrastructure.yml /opt/stacks/infrastructure/docker-compose.yml
cp .env /opt/stacks/infrastructure/
cd /opt/stacks/infrastructure
docker compose up -d
```
## Step 10: Deploy Dashboards
```bash
sudo mkdir -p /opt/stacks/dashboards
cp docker-compose/dashboards.yml /opt/stacks/dashboards/docker-compose.yml
cp -r config-templates/homepage /opt/stacks/dashboards/
cp .env /opt/stacks/dashboards/
# Replace Homepage domain variables
find /opt/stacks/dashboards/homepage -type f \( -name "*.yaml" -o -name "*.yml" \) -exec sed -i "s/{{HOMEPAGE_VAR_DOMAIN}}/$DOMAIN/g" {} \;
cd /opt/stacks/dashboards
docker compose up -d
```
## Step 11: Verify Deployment
```bash
# Check running containers
docker ps
# Check logs if any service fails
docker logs container-name
# Access services
echo "Dockge: https://dockge.$DOMAIN"
echo "Authelia: https://auth.$DOMAIN"
echo "Traefik: https://traefik.$DOMAIN"
```
## Troubleshooting
**Permission issues:**
```bash
# Ensure proper ownership
sudo chown -R $USER:$USER /opt/stacks
# Check group membership
groups $USER
```
**Container won't start:**
```bash
# Check logs
docker logs container-name
# Check compose file syntax
docker compose config
```
**Network conflicts:**
```bash
# List existing networks
docker network ls
# Remove and recreate if needed
docker network rm network-name
docker network create network-name
```
## When to Use Manual Setup
- Automated script fails on your system
- You want full control over each step
- You're using a non-Debian/Ubuntu distribution
- You need custom configurations
- You're troubleshooting deployment issues
## Switching to Automated
If manual setup works, you can switch to the automated scripts for future updates:
```bash
# Just run the deploy script
cd ~/AI-Homelab
./scripts/deploy-homelab.sh
```
The deploy script is idempotent - it won't break existing configurations.

56
docs/quick-reference.md
View File

@@ -23,58 +23,12 @@ Your homelab uses separate stacks for organization:
## Deployment Scripts
### setup-homelab.sh
For detailed information about the deployment scripts, their features, and usage, see [scripts/README.md](../scripts/README.md).
First-run system preparation and Authelia configuration:
```bash
sudo ./scripts/setup-homelab.sh
```
**What it does:**
- Pre-flight checks (internet, disk space 50GB+)
- Installs Docker Engine + Compose V2
- Configures user groups and firewall
- Generates Authelia secrets automatically
- Creates admin user with secure password hash
- Sets up Docker networks and directory structure
- Detects NVIDIA GPU and offers driver installation
**Safe to re-run** - skips completed steps
### deploy-homelab.sh
Deploys all core services and prepares additional stacks:
```bash
./scripts/deploy-homelab.sh
```
**What it does:**
- Validates Docker installation
- Deploys core stack (4 containers)
- Deploys infrastructure stack (6 containers)
- Deploys dashboards with configured URLs (2 containers)
- Copies 7 additional stacks to Dockge (not started)
- Optional: Pre-pull images for additional stacks
- Opens Dockge in browser
### reset-test-environment.sh
**Testing/development only** - safely removes all deployed services:
```bash
sudo ./scripts/reset-test-environment.sh
```
**What it does:**
- Gracefully stops all Docker Compose stacks
- Removes Docker volumes (after 3s wait)
- Cleans stack directories and temp files
- Removes Docker networks
- Prunes unused Docker resources
**Warning:** This is destructive! Only use for testing or complete reset.
**Quick summary:**
- `setup-homelab.sh` - First-run system setup and Authelia configuration
- `deploy-homelab.sh` - Deploy all core services and prepare additional stacks
- `reset-test-environment.sh` - Testing/development only - removes all deployed services
## Common Commands

187
docs/services-overview.md
View File

@@ -7,18 +7,16 @@ This document provides a comprehensive overview of all 60+ pre-configured servic
| Stacks (10) | Services (70 + 6db) | SSO | Storage | Access URLs |
|-------|----------|-----|---------|-------------|
| **📦 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} |
| └─ Gluetun | VPN (Surfshark) | - | /opt/stacks/core/gluetun | No UI |
| ├─ [DuckDNS](service-docs/duckdns.md) | Dynamic DNS updater | - | /opt/stacks/core/duckdns | No UI |
| ├─ [Traefik](service-docs/traefik.md) | Reverse proxy + SSL | ✓ | /opt/stacks/core/traefik | traefik.${DOMAIN} |
| ├─ [Authelia](service-docs/authelia.md) | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} |
| └─ [Gluetun](service-docs/gluetun.md) | VPN (Surfshark) | - | /opt/stacks/core/gluetun | No UI |
| **🔧 infrastructure.yaml (6+5)** | **Deployed: 6** | | | |
| ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/infrastructure | dockge.${DOMAIN} |
| ├─ Pi-hole | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} |
| ├─ Dozzle | Docker log viewer | ✓ | /opt/stacks/infrastructure | dozzle.${DOMAIN} |
| ├─ Glances | System monitoring | ✓ | /opt/stacks/infrastructure | glances.${DOMAIN} |
| └─ Docker Proxy | Secure socket access | - | /opt/stacks/infrastructure | No UI |
| **⚠️ Disabled:** | | | | |
| ├─ Watchtower | Auto updates (disabled) | - | Docker API issue | No UI |
| ├─ [Dockge](service-docs/dockge.md) | Stack manager (PRIMARY) | ✓ | /opt/stacks/infrastructure | dockge.${DOMAIN} |
| ├─ [Pi-hole](service-docs/pihole.md) | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} |
| ├─ [Dozzle](service-docs/dozzle.md) | Docker log viewer | ✓ | /opt/stacks/infrastructure | dozzle.${DOMAIN} |
| ├─ [Glances](service-docs/glances.md) | System monitoring | ✓ | /opt/stacks/infrastructure | glances.${DOMAIN} |
| └─ [Docker Proxy](service-docs/docker-proxy.md) | Secure socket access | - | /opt/stacks/infrastructure | No UI |
| **📦 alternatives.yaml (5)** | **Not deployed** | | | |
| ├─ Portainer | Container management | ✓ | /opt/stacks/alternatives | portainer.${DOMAIN} |
| ├─ Authentik Server | SSO with web UI | ✓ | /opt/stacks/alternatives | authentik.${DOMAIN} |
@@ -95,42 +93,6 @@ This document provides a comprehensive overview of all 60+ pre-configured servic
**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)
- Media: `/opt/stacks/media/`
- Extended Media: `/opt/stacks/media-extended/`
- Home Automation: `/opt/stacks/homeassistant/`
- Productivity: `/opt/stacks/productivity/`
- Utilities: `/opt/stacks/utilities/`
- Monitoring: `/opt/stacks/monitoring/`
- Development: `/opt/stacks/development/`
## 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.
@@ -192,137 +154,6 @@ docker compose -f /opt/stacks/stack-name/docker-compose.yml down
- **Gradual Exposure**: Comment out SSO only when ready to expose a service
- **Quick Toggle**: AI assistant can modify these labels automatically when you ask
## Authelia Customization
### Available Customization Options
**1. Branding and Appearance**
Edit `/opt/stacks/core/authelia/configuration.yml`:
```yaml
# Custom logo and branding
theme: dark # Options: light, dark, grey, auto
# No built-in web UI for configuration
# All settings managed via YAML files
```
**2. User Management**
Users are managed in `/opt/stacks/core/authelia/users_database.yml`:
```yaml
users:
username:
displayname: "Display Name"
password: "$argon2id$v=19$m=65536..." # Generated with authelia hash-password
email: user@example.com
groups:
- admins
- users
```
Generate password hash:
```bash
docker run --rm authelia/authelia:4.37 authelia hash-password 'yourpassword'
```
**3. Access Control Rules**
Customize who can access what in `configuration.yml`:
```yaml
access_control:
default_policy: deny
rules:
# Public services (no auth)
- domain:
- "jellyfin.yourdomain.com"
- "plex.yourdomain.com"
policy: bypass
# Admin only services
- domain:
- "dockge.yourdomain.com"
- "portainer.yourdomain.com"
policy: two_factor
subject:
- "group:admins"
# All authenticated users
- domain: "*.yourdomain.com"
policy: one_factor
```
**4. Two-Factor Authentication (2FA)**
- TOTP (Time-based One-Time Password) via apps like Google Authenticator, Authy
- Configure in `configuration.yml` under `totp:` section
- Per-user enrollment via Authelia UI at `https://auth.${DOMAIN}`
**5. Session Management**
Edit `configuration.yml`:
```yaml
session:
name: authelia_session
expiration: 1h # How long before re-login required
inactivity: 5m # Timeout after inactivity
remember_me_duration: 1M # "Remember me" checkbox duration
```
**6. Notification Settings**
Email notifications for password resets, 2FA enrollment:
```yaml
notifier:
smtp:
host: smtp.gmail.com
port: 587
username: your-email@gmail.com
password: app-password
sender: authelia@yourdomain.com
```
### No Web UI for Configuration
⚠️ **Important**: Authelia does **not** have a configuration web UI. All configuration is done via YAML files:
- `/opt/stacks/core/authelia/configuration.yml` - Main settings
- `/opt/stacks/core/authelia/users_database.yml` - User accounts
This is **by design** and makes Authelia perfect for AI management and security-first approach:
- AI can read and modify YAML files
- Version control friendly
- No UI clicks required
- Infrastructure as code
- Secure by default
**Web UI Available For:**
- Login page: `https://auth.${DOMAIN}`
- User profile: Change password, enroll 2FA
- Device enrollment: Manage trusted devices
**Alternative with Web UI: Authentik**
If you need a web UI for user management, Authentik is included in the infrastructure stack:
- **Authentik**: Full-featured SSO with web UI for user/group management
- Access at: `https://authentik.${DOMAIN}`
- Includes PostgreSQL database and Redis cache
- More complex but offers GUI-based configuration
- Deploy only if you need web-based user management
**Other Alternatives:**
- **Keycloak**: Enterprise-grade SSO with web UI
- **Authelia + LDAP**: Use LDAP with web management (phpLDAPadmin, etc.)
### Quick Configuration with AI
Since all Authelia configuration is file-based, you can use the AI assistant to:
- Add/remove users
- Modify access rules
- Change session settings
- Update branding
- Enable/disable features
Just ask: "Add a new user to Authelia" or "Change session timeout to 2 hours"
## Storage Recommendations
| Data Type | Recommended Location | Reason |

4
docs/services-reference.md
View File

@@ -1,4 +0,0 @@
# Services Reference
AI instructions:
the contents of this file was moved to services-overview.yaml

41
tasks.txt Normal file
View File

@@ -0,0 +1,41 @@
README.md
Quick setup steps are out of order. the .env file has to be created before running the script
also Run deployment script: remove old login credentials from file
updage all references to 40+ services or similar to 60+
getting-started.md
add ',leave default values for now' to 'Authelia secrets are generated by the setup script.'
remove 'Important: The script generates a secure admin password hash that will be used during deployment. Credentials are displayed at the end and saved to a temporary file.'
remove 'Generates Authelia admin password (saved to /opt/stacks/core/authelia/ADMIN_PASSWORD.txt)'
clarify 'Username: admin' is default, or the user you created
replace 'Password: Check /opt/stacks/core/authelia/ADMIN_PASSWORD.txt or see script output' with 'Password: you set in the setup'
Manual Setup section should be a seperate .md file and linked to
Refine and rename Post-Setup Configuration to Post-Setup Next Steps. for example Configure Authelia section the user password is set by the setup script.
Deploy Additional Stacks
dashboards.yml - Homepage and Homarr - dashboards are already deployed by the script
Service Issues section include a blockquote to recomend using Dozzle to view logs
replace 'Set up Authelia authentication' with 'Set up 2FA with Authelia'
services-references.md
Remove this file.
services-overview.md
In the stacks column all the Container names should be a clickable link to the apropriate service-docs file
remove '⚠️ Disabled:'
remove the Quick Deployments Order section
Authemlia Customization section doesn't belong in this file, it should be elsewhere
quick-reference.md
Deployment Scripts section should like to the readme.md in the scripts folder, instead of restating it.
For later:
reorganize stacks, get *arr apps in one stack, downloaders in another, and transcoders in another. Make Jellyfin the default and put plex in alternatives.
README.md VS Code expanded instructions. launch the code server, and configure it.
Refine backup strategy, backrest as the default