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

Create deployment script and restructure Quick Setup with automated workflow

Browse Source 
- Create deploy-homelab.sh script for automated deployment
  - Validates prerequisites (Docker, .env file)
  - Creates required directories and networks
  - Deploys core stack (DuckDNS, Traefik, Authelia, Gluetun)
  - Deploys infrastructure stack (Dockge, Portainer, etc.)
  - Waits for Dockge web UI to be ready
  - Automatically opens browser to Dockge when accessible
  - Comprehensive error checking and user feedback

- Restructure README Quick Setup section
  - Step 1: Clone repository
  - Step 2: (Optional) Run setup-homelab.sh for fresh Debian installations
  - Step 3: Create and configure .env file
  - Step 4: Run deploy-homelab.sh (automated deployment with browser launch)
  - Step 5: Deploy additional stacks through Dockge web UI
  - Include manual deployment alternative for advanced users

- Update scripts/README.md documentation
  - Document both setup-homelab.sh and deploy-homelab.sh
  - Clear usage instructions for each script
  - Browser detection details
  - Troubleshooting section
  - Manual deployment alternatives

Key improvements:
- User only needs to run 2 scripts (setup optional, deploy required)
- Automated browser launch when Dockge is ready
- No manual directory creation or network setup needed
- Smart wait logic ensures UI is accessible before opening browser
- Better user experience with clear progress indicators

Co-authored-by: kelinfoxy <67766943+kelinfoxy@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-01-12 04:17:57 +00:00
parent afe057c543
commit b5eac0b1e9
3 changed files with 412 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
README.md
View File

@@ -43,52 +43,80 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
cd AI-Homelab cd AI-Homelab
``` ```
2. **Create environment file:** 2. **(Optional) Run first-run setup script:**
**For fresh Debian installations only**, this automated script will:
- Update system and install Docker Engine + Compose V2
- Configure user groups (sudo, docker) and SSH access
- Detect NVIDIA GPU and provide driver installation guidance
- Create directory structure and Docker networks
```bash
sudo ./scripts/setup-homelab.sh
```
After completion, log out and log back in for group changes to take effect.
**Skip this step if Docker is already installed and configured.**
3. **Create and configure environment file:**
```bash ```bash
cp .env.example .env cp .env.example .env
# Edit .env with your values (domain, API keys, passwords) nano .env # Edit with your domain, API keys, and passwords
nano .env
``` ```
**Required variables:**
- `DOMAIN` - Your DuckDNS domain (e.g., yourhomelab.duckdns.org)
- `DUCKDNS_TOKEN` - Token from DuckDNS.org
- `TZ` - Your timezone (e.g., America/New_York)
- Authelia user credentials
- API keys for services you plan to use
3. **Create required directories:** 4. **Run deployment script:**
This automated script will:
- Create required directories
- Verify Docker networks exist
- Deploy core infrastructure (DuckDNS, Traefik, Authelia, Gluetun)
- Deploy infrastructure stack with Dockge
- Wait for Dockge to be ready
- Automatically open Dockge in your browser
```bash ```bash
sudo mkdir -p /opt/stacks ./scripts/deploy-homelab.sh
sudo chown -R $USER:$USER /opt/stacks
``` ```
4. **Create Docker networks:** The script will automatically open `https://dockge.yourdomain.duckdns.org` when ready.
**Manual deployment alternative:**
```bash ```bash
docker network create homelab-network # Deploy core stack
docker network create traefik-network
docker network create media-network
```
5. **Deploy core infrastructure stack:**
```bash
# Deploy the unified core stack (DuckDNS, Traefik, Authelia, Gluetun)
mkdir -p /opt/stacks/core mkdir -p /opt/stacks/core
cp docker-compose/core.yml /opt/stacks/core/docker-compose.yml cp docker-compose/core.yml /opt/stacks/core/docker-compose.yml
cp -r config-templates/traefik /opt/stacks/core/ cp -r config-templates/traefik /opt/stacks/core/
cp -r config-templates/authelia /opt/stacks/core/ cp -r config-templates/authelia /opt/stacks/core/
cp .env /opt/stacks/core/
# From within the directory
cd /opt/stacks/core && docker compose up -d cd /opt/stacks/core && docker compose up -d
# OR from anywhere with full path # Deploy infrastructure stack
docker compose -f /opt/stacks/core/docker-compose.yml up -d
```
6. **Deploy infrastructure stack (includes Dockge):**
```bash
mkdir -p /opt/stacks/infrastructure mkdir -p /opt/stacks/infrastructure
cp docker-compose/infrastructure.yml /opt/stacks/infrastructure/docker-compose.yml cp docker-compose/infrastructure.yml /opt/stacks/infrastructure/docker-compose.yml
cp .env /opt/stacks/infrastructure/
cd /opt/stacks/infrastructure && docker compose up -d cd /opt/stacks/infrastructure && docker compose up -d
# Manually open: https://dockge.yourdomain.duckdns.org
``` ```
7. **Access Dockge:** 5. **Deploy additional stacks through Dockge:**
Open `https://dockge.yourdomain.duckdns.org` (use Authelia login)
Now deploy remaining stacks through Dockge's UI! Log in to Dockge with your Authelia credentials and deploy additional stacks:
- `dashboards.yml` - Homepage and Homarr dashboards
- `media.yml` - Plex, Jellyfin, Sonarr, Radarr, Prowlarr, qBittorrent
- `media-extended.yml` - Readarr, Lidarr, Lazy Librarian, Mylar3, Calibre-Web
- `homeassistant.yml` - Home Assistant, ESPHome, Node-RED, and accessories
- `productivity.yml` - Nextcloud, Gitea, WordPress, wikis
- `monitoring.yml` - Grafana, Prometheus, Loki
- `utilities.yml` - Backups, code editors, password manager
## Repository Structure ## Repository Structure

