From b5eac0b1e99d5c0f3c854275bb500c6833bb9fbc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 12 Jan 2026 04:17:57 +0000 Subject: [PATCH] Create deployment script and restructure Quick Setup with automated workflow - 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> --- README.md | 82 ++++++++----- scripts/README.md | 122 ++++++++++++++++++- scripts/deploy-homelab.sh | 239 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 412 insertions(+), 31 deletions(-) create mode 100755 scripts/deploy-homelab.sh diff --git a/README.md b/README.md index aa1785c..2586784 100644 --- a/README.md +++ b/README.md @@ -43,52 +43,80 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f 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 cp .env.example .env - # Edit .env with your values (domain, API keys, passwords) - nano .env + nano .env # Edit with your domain, API keys, and passwords ``` + + **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 - sudo mkdir -p /opt/stacks - sudo chown -R $USER:$USER /opt/stacks + ./scripts/deploy-homelab.sh ``` - -4. **Create Docker networks:** + + The script will automatically open `https://dockge.yourdomain.duckdns.org` when ready. + + **Manual deployment alternative:** ```bash - docker network create homelab-network - 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) + # 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/ - - # From within the directory + cp .env /opt/stacks/core/ cd /opt/stacks/core && docker compose up -d - # OR from anywhere with full path - docker compose -f /opt/stacks/core/docker-compose.yml up -d - ``` - -6. **Deploy infrastructure stack (includes Dockge):** - ```bash + # 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 ``` -7. **Access Dockge:** - Open `https://dockge.yourdomain.duckdns.org` (use Authelia login) +5. **Deploy additional stacks through Dockge:** - 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 diff --git a/scripts/README.md b/scripts/README.md index 59afdf3..87a509b 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,8 +1,13 @@ # 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 -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 @@ -33,9 +38,7 @@ sudo ./scripts/setup-homelab.sh 1. Log out and log back in for group changes to take effect 2. Edit `.env` file with your configuration -3. Deploy the core infrastructure stack -4. Deploy the infrastructure stack (includes Dockge) -5. Access Dockge to manage remaining stacks +3. Run `deploy-homelab.sh` to deploy core infrastructure and Dockge ### NVIDIA GPU Support @@ -72,3 +75,114 @@ This manual approach avoids driver conflicts that often occur with automated ins - Configures Docker networks automatically - SSH is enabled for remote management - 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) diff --git a/scripts/deploy-homelab.sh b/scripts/deploy-homelab.sh new file mode 100755 index 0000000..51c9770 --- /dev/null +++ b/scripts/deploy-homelab.sh @@ -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 ""