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

Documentation updates

Browse Source
This commit is contained in:
kelinfoxy
2026-01-24 21:40:51 -05:00
parent a1c9a0958b
commit a59862c988
15 changed files with 93 additions and 2026 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -33,7 +33,7 @@ With VS Code connected to your server, you can now use GitHub Copilot to guide y
### 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"
- **Run setup scripts**: "Walk me through running the ez-homelab.sh script"
- **Deploy services**: "Help me run the deployment script"
### AI-Assisted Configuration

66
docs/automated-setup.md
View File

@@ -35,39 +35,18 @@ For most users, the automated setup script handles everything from system prepar
**Note:** The `.env` file stays in the repository folder (`~/EZ-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:**
5. **Run the unified setup script:**
```bash
sudo ./scripts/setup-homelab.sh
./scripts/ez-homelab.sh
```
The script will:
- Update system packages
- Install Docker Engine + Compose V2 (if needed)
- Configure user groups (docker, sudo)
- Set up firewall (UFW)
- Enable SSH server
- **Generate Authelia secrets** (JWT, session, encryption key)
- **Prompt for admin username, password, and email**
- **Generate argon2id password hash** (30-60 seconds)
- Create `/opt/stacks/` directory structure
- Set up Docker networks (homelab, traefik, dockerproxy, media)
- Detect NVIDIA GPU and offer driver installation
**Important:** If NVIDIA drivers were installed, reboot your system now before continuing.
6. **Deploy homelab**:
```bash
sudo ./scripts/deploy-homelab.sh
```
**The deploy script automatically:**
- Creates Docker networks
- Configures Traefik with your email and domain
- **Obtains wildcard SSL certificate** (*.yourdomain.duckdns.org) via DNS challenge
- Deploys core stack (DuckDNS, Traefik, Authelia, Gluetun)
- Deploys infrastructure stack (Dockge, Pi-hole, monitoring)
- Deploys dashboards stack (Homepage, Homarr)
- Opens Dockge in your browser
The script will guide you through:
- System preparation (if needed)
- Domain and credential configuration
- Service stack selection
- Authelia secrets generation
- SSL certificate setup
- Service deployment
**Note:** Certificate generation may take 2-5 minutes. All services will use the wildcard certificate automatically.
@@ -78,11 +57,11 @@ For most users, the automated setup script handles everything from system prepar
**That's it!** Your homelab is ready.
**Access Dockge at `https://dockge.yourdomain.duckdns.org`**
## What the Setup Script Does
## What the Unified Setup Script Does
The `setup-homelab.sh` script is a comprehensive first-run configuration tool:
The `ez-homelab.sh` script is a comprehensive guided setup and deployment tool:
**System Preparation:**
**System Preparation (when needed):**
- ✅ Pre-flight checks (internet connectivity, disk space 50GB+)
- ✅ Updates system packages
- ✅ Installs required packages (git, curl, etc.)
@@ -91,22 +70,25 @@ The `setup-homelab.sh` script is a comprehensive first-run configuration tool:
- ✅ Sets up firewall (UFW with SSH, HTTP, HTTPS)
- ✅ Enables SSH server
**Authelia Configuration (Interactive):**
**Interactive Configuration:**
- ✅ Guides through domain setup (DuckDNS)
- ✅ Prompts for admin username, email, and password
- ✅ Generates three cryptographic secrets (JWT, session, encryption)
- ✅ Prompts for admin username (default: admin)
- ✅ Prompts for secure password with confirmation
- ✅ Prompts for admin email address
- ✅ Generates argon2id password hash using Docker (30-60s process)
- ✅ Validates Docker is available before password operations
- ✅ Saves credentials securely for deployment script
- ✅ Allows service stack selection
- ✅ Validates Docker is available before operations
**Infrastructure Setup:**
**Infrastructure Setup & Deployment:**
- ✅ Creates directory structure (`/opt/stacks/`)
- ✅ Sets up Docker networks (homelab, traefik, dockerproxy, media)
- ✅ Deploys selected service stacks
- ✅ Obtains wildcard SSL certificate (*.yourdomain.duckdns.org)
- ✅ Detects NVIDIA GPU and offers driver installation
- ✅ Opens Dockge when ready
**Safety Features:**
- Skips completed steps (safe to re-run)
- Interactive guidance with clear prompts
- Timeout handling (60s for Docker operations)
- Comprehensive error messages with troubleshooting hints
- Exit on critical failures with clear next steps
- Safe to re-run (idempotent operations)
- Confirmation prompts for destructive actions

4
docs/env-configuration.md
View File

@@ -110,9 +110,9 @@ Set your timezone. Common options:
### 4. Authelia Secrets
**⚠️ IMPORTANT:** These are auto-generated by the setup script. Do NOT set them manually.
**⚠️ IMPORTANT:** These are auto-generated by the unified setup script. Do NOT set them manually.
The `setup-homelab.sh` script will generate secure random secrets for:
The `ez-homelab.sh` script will generate secure random secrets for:
- JWT Secret (64 hex characters)
- Session Secret (64 hex characters)
- Storage Encryption Key (64 hex characters)

4
docs/getting-started.md
View File

@@ -6,9 +6,7 @@ Welcome to your AI-powered homelab! This guide will walk you through setting up
- [ ] Clone this repository to your home folder
- [ ] Configure `.env` file with your domain and tokens ([see prerequisites](env-configuration.md))
- [ ] Forward ports 80 and 443 from your router to your server
- [ ] Run setup script (generates Authelia secrets and admin user) ([setup-homelab.sh](../scripts/setup-homelab.sh))
- [ ] Log out and back in for Docker group permissions
- [ ] Run deployment script (deploys all core, infrastructure & dashboard services) ([deploy-homelab.sh](../scripts/deploy-homelab.sh))
- [ ] Run unified setup script (generates Authelia secrets and admin user, deploys services) ([ez-homelab.sh](../scripts/ez-homelab.sh))
- [ ] Access Dockge web UI (`https://dockge.${DOMAIN}`)
- [ ] 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))

