EZ-Homelab/docs/automated-setup.md

Automated Setup (Recommended)

For most users, the automated setup script handles everything from system preparation to deployment.

Prerequisites

• Fresh Debian/Ubuntu server (or existing system)
• Root/sudo access
• Internet connection
• Ports 80 and 443 forwarded from your router to your core server only (required for SSL certificates)
• VS Code with GitHub Copilot (for AI assistance)

Note: For multi-server setups, only the core server needs ports forwarded. Remote servers connect via Docker TLS (port 2376).

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 repository:

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

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 (~/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 unified setup script:

   ./scripts/ez-homelab.sh
   

   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.

   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

Multi-Server Setup

To deploy services across multiple servers (e.g., Raspberry Pi, mini PCs):

Core Server Setup (First)

1. Follow the main setup above (steps 1-5)
2. This server gets ports 80/443 forwarded from your router
3. This server generates the shared CA for Docker TLS communication

Remote Server Setup (After Core)

1. Clone repository on remote server:

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

2. Copy .env from core server:

   # On core server
   cd ~/EZ-Homelab
   cat .env  # Copy the contents
   
   # On remote server
   nano ~/EZ-Homelab/.env  # Paste and save
   

3. Run setup with Infrastructure-Only option:

   ./scripts/ez-homelab.sh
   # Select option 3: "Deploy Infrastructure Only (Remote Server)"
   

4. When prompted, provide core server IP for CA import

5. Script automatically:

   • Copies shared CA from core server via SSH
   • Configures Docker TLS with shared certificates
   • Generates server certificates signed by shared CA
   • Sets up Docker daemon for TLS on port 2376
   • Deploys Traefik for local container discovery
   • Deploys Sablier for local lazy loading

What Gets Deployed Where

Component	Core Server	Remote Servers
DuckDNS	✅ Yes	❌ No
Authelia	✅ Yes	❌ No
Traefik	✅ Yes (multi-provider)	✅ Yes (local only)
Sablier	✅ Yes (own stack)	✅ Yes (own stack)
Dockge	✅ Yes	✅ Yes
Services	✅ Any	✅ Any

Architecture Benefits

• Single Domain: All services accessible via core server's domain
• No Port Forwarding: Remote servers don't need router configuration
• Automatic Discovery: Core Traefik finds services on all servers
• Local Control: Each Sablier manages its own server's containers
• Secure Communication: All inter-server traffic uses TLS encryption

Troubleshooting Multi-Server Setup

If remote server setup fails:

1. Check SSH access from remote to core server
2. Verify firewall allows port 2376 on remote servers
3. Test TLS connection from core:

   cd /opt/stacks/core/shared-ca
   docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem \
     --tlskey=key.pem --host=tcp://REMOTE_IP:2376 ps
   

4. Check logs: See setup script output for specific errors

What the Unified Setup Script Does

The ez-homelab.sh script is a comprehensive guided setup and deployment tool:

System Preparation (when needed):

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

Interactive Configuration:

• ✅ Guides through domain setup (DuckDNS)
• ✅ Prompts for admin username, email, and password
• ✅ Generates three cryptographic secrets (JWT, session, encryption)
• ✅ Generates argon2id password hash using Docker (30-60s process)
• ✅ Allows service stack selection
• ✅ Validates Docker is available before operations

Infrastructure Setup & Deployment:

• ✅ Creates directory structure (/opt/stacks/)
• ✅ Sets up Docker networks (homelab, traefik, dockerproxy, media)
• ✅ Deploys selected service stacks with individual deployment scripts
• ✅ Obtains wildcard SSL certificate (*.yourdomain.duckdns.org)
• ✅ Configures Traefik for multi-server support (if applicable)
• ✅ Generates and distributes TLS certificates for Docker API (multi-server)
• ✅ Detects NVIDIA GPU and offers driver installation
• ✅ Opens Dockge when ready

Safety Features:

• Interactive guidance with clear prompts
• Timeout handling (60s for Docker operations)
• Comprehensive error messages with troubleshooting hints
• Safe to re-run (idempotent operations)
• Confirmation prompts for destructive actions

Release-Specific Notes

• Current Version: Production-ready with comprehensive multi-server support
• Stacks: Core, Infrastructure, Sablier, and Dashboards deploy automatically
• Dashboards: Homepage is preconfigured at homepage.yourdomain.duckdns.org
• Multi-Server: Use option 3 for remote server infrastructure deployment
• Modular Deployment: Individual scripts in docker-compose/*/deploy-*.sh called by ez-homelab.sh