Wiki v1.0
Added a wiki
This commit is contained in:
kelinfoxy
234
config-templates/dokuwiki/data/pages/getting_started/setup.txt
Normal file
234
config-templates/dokuwiki/data/pages/getting_started/setup.txt
Normal file
@@ -0,0 +1,234 @@
|
||||
====== 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]].
|
||||
Reference in New Issue
Block a user