10
docs/manual-setup.md
View File

@@ -205,12 +205,12 @@ docker network create network-name
## Switching to Automated
If manual setup works, you can switch to the automated scripts for future updates:
If manual setup works, you can switch to the unified automated script for future updates:
```bash
# Just run the deploy script
cd ~/AI-Homelab
sudo ./scripts/deploy-homelab.sh
# Just run the unified setup script
cd ~/EZ-Homelab
./scripts/ez-homelab.sh
```
The deploy script is idempotent - it won't break existing configurations.
The unified script is idempotent - it won't break existing configurations.

16
docs/quick-reference.md
View File

@@ -26,8 +26,7 @@ Your homelab uses separate stacks for organization:
For detailed information about the deployment scripts, their features, and usage, see [scripts/README.md](../scripts/README.md).
**Quick summary:**
- `setup-homelab.sh` - First-run system setup and Authelia configuration
- `deploy-homelab.sh` - Deploy all core services and prepare additional stacks
- `ez-homelab.sh` - Unified setup and deployment script (system prep, secrets generation, service deployment)
- `reset-test-environment.sh` - Testing/development only - removes all deployed services
- `reset-ondemand-services.sh` - Reload services for Sablier lazy loading
@@ -530,15 +529,10 @@ deploy:
### Minimal setup
```bash
# Clone and configure
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab
sudo ./scripts/setup-homelab.sh
cp .env.example .env
nano .env
# Deploy core only
mkdir -p /opt/stacks/core
cp docker-compose/core/docker-compose.yml /opt/stacks/core/docker-compose.yml
git clone https://github.com/kelinfoxy/EZ-Homelab.git
cd EZ-Homelab
./scripts/ez-homelab.sh
```
cp -r config-templates/traefik /opt/stacks/core/
cp -r config-templates/authelia /opt/stacks/core/
cp .env /opt/stacks/core/

13
docs/troubleshooting/COMMON-ISSUES.md
View File

@@ -95,8 +95,8 @@ docker compose up -d
**Solution:**
```bash
# Re-run deployment script (safe - won't affect running services)
sudo ./scripts/deploy-homelab.sh
# Re-run unified setup script (safe - won't affect running services)
./scripts/ez-homelab.sh
# Or manually fix:
cd /opt/stacks/dashboards/homepage
@@ -181,8 +181,8 @@ sudo systemctl stop systemd-resolved
# Check what exists
ls -la /opt/stacks/
# Re-run deployment to copy stacks
sudo ./scripts/deploy-homelab.sh
# Re-run unified setup script to copy stacks
./scripts/ez-homelab.sh
```
## Performance Issues
@@ -233,9 +233,8 @@ sudo docker logs authelia
# Use the safe reset script
sudo ./scripts/reset-test-environment.sh
# Then re-run setup and deploy
sudo ./scripts/setup-homelab.sh
sudo ./scripts/deploy-homelab.sh
# Then re-run unified setup script
./scripts/ez-homelab.sh
```
### Partial Reset (Single Stack)