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

167
scripts/README.md
View File

@@ -1,20 +1,18 @@
# AI-Homelab Setup Scripts
# EZ-Homelab Setup Scripts
This directory contains scripts for automated AI-Homelab deployment and management:
This directory contains scripts for automated EZ-Homelab deployment and management:
1. **setup-homelab.sh** - System preparation
2. **deploy-homelab.sh** - Core infrastructure deployment
3. **reset-test-environment.sh** - Safe test environment cleanup
4. **reset-ondemand-services.sh** - Reload services for Sablier lazy loading
1. **ez-homelab.sh** - Unified setup and deployment script
2. **reset-test-environment.sh** - Safe test environment cleanup
3. **reset-ondemand-services.sh** - Reload services for Sablier lazy loading
## setup-homelab.sh
## ez-homelab.sh
Automated first-run setup script for preparing a fresh Debian installation for AI-Homelab deployment.
> You can skip this if you have the following completed already.
Or run it to verify.
Unified guided setup and deployment script that handles both system preparation and service deployment in a single interactive session.
### What It Does
**System Preparation (when needed):**
1. **System Update** - Updates all system packages
2. **Install Dependencies** - Installs required packages (curl, git, etc.)
3. **Install Docker** - Adds Docker repository and installs Docker Engine with Compose V2
@@ -24,23 +22,40 @@ Or run it to verify.
7. **Create Directories** - Sets up `/opt/stacks`, `/opt/dockge`, `/mnt/media`, `/mnt/downloads`
8. **Create Docker Networks** - Creates homelab-network, traefik-network, and media-network
**Configuration & Deployment:**
1. **Interactive Setup** - Guides you through domain, admin credentials, and service selection
2. **Authelia Secrets Generation** - Generates JWT, session, and encryption keys
3. **Admin User Creation** - Prompts for admin username, email, and password
4. **Service Deployment** - Deploys selected stacks based on your choices
5. **SSL Certificate Setup** - Obtains wildcard certificate via DNS challenge
6. **Dockge Access** - Opens Dockge web UI when ready
### Usage
```bash
cd ~/AI-Homelab
cd ~/EZ-Homelab
# Make the script executable (if needed)
chmod +x scripts/setup-homelab.sh
chmod +x scripts/ez-homelab.sh
# Run with sudo
sudo ./scripts/setup-homelab.sh
# Run the script (will use sudo when needed)
./scripts/ez-homelab.sh
```
### Interactive Options
The script will prompt you to:
- Enter your domain (e.g., yourdomain.duckdns.org)
- Provide DuckDNS token
- Set admin credentials for Authelia
- Choose which service stacks to deploy
- Configure additional settings as needed
### After Running
1. Log out and log back in for group changes to take effect
2. Edit `.env` file with your configuration
3. Run `deploy-homelab.sh` to deploy core infrastructure and Dockge
1. Access Dockge at `https://dockge.yourdomain.duckdns.org`
2. Log in with your configured Authelia credentials
3. Deploy additional stacks through Dockge's web UI
### NVIDIA GPU Support
@@ -61,14 +76,16 @@ This manual approach avoids driver conflicts that often occur with automated ins
### Requirements
- Fresh Debian installation (Debian 11 or 12)
- Fresh Debian/Ubuntu installation (or existing system)
- Root access (via sudo)
- Internet connection
- Ports 80 and 443 forwarded to your server
### Tested On
- Debian 11 (Bullseye)
- Debian 12 (Bookworm)
- Ubuntu 20.04/22.04
### Notes
@@ -80,117 +97,6 @@ This manual approach avoids driver conflicts that often occur with automated ins
---
## deploy-homelab.sh
Automated deployment script that deploys the core infrastructure and Dockge. Run this after editing your `.env` file.
### What It Does
1. **Validate Prerequisites** - Checks for Docker, .env file, and proper configuration
2. **Create Directories** - Sets up `/opt/stacks/core` and `/opt/stacks/infrastructure`
3. **Create Docker Networks** - Ensures homelab-network, traefik-network, and media-network exist
4. **Deploy Core Stack** - Deploys DuckDNS, Traefik, and Authelia
5. **Deploy Infrastructure Stack** - Deploys Dockge, Portainer, Pi-hole, and monitoring tools
6. **Wait for Dockge** - Waits for Dockge web UI to become accessible
7. **Open Browser** - Automatically opens Dockge in your default browser
### Usage
```bash
# From the AI-Homelab directory
cd AI-Homelab
# Ensure .env is configured
cp .env.example .env
nano .env # Edit with your values
# Make the script executable (if needed)
chmod +x scripts/deploy-homelab.sh
# Run WITHOUT sudo (run as your regular user)
./scripts/deploy-homelab.sh
```
### After Running
The script will automatically open `https://dockge.yourdomain.duckdns.org` in your browser when Dockge is ready.
1. Log in to Dockge using your Authelia credentials (configured in `/opt/stacks/core/authelia/users_database.yml`)
2. Deploy additional stacks through Dockge's web UI:
- `dashboards.yml` - Homepage and Homarr
- `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
- `utilities.yml` - Backups, password manager
### Requirements
- Docker and Docker Compose installed
- `.env` file configured with your domain and credentials
- User must be in docker group (handled by setup-homelab.sh)
### Browser Detection
The script will attempt to open Dockge using:
- `xdg-open` (default on most Linux desktops)
- `gnome-open` (GNOME desktop)
- `firefox` or `google-chrome` (direct browser launch)
If no browser is detected, it will display the URL for manual access.
### Manual Deployment Alternative
If you prefer to deploy manually instead of using the script:
```bash
# Deploy core stack
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 -r config-templates/authelia /opt/stacks/core/
cp .env /opt/stacks/core/
cd /opt/stacks/core && docker compose up -d
# Deploy infrastructure stack
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
# Manually open: https://dockge.yourdomain.duckdns.org
```
### Troubleshooting
**Script says "Docker daemon is not running":**
- Run: `sudo systemctl start docker`
- Or log out and back in if you just added yourself to docker group
**Script says ".env file not found":**
- Run: `cp .env.example .env` and edit with your values
**Dockge doesn't open automatically:**
- The script will display the URL to open manually
- Wait a minute for services to fully start
- Check logs: `docker compose -f /opt/stacks/infrastructure/docker-compose.yml logs dockge`
**Traefik SSL certificate errors:**
- Initial certificate generation can take a few minutes
- Check DuckDNS token is correct in .env
- Verify your domain is accessible from the internet
### Notes
- Run as regular user (NOT with sudo)
- Validates .env configuration before deployment
- Waits up to 60 seconds for Dockge to become ready
- Automatically copies .env to stack directories
- Safe to run multiple times (idempotent)
---
## reset-test-environment.sh
Safe cleanup script for testing environments. Completely removes all deployed services, data, and configurations while preserving the underlying system setup. Intended for development and testing scenarios only.
@@ -231,8 +137,7 @@ sudo ./scripts/reset-test-environment.sh
The system will be returned to a clean state ready for re-deployment:
1. Ensure `.env` file is properly configured
2. Run: `sudo ./scripts/setup-homelab.sh` (if needed)
3. Run: `./scripts/deploy-homelab.sh`
2. Run: `./scripts/ez-homelab.sh`
### Requirements