122
scripts/README.md
View File

@@ -1,8 +1,13 @@
# AI-Homelab Setup Scripts # AI-Homelab Setup Scripts
This directory contains two scripts for automated AI-Homelab deployment:
1. **setup-homelab.sh** - System preparation (optional, for fresh installations)
2. **deploy-homelab.sh** - Core infrastructure deployment
## setup-homelab.sh ## setup-homelab.sh
Automated first-run setup script for preparing a fresh Debian installation for AI-Homelab deployment. Automated first-run setup script for preparing a fresh Debian installation for AI-Homelab deployment. **This is optional** - skip if Docker is already installed and configured.
### What It Does ### What It Does
@@ -33,9 +38,7 @@ sudo ./scripts/setup-homelab.sh
1. Log out and log back in for group changes to take effect 1. Log out and log back in for group changes to take effect
2. Edit `.env` file with your configuration 2. Edit `.env` file with your configuration
3. Deploy the core infrastructure stack 3. Run `deploy-homelab.sh` to deploy core infrastructure and Dockge
4. Deploy the infrastructure stack (includes Dockge)
5. Access Dockge to manage remaining stacks
### NVIDIA GPU Support ### NVIDIA GPU Support
@@ -72,3 +75,114 @@ This manual approach avoids driver conflicts that often occur with automated ins
- Configures Docker networks automatically - Configures Docker networks automatically
- SSH is enabled for remote management - SSH is enabled for remote management
- NVIDIA driver installation requires manual intervention for reliability - NVIDIA driver installation requires manual intervention for reliability
---
## 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, Authelia, and Gluetun
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)

239
scripts/deploy-homelab.sh Executable file
View File

