234 lines
6.2 KiB
Plaintext
234 lines
6.2 KiB
Plaintext
====== Automated Setup ======
|
|
|
|
The AI-Homelab uses two automated scripts for deployment. This is the recommended approach for most users.
|
|
|
|
===== Quick Setup Commands =====
|
|
|
|
```bash
|
|
# 1. Clone the repository
|
|
git clone https://github.com/kelinfoxy/AI-Homelab.git
|
|
cd AI-Homelab
|
|
|
|
# 2. Configure environment
|
|
cp .env.example .env
|
|
nano .env # Edit with your domain and tokens
|
|
|
|
# 3. Run setup script
|
|
sudo ./scripts/setup-homelab.sh
|
|
|
|
# 4. Run deployment script
|
|
sudo ./scripts/deploy-homelab.sh
|
|
```
|
|
|
|
That's it! Your homelab will be ready in 10-15 minutes.
|
|
|
|
===== Detailed Setup Process =====
|
|
|
|
==== Step 1: Clone Repository ====
|
|
|
|
```bash
|
|
# Clone to your home directory
|
|
cd ~
|
|
git clone https://github.com/kelinfoxy/AI-Homelab.git
|
|
cd AI-Homelab
|
|
```
|
|
|
|
**What this provides:**
|
|
* Complete homelab configuration
|
|
* Docker compose files for all services
|
|
* Automated deployment scripts
|
|
* Configuration templates
|
|
* Documentation and guides
|
|
|
|
==== Step 2: Configure Environment ====
|
|
|
|
```bash
|
|
# Copy example configuration
|
|
cp .env.example .env
|
|
|
|
# Edit with your settings
|
|
nano .env
|
|
```
|
|
|
|
**Required variables:**
|
|
```
|
|
DOMAIN=yourdomain.duckdns.org
|
|
DUCKDNS_TOKEN=your-duckdns-token
|
|
ACME_EMAIL=your-email@example.com
|
|
```
|
|
|
|
**Optional variables:**
|
|
```
|
|
SURFSHARK_USERNAME=your-vpn-username
|
|
SURFSHARK_PASSWORD=your-vpn-password
|
|
TZ=America/New_York
|
|
PUID=1000
|
|
PGID=1000
|
|
```
|
|
|
|
==== Step 3: Run Setup Script ====
|
|
|
|
```bash
|
|
# Execute with sudo privileges
|
|
sudo ./scripts/setup-homelab.sh
|
|
```
|
|
|
|
**What the setup script does:**
|
|
|
|
**System Preparation:**
|
|
* Updates system packages
|
|
* Installs required dependencies (git, curl, etc.)
|
|
* Installs Docker Engine + Compose V2
|
|
* Configures user permissions
|
|
* Sets up UFW firewall
|
|
* Enables SSH server
|
|
|
|
**Authelia Configuration:**
|
|
* Generates cryptographic secrets (JWT, session, encryption keys)
|
|
* Prompts for admin username (default: admin)
|
|
* Prompts for secure password with confirmation
|
|
* Generates argon2id password hash
|
|
* Creates user database
|
|
|
|
**Infrastructure Setup:**
|
|
* Creates `/opt/stacks/` directory structure
|
|
* Sets up Docker networks (traefik-network, homelab-network, etc.)
|
|
* Detects NVIDIA GPU and offers driver installation
|
|
|
|
**Security Features:**
|
|
* Idempotent (safe to re-run)
|
|
* Comprehensive error handling
|
|
* Timeout protection for operations
|
|
* Clear troubleshooting messages
|
|
|
|
==== Step 4: Run Deployment Script ====
|
|
|
|
```bash
|
|
# Deploy all services
|
|
sudo ./scripts/deploy-homelab.sh
|
|
```
|
|
|
|
**What the deployment script does:**
|
|
|
|
**Prerequisites Check:**
|
|
* Validates environment configuration
|
|
* Verifies Docker installation
|
|
* Checks network connectivity
|
|
|
|
**Core Stack Deployment:**
|
|
* Deploys DuckDNS, Traefik, Authelia, Gluetun
|
|
* Obtains wildcard SSL certificate (*.yourdomain.duckdns.org)
|
|
* Configures reverse proxy routing
|
|
|
|
**Infrastructure Deployment:**
|
|
* Deploys Dockge, Pi-hole, monitoring tools
|
|
* Sets up dashboards (Homepage, Homarr)
|
|
* Configures service discovery
|
|
|
|
**Health Checks:**
|
|
* Waits for services to become healthy
|
|
* Validates SSL certificate generation
|
|
* Opens Dockge in browser
|
|
|
|
===== Post-Setup Configuration =====
|
|
|
|
==== Access Your Services ====
|
|
|
|
After deployment, access services at:
|
|
|
|
| Service | URL | Status |
|
|
|---------|-----|--------|
|
|
| **Dockge** | `https://dockge.yourdomain.duckdns.org` | ✅ Primary management |
|
|
| **Homepage** | `https://home.yourdomain.duckdns.org` | ✅ Service dashboard |
|
|
| **Authelia** | `https://auth.yourdomain.duckdns.org` | ✅ SSO login |
|
|
| **Traefik** | `https://traefik.yourdomain.duckdns.org` | ✅ Proxy dashboard |
|
|
|
|
**Default Credentials:**
|
|
* Username: `admin` (or your custom username)
|
|
* Password: The secure password you created
|
|
|
|
==== Configure Two-Factor Authentication ====
|
|
|
|
1. Visit `https://auth.yourdomain.duckdns.org`
|
|
2. Log in with your admin credentials
|
|
3. Go to Settings → One-Time Password
|
|
4. Scan QR code with authenticator app
|
|
5. Enter verification code to enable 2FA
|
|
|
|
==== Customize Homepage Dashboard ====
|
|
|
|
1. Visit `https://home.yourdomain.duckdns.org`
|
|
2. Click the settings icon (gear)
|
|
3. Configure services and widgets
|
|
4. Add API keys for enhanced widgets
|
|
|
|
===== Troubleshooting Setup =====
|
|
|
|
==== Common Issues ====
|
|
|
|
**"Permission denied" when running scripts:**
|
|
```bash
|
|
# Ensure you're using sudo
|
|
sudo ./scripts/setup-homelab.sh
|
|
|
|
# Check if scripts are executable
|
|
ls -la scripts/
|
|
chmod +x scripts/*.sh
|
|
```
|
|
|
|
**Docker installation fails:**
|
|
```bash
|
|
# Remove conflicting packages
|
|
sudo apt remove docker docker-engine docker.io containerd runc
|
|
|
|
# Re-run setup script
|
|
sudo ./scripts/setup-homelab.sh
|
|
```
|
|
|
|
**SSL certificate generation fails:**
|
|
* Check DuckDNS token is correct in `.env`
|
|
* Verify ports 80/443 are forwarded
|
|
* Wait 2-5 minutes for DNS propagation
|
|
* Check Traefik logs: `docker logs traefik`
|
|
|
|
**Services not accessible:**
|
|
* Verify domain resolves: `nslookup yourdomain.duckdns.org`
|
|
* Check firewall: `sudo ufw status`
|
|
* View service logs: `docker compose -f /opt/stacks/core/docker-compose.yml logs`
|
|
|
|
==== NVIDIA GPU Setup ====
|
|
|
|
If you have an NVIDIA GPU and want hardware acceleration:
|
|
|
|
```bash
|
|
# During setup script, answer 'y' when prompted
|
|
# Or install manually after setup:
|
|
|
|
# Add NVIDIA package repository
|
|
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
|
|
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
|
|
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
|
|
|
|
# Install NVIDIA Docker
|
|
sudo apt-get update && sudo apt-get install -y nvidia-docker2
|
|
sudo systemctl restart docker
|
|
|
|
# Test GPU access
|
|
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
|
|
```
|
|
|
|
==== Manual Setup Alternative ====
|
|
|
|
If automated scripts fail, see [[getting_started:manual|Manual Setup Guide]] for step-by-step instructions.
|
|
|
|
===== Next Steps =====
|
|
|
|
1. **Explore Services**: Use Dockge to deploy additional services
|
|
2. **Configure Backups**: Set up Backrest for automated backups
|
|
3. **Add Monitoring**: Deploy Grafana/Prometheus for observability
|
|
4. **Customize**: Modify services to fit your needs
|
|
5. **Contribute**: Help improve the project
|
|
|
|
**Ready to deploy?** Run the setup script and enjoy your new homelab!
|
|
|
|
**Need help?** Check [[troubleshooting:deployment|Deployment Troubleshooting]] or ask in [[https://github.com/kelinfoxy/AI-Homelab/discussions|GitHub Discussions]]. |