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

Update documentation files with recent tweaks

Browse Source
This commit is contained in:
Kelin
2026-02-08 18:42:16 -05:00
parent 0de82e55b6
commit 30143d5f75
5 changed files with 94 additions and 1659 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
docs/automated-setup.md
View File

@@ -7,109 +7,61 @@ For most users, the automated setup script handles everything from system prepar
- **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).
**Note**: For multi-server setups, only the core server needs ports forwarded.
## Simple Setup
# Deploy Core Server
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!
## 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**
## Install commands
```bash
sudo apt update && sudo apt upgrade -y && sudo apt install git
```
3. **Clone the repository**:
```bash
git clone https://github.com/kelinfoxy/EZ-Homelab.git
cd EZ-Homelab
```
4. **Configure environment**:
```bash
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](https://www.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:**
```bash
./scripts/ez-homelab.sh
sudo apt update && sudo apt upgrade -y && sudo apt install git -y && git clone https://github.com/kelinfoxy/EZ-Homelab.git
&& cd EZ-Homelab
```
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
## Run the ez-homelab.sh script with sudo:
`sudo ./scripts/ez-homelab.sh`
**Note:** Certificate generation may take 2-5 minutes. All services will use the wildcard certificate automatically.
### Select option 1 Install Prerequesites
* This will install docker and prepare the local environment.
**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
### Logout and back in to apply docker group changes
**That's it!** Your homelab is ready.
**Access Dockge at `https://dockge.yourdomain.duckdns.org`**
### Run the script without sudo and select Option 2: Deploy Core Server
* It will prompt for required env variables and create/update ~/EZ-Homelab/.env
## Multi-Server Setup
**Note:** Certificate generation may take 2-5 minutes. All services will use the wildcard certificate automatically.
To deploy services across multiple servers (e.g., Raspberry Pi, mini PCs):
**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
### 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
**That's it!** Your homelab is ready.
**Access Dockge at `https://dockge.yourdomain.duckdns.org`**
### Remote Server Setup (After Core)
1. **Clone repository on remote server**:
```bash
git clone https://github.com/kelinfoxy/EZ-Homelab.git
cd EZ-Homelab
```
----
2. **Copy `.env` from core server**:
```bash
# On core server
cd ~/EZ-Homelab
cat .env # Copy the contents
# On remote server
nano ~/EZ-Homelab/.env # Paste and save
```
# Deploy Additional Server
3. **Run setup with Infrastructure-Only option**:
```bash
./scripts/ez-homelab.sh
# Select option 3: "Deploy Infrastructure Only (Remote Server)"
```
>**You must have one and only one core server**
4. **When prompted, provide core server IP** for CA import
## Follow the steps above but select Option 3: Deploy Additional Server
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
* It will prompt for required env variables if missing from ~/EZ-Homelab/.env
* It includes variables for connecting to the core server
----
## What Gets Deployed Where
### 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) |
| Traefik | ✅ Yes | ❌ No |
| Sablier | ✅ Yes | ✅ Yes |
| Dockge | ✅ Yes | ✅ Yes |
| Services | ✅ Any | ✅ Any |
@@ -118,22 +70,8 @@ To deploy services across multiple servers (e.g., Raspberry Pi, mini PCs):
- **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:
```bash
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
## What the ez-homelab.sh Script Does
The `ez-homelab.sh` script is a comprehensive guided setup and deployment tool:
@@ -147,29 +85,24 @@ The `ez-homelab.sh` script is a comprehensive guided setup and deployment tool:
- ✅ 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
- ✅ Prompts for all required env variables
- ✅ Generates three secrets for Authelia (JWT, session, encryption)
- ✅ Generates argon2id password hash for admin password using Docker
- ✅ Validates Docker is available before operations
**Infrastructure Setup & Deployment:**
- ✅ Creates directory structure (`/opt/stacks/`)
- ✅ Sets up Docker networks (homelab, traefik, dockerproxy, media)
- ✅ Creates directory structure (`/opt/stacks/` & `opt/dockge`)
- ✅ Sets up Docker networks (homelab, traefik, dockerproxy)
- ✅ 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)
- ✅ Configures Traefik for multi-server support
- ✅ 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