@@ -0,0 +1,239 @@
#!/bin/bash
# AI-Homelab Deployment Script
# This script deploys the core infrastructure and Dockge
# Run after: 1) setup-homelab.sh and 2) editing .env file
# Run as: ./deploy-homelab.sh
set -e # Exit on error
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Log functions
log_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
log_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
log_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Check if running as root
if [ "$EUID" -eq 0 ]; then
log_error "Please do NOT run this script as root or with sudo"
log_info "Run as: ./deploy-homelab.sh"
exit 1
fi
# Get script directory (AI-Homelab/scripts)
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
REPO_DIR="$( cd "$SCRIPT_DIR/.." && pwd )"
log_info "AI-Homelab Deployment Script"
echo ""
# Check if .env file exists
if [ ! -f "$REPO_DIR/.env" ]; then
log_error ".env file not found!"
log_info "Please create and configure your .env file first:"
echo " cd $REPO_DIR"
echo " cp .env.example .env"
echo " nano .env"
exit 1
fi
# Check if Docker is installed and running
if ! command -v docker &> /dev/null; then
log_error "Docker is not installed. Please run setup-homelab.sh first."
exit 1
fi
if ! docker info &> /dev/null; then
log_error "Docker daemon is not running or you don't have permission."
log_info "Try: sudo systemctl start docker"
log_info "Or log out and log back in for group changes to take effect"
exit 1
fi
log_success "Docker is available and running"
echo ""
# Load environment variables for domain check
source "$REPO_DIR/.env"
if [ -z "$DOMAIN" ]; then
log_error "DOMAIN is not set in .env file"
log_info "Please edit .env and set your DuckDNS domain"
exit 1
fi
log_info "Using domain: $DOMAIN"
echo ""
# Step 1: Create required directories
log_info "Step 1/5: Creating required directories..."
mkdir -p /opt/stacks/core
mkdir -p /opt/stacks/infrastructure
mkdir -p /opt/dockge/data
log_success "Directories created"
echo ""
# Step 2: Create Docker networks (if they don't exist)
log_info "Step 2/5: Creating Docker networks..."
docker network create homelab-network 2>/dev/null && log_success "Created homelab-network" || log_info "homelab-network already exists"
docker network create traefik-network 2>/dev/null && log_success "Created traefik-network" || log_info "traefik-network already exists"
docker network create media-network 2>/dev/null && log_success "Created media-network" || log_info "media-network already exists"
echo ""
# Step 3: Deploy core infrastructure (DuckDNS, Traefik, Authelia, Gluetun)
log_info "Step 3/5: Deploying core infrastructure stack..."
log_info " - DuckDNS (Dynamic DNS)"
log_info " - Traefik (Reverse Proxy with SSL)"
log_info " - Authelia (Single Sign-On)"
log_info " - Gluetun (VPN Client)"
echo ""
# Copy core stack files
cp "$REPO_DIR/docker-compose/core.yml" /opt/stacks/core/docker-compose.yml
cp -r "$REPO_DIR/config-templates/traefik" /opt/stacks/core/
cp -r "$REPO_DIR/config-templates/authelia" /opt/stacks/core/
cp "$REPO_DIR/.env" /opt/stacks/core/.env
# Deploy core stack
cd /opt/stacks/core
docker compose up -d
log_success "Core infrastructure deployed"
echo ""
# Wait for Traefik to be ready
log_info "Waiting for Traefik to initialize..."
sleep 10
# Check if Traefik is healthy
if docker ps | grep -q "traefik.*Up"; then
log_success "Traefik is running"
else
log_warning "Traefik container check inconclusive, continuing..."
fi
echo ""
# Step 4: Deploy infrastructure stack (Dockge and monitoring tools)
log_info "Step 4/5: Deploying infrastructure stack..."
log_info " - Dockge (Docker Compose Manager)"
log_info " - Portainer (Alternative Docker UI)"
log_info " - Pi-hole (DNS Ad Blocker)"
log_info " - Watchtower (Container Updates)"
log_info " - Dozzle (Log Viewer)"
log_info " - Glances (System Monitor)"
log_info " - Docker Proxy (Security)"
echo ""
# Copy infrastructure stack
cp "$REPO_DIR/docker-compose/infrastructure.yml" /opt/stacks/infrastructure/docker-compose.yml
cp "$REPO_DIR/.env" /opt/stacks/infrastructure/.env
# Deploy infrastructure stack
cd /opt/stacks/infrastructure
docker compose up -d
log_success "Infrastructure stack deployed"
echo ""
# Step 5: Wait for Dockge to be ready and open browser
log_info "Step 5/5: Waiting for Dockge web UI to be ready..."
DOCKGE_URL="https://dockge.${DOMAIN}"
MAX_WAIT=60 # Maximum wait time in seconds
WAITED=0
# Function to check if Dockge is accessible
check_dockge() {
# Try to connect to Dockge (ignore SSL cert warnings for self-signed during startup)
curl -k -s -o /dev/null -w "%{http_code}" "$DOCKGE_URL" 2>/dev/null
}
# Wait for Dockge to respond
while [ $WAITED -lt $MAX_WAIT ]; do
HTTP_CODE=$(check_dockge)
if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "302" ] || [ "$HTTP_CODE" = "401" ]; then
log_success "Dockge web UI is ready!"
break
fi
echo -n "."
sleep 2
WAITED=$((WAITED + 2))
done
echo ""
echo ""
if [ $WAITED -ge $MAX_WAIT ]; then
log_warning "Dockge did not respond within ${MAX_WAIT} seconds"
log_info "It may still be starting up. Check manually at: $DOCKGE_URL"
else
# Try to open browser
log_info "Opening Dockge in your browser..."
# Detect and use available browser
if command -v xdg-open &> /dev/null; then
xdg-open "$DOCKGE_URL" &> /dev/null &
log_success "Browser opened"
elif command -v gnome-open &> /dev/null; then
gnome-open "$DOCKGE_URL" &> /dev/null &
log_success "Browser opened"
elif command -v firefox &> /dev/null; then
firefox "$DOCKGE_URL" &> /dev/null &
log_success "Browser opened"
elif command -v google-chrome &> /dev/null; then
google-chrome "$DOCKGE_URL" &> /dev/null &
log_success "Browser opened"
else
log_warning "No browser detected. Please manually open: $DOCKGE_URL"
fi
fi
echo ""
echo "=========================================="
log_success "Deployment completed successfully!"
echo "=========================================="
echo ""
log_info "Access your services:"
echo ""
echo " 🚀 Dockge: $DOCKGE_URL"
echo " 🔒 Authelia: https://auth.${DOMAIN}"
echo " 🔀 Traefik: https://traefik.${DOMAIN}"
echo ""
log_info "Next steps:"
echo ""
echo " 1. Log in to Dockge using your Authelia credentials"
echo " (configured in /opt/stacks/core/authelia/users_database.yml)"
echo ""
echo " 2. Deploy additional stacks through Dockge's web UI:"
echo " - dashboards.yml (Homepage, Homarr)"
echo " - media.yml (Plex, Jellyfin, Sonarr, Radarr, etc.)"
echo " - media-extended.yml (Readarr, Lidarr, etc.)"
echo " - homeassistant.yml (Home Assistant and accessories)"
echo " - productivity.yml (Nextcloud, Gitea, wikis)"
echo " - monitoring.yml (Grafana, Prometheus, etc.)"
echo " - utilities.yml (Backups, code editors, etc.)"
echo ""
echo " 3. Configure services via the AI assistant in VS Code"
echo ""
echo "=========================================="
echo ""
log_info "For documentation, see: $REPO_DIR/docs/"
log_info "For troubleshooting, see: $REPO_DIR/docs/quick-reference.md"
echo ""