EZ-Homelab/docs/getting-started.md

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 60+ services.

Getting Started Checklist

• Clone this repository to your home folder
• Configure .env file with your domain and tokens
• Run setup script (generates Authelia secrets and admin user)
• Log out and back in for Docker group permissions
• Run deployment script (deploys all core, infrastructure & dashboard services)
• Access Dockge web UI
• Set up 2FA with Authelia
• (optional) Deploy additional stacks as needed via Dockge
• Configure and use VS Code with Github Copilot to manage the server

Quick Setup (Recommended)

For most users, the automated setup script handles everything:

Prerequisites

• Fresh Debian/Ubuntu server (or existing system)
• Root/sudo access
• Internet connection
• VS Code with GitHub Copilot (for AI assistance)

Simple Setup

1. Connect to your server via SSH

   Tip: Use VS Code on your local machine to ssh
   in to your server for the easiest install!

2. Install git if needed

      sudo apt update && sudo apt upgrade -y && sudo apt install git
   

3. Clone the rep:

   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homeb
   

4. Configure environment:

   cp .env.example .env
   nano .env  # Edit with your domain and tokens
   

   Required variables in .env:

   • DOMAIN - Your DuckDNS domain (e.g., yourdomain.duckdns.org)
   • DUCKDNS_TOKEN - Your DuckDNS token from duckdns.org
   • 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 (JWT, session, encryption key) are auto-generated by the setup script - leave them with default values for now.

5. Run the setup script:

   sudo ./scripts/setup-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

6. Log out and back in (or run newgrp docker)

   Don't skip this step!
   Required for Docker group permissions.

7. Deploy homelab:

   ./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

   Note: Certificate generation may take 2-5 minutes. All services will use the wildcard certificate automatically.

   Login credentials:

   • 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

What the Setup Script Does

The setup-homelab.sh script is a comprehensive first-run configuration tool:

System Preparation:

• ✅ Pre-flight checks (internet connectivity, disk space 50GB+)
• ✅ Updates system packages
• ✅ Installs required packages (git, curl, etc.)
• ✅ Installs Docker Engine + Compose V2 (if not present)
• ✅ Configures user permissions (docker, sudo groups)
• ✅ Sets up firewall (UFW with SSH, HTTP, HTTPS)
• ✅ Enables SSH server

Authelia Configuration (Interactive):

• ✅ 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

Infrastructure Setup:

• ✅ Creates directory structure (/opt/stacks/)
• ✅ Sets up Docker networks (homelab, traefik, dockerproxy, media)
• ✅ Detects NVIDIA GPU and offers driver installation

Safety Features:

• Skips completed steps (safe to re-run)
• Timeout handling (60s for Docker operations)
• Comprehensive error messages with troubleshooting hints
• Exit on critical failures with clear next steps

Manual Setup (Alternative)

If you prefer manual control or the automated script fails, see the Manual Setup Guide for step-by-step instructions on installing Docker, configuring services, and deploying the homelab manually.

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

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:

• 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
2. Get API keys from services
3. Configure widgets in /opt/stacks/dashboards/homepage/config/

VS Code Integration

1. Install VS Code and GitHub Copilot
2. Open the AI-Homelab repository
3. Use AI assistance for:
   • Adding new services
   • Configuring Traefik routing
   • Managing Docker stacks

Debloat or add custom service

Use VS Code on the server or on your local machine
Tell the chat Agent what changes to make to the server.

Be sure to choose an LLM that is good at code.

Tell the AI what service you want to install or give it a docker based github repository or docker hub image. Use your imagination, the copilot instructions are configured with best practices and a framework to add new services.

Troubleshooting

Script Issues

• Permission denied: Run with sudo
• Docker not found: Log out/in or run newgrp docker
• Network conflicts: Check existing networks with docker network ls

Service Issues

• Can't access services: Check Traefik dashboard at https://traefik.yourdomain.duckdns.org
• SSL certificate errors: Wait 2-5 minutes for wildcard certificate to be obtained from Let's Encrypt
  • Check status: python3 -c "import json; d=json.load(open('/opt/stacks/core/traefik/acme.json')); print(f'Certificates: {len(d[\"letsencrypt\"][\"Certificates\"])}')"
  • 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

# Restart Docker
sudo systemctl restart docker

# Check service logs
cd /opt/stacks/stack-name
docker compose logs -f

# Rebuild service
docker compose up -d --build service-name

Next Steps

1. Explore services through Dockge
2. Configure backups with Backrest/Duplicati
3. Set up monitoring with Grafana/Prometheus
4. Add external services via Traefik proxying
5. Use AI assistance for custom configurations

Happy homelabbing! 🚀