docs: implement user feedback from tasks.txt
- README.md: Fixed .env step order, updated to 60+ services - getting-started.md: Service count updates, credential clarifications, moved Manual Setup to separate file - manual-setup.md: Created comprehensive manual setup guide - authelia-customization.md: Moved Authelia customization from services-overview - services-overview.md: Added clickable links to service docs, removed disabled section and Quick Deployment - quick-reference.md: Linked to scripts/README.md instead of duplicating content - Removed services-reference.md as requested
This commit is contained in:
256
docs/authelia-customization.md
Normal file
256
docs/authelia-customization.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Authelia Customization Guide
|
||||
|
||||
This guide covers how to customize Authelia for your specific needs.
|
||||
|
||||
## Available Customization Options
|
||||
|
||||
### 1. Branding and Appearance
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
|
||||
```yaml
|
||||
# Custom logo and branding
|
||||
theme: dark # Options: light, dark, grey, auto
|
||||
|
||||
# No built-in web UI for configuration
|
||||
# All settings managed via YAML files
|
||||
```
|
||||
|
||||
### 2. User Management
|
||||
Users are managed in `/opt/stacks/core/authelia/users_database.yml`:
|
||||
|
||||
```yaml
|
||||
users:
|
||||
username:
|
||||
displayname: "Display Name"
|
||||
password: "$argon2id$v=19$m=65536..." # Generated with authelia hash-password
|
||||
email: user@example.com
|
||||
groups:
|
||||
- admins
|
||||
- users
|
||||
```
|
||||
|
||||
Generate password hash:
|
||||
```bash
|
||||
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'yourpassword'
|
||||
```
|
||||
|
||||
### 3. Access Control Rules
|
||||
Customize who can access what in `configuration.yml`:
|
||||
|
||||
```yaml
|
||||
access_control:
|
||||
default_policy: deny
|
||||
|
||||
rules:
|
||||
# Public services (no auth)
|
||||
- domain:
|
||||
- "jellyfin.yourdomain.com"
|
||||
- "plex.yourdomain.com"
|
||||
policy: bypass
|
||||
|
||||
# Admin only services
|
||||
- domain:
|
||||
- "dockge.yourdomain.com"
|
||||
- "portainer.yourdomain.com"
|
||||
policy: two_factor
|
||||
subject:
|
||||
- "group:admins"
|
||||
|
||||
# All authenticated users
|
||||
- domain: "*.yourdomain.com"
|
||||
policy: one_factor
|
||||
```
|
||||
|
||||
### 4. Two-Factor Authentication (2FA)
|
||||
- TOTP (Time-based One-Time Password) via apps like Google Authenticator, Authy
|
||||
- Configure in `configuration.yml` under `totp:` section
|
||||
- Per-user enrollment via Authelia UI at `https://auth.${DOMAIN}`
|
||||
|
||||
### 5. Session Management
|
||||
Edit `configuration.yml`:
|
||||
|
||||
```yaml
|
||||
session:
|
||||
name: authelia_session
|
||||
expiration: 1h # How long before re-login required
|
||||
inactivity: 5m # Timeout after inactivity
|
||||
remember_me_duration: 1M # "Remember me" checkbox duration
|
||||
```
|
||||
|
||||
### 6. Notification Settings
|
||||
Email notifications for password resets, 2FA enrollment:
|
||||
|
||||
```yaml
|
||||
notifier:
|
||||
smtp:
|
||||
host: smtp.gmail.com
|
||||
port: 587
|
||||
username: your-email@gmail.com
|
||||
password: app-password
|
||||
sender: authelia@yourdomain.com
|
||||
```
|
||||
|
||||
## No Web UI for Configuration
|
||||
|
||||
⚠️ **Important**: Authelia does **not** have a configuration web UI. All configuration is done via YAML files:
|
||||
- `/opt/stacks/core/authelia/configuration.yml` - Main settings
|
||||
- `/opt/stacks/core/authelia/users_database.yml` - User accounts
|
||||
|
||||
This is **by design** and makes Authelia perfect for AI management and security-first approach:
|
||||
- AI can read and modify YAML files
|
||||
- Version control friendly
|
||||
- No UI clicks required
|
||||
- Infrastructure as code
|
||||
- Secure by default
|
||||
|
||||
**Web UI Available For:**
|
||||
- Login page: `https://auth.${DOMAIN}`
|
||||
- User profile: Change password, enroll 2FA
|
||||
- Device enrollment: Manage trusted devices
|
||||
|
||||
## Alternative with Web UI: Authentik
|
||||
|
||||
If you need a web UI for user management, Authentik is included in the infrastructure stack:
|
||||
- **Authentik**: Full-featured SSO with web UI for user/group management
|
||||
- Access at: `https://authentik.${DOMAIN}`
|
||||
- Includes PostgreSQL database and Redis cache
|
||||
- More complex but offers GUI-based configuration
|
||||
- Deploy only if you need web-based user management
|
||||
|
||||
**Other Alternatives:**
|
||||
- **Keycloak**: Enterprise-grade SSO with web UI
|
||||
- **Authelia + LDAP**: Use LDAP with web management (phpLDAPadmin, etc.)
|
||||
|
||||
## Quick Configuration with AI
|
||||
|
||||
Since all Authelia configuration is file-based, you can use the AI assistant to:
|
||||
- Add/remove users
|
||||
- Modify access rules
|
||||
- Change session settings
|
||||
- Update branding
|
||||
- Enable/disable features
|
||||
|
||||
Just ask: "Add a new user to Authelia" or "Change session timeout to 2 hours"
|
||||
|
||||
## Common Customizations
|
||||
|
||||
### Adding a New User
|
||||
|
||||
1. Generate password hash:
|
||||
```bash
|
||||
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'newuserpassword'
|
||||
```
|
||||
|
||||
2. Edit `/opt/stacks/core/authelia/users_database.yml`:
|
||||
```yaml
|
||||
users:
|
||||
admin:
|
||||
# existing admin user...
|
||||
|
||||
newuser:
|
||||
displayname: "New User"
|
||||
password: "$argon2id$v=19$m=65536..." # paste generated hash
|
||||
email: newuser@example.com
|
||||
groups:
|
||||
- users
|
||||
```
|
||||
|
||||
3. Restart Authelia:
|
||||
```bash
|
||||
cd /opt/stacks/core
|
||||
docker compose restart authelia
|
||||
```
|
||||
|
||||
### Bypass SSO for Specific Service
|
||||
|
||||
Edit the service's Traefik labels to remove the Authelia middleware:
|
||||
|
||||
```yaml
|
||||
# Before (SSO protected)
|
||||
labels:
|
||||
- "traefik.http.routers.service.middlewares=authelia@docker"
|
||||
|
||||
# After (bypass SSO)
|
||||
labels:
|
||||
# - "traefik.http.routers.service.middlewares=authelia@docker" # commented out
|
||||
```
|
||||
|
||||
### Change Session Timeout
|
||||
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
```yaml
|
||||
session:
|
||||
expiration: 12h # Changed from 1h to 12h
|
||||
inactivity: 30m # Changed from 5m to 30m
|
||||
```
|
||||
|
||||
Restart Authelia to apply changes.
|
||||
|
||||
### Enable SMTP Notifications
|
||||
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
```yaml
|
||||
notifier:
|
||||
smtp:
|
||||
host: smtp.gmail.com
|
||||
port: 587
|
||||
username: your-email@gmail.com
|
||||
password: your-app-password # Use app-specific password
|
||||
sender: authelia@yourdomain.com
|
||||
subject: "[Authelia] {title}"
|
||||
```
|
||||
|
||||
### Create Admin-Only Access Rule
|
||||
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
```yaml
|
||||
access_control:
|
||||
rules:
|
||||
# Admin-only services
|
||||
- domain:
|
||||
- "dockge.yourdomain.duckdns.org"
|
||||
- "traefik.yourdomain.duckdns.org"
|
||||
- "portainer.yourdomain.duckdns.org"
|
||||
policy: two_factor
|
||||
subject:
|
||||
- "group:admins"
|
||||
|
||||
# All other services - any authenticated user
|
||||
- domain: "*.yourdomain.duckdns.org"
|
||||
policy: one_factor
|
||||
```
|
||||
|
||||
Restart Authelia after changes.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### User Can't Log In
|
||||
|
||||
1. Check password hash format in users_database.yml
|
||||
2. Verify email address matches
|
||||
3. Check Authelia logs: `docker logs authelia`
|
||||
|
||||
### 2FA Not Working
|
||||
|
||||
1. Ensure time sync on server: `timedatectl`
|
||||
2. Check TOTP configuration in configuration.yml
|
||||
3. Regenerate QR code for user
|
||||
|
||||
### Sessions Expire Too Quickly
|
||||
|
||||
Increase session expiration in configuration.yml:
|
||||
```yaml
|
||||
session:
|
||||
expiration: 24h
|
||||
inactivity: 1h
|
||||
```
|
||||
|
||||
### Can't Access Specific Service
|
||||
|
||||
Check access control rules - service domain may be blocked by default_policy: deny
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Authelia Documentation](https://www.authelia.com/docs/)
|
||||
- [Authelia Service Docs](service-docs/authelia.md)
|
||||
- [Getting Started Guide](getting-started.md)
|
||||
@@ -1,6 +1,6 @@
|
||||
# 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 40+ services.
|
||||
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.
|
||||
|
||||
## Quick Setup (Recommended)
|
||||
|
||||
@@ -36,7 +36,7 @@ For most users, the automated setup script handles everything:
|
||||
- `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 are generated by the setup script.
|
||||
**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:**
|
||||
```bash
|
||||
@@ -56,8 +56,6 @@ For most users, the automated setup script handles everything:
|
||||
- Set up Docker networks (homelab, traefik, dockerproxy, media)
|
||||
- Detect NVIDIA GPU and offer driver installation
|
||||
|
||||
**Important:** The script generates a secure admin password hash that will be used during deployment. Credentials are displayed at the end and saved to a temporary file.
|
||||
|
||||
6. **Log out and back in** (or run `newgrp docker`)
|
||||
> Don't skip this step! Required for Docker group permissions.
|
||||
|
||||
@@ -76,8 +74,8 @@ For most users, the automated setup script handles everything:
|
||||
- Opens Dockge in your browser
|
||||
|
||||
**Login credentials:**
|
||||
- Username: `admin`
|
||||
- Password: Check `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt` or see script output
|
||||
- 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`
|
||||
|
||||
@@ -116,97 +114,30 @@ The `setup-homelab.sh` script is a comprehensive first-run configuration tool:
|
||||
|
||||
## Manual Setup (Alternative)
|
||||
|
||||
If you prefer manual control or the script fails, follow these steps:
|
||||
If you prefer manual control or the automated script fails, see the [Manual Setup Guide](manual-setup.md) for step-by-step instructions on installing Docker, configuring services, and deploying the homelab manually.
|
||||
|
||||
### Step 1: System Preparation
|
||||
```bash
|
||||
# Update system
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# Install required packages
|
||||
sudo apt install -y curl wget git ufw openssh-server
|
||||
|
||||
# Enable firewall
|
||||
sudo ufw allow ssh
|
||||
sudo ufw allow 80/tcp
|
||||
sudo ufw allow 443/tcp
|
||||
sudo ufw --force enable
|
||||
```
|
||||
|
||||
### Step 2: Install Docker
|
||||
```bash
|
||||
# Install Docker
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Add user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
sudo usermod -aG sudo $USER
|
||||
|
||||
# Log out and back in, or run: newgrp docker
|
||||
```
|
||||
|
||||
### Step 3: Clone Repository
|
||||
```bash
|
||||
cd ~
|
||||
git clone https://github.com/kelinfoxy/AI-Homelab.git
|
||||
cd AI-Homelab
|
||||
```
|
||||
|
||||
### Step 4: Configure Environment
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env # Edit all required variables
|
||||
```
|
||||
|
||||
### Step 5: Create Infrastructure
|
||||
```bash
|
||||
# Create directories
|
||||
sudo mkdir -p /opt/stacks /mnt/{media,database,downloads,backups}
|
||||
sudo chown -R $USER:$USER /opt/stacks /mnt
|
||||
|
||||
# Create networks
|
||||
docker network create traefik-network
|
||||
docker network create homelab-network
|
||||
docker network create media-network
|
||||
```
|
||||
|
||||
### Step 6: Deploy Services
|
||||
```bash
|
||||
# Deploy core infrastructure
|
||||
sudo mkdir -p /opt/stacks/core
|
||||
cp docker-compose/core.yml /opt/stacks/core/
|
||||
cp -r config-templates/traefik /opt/stacks/core/
|
||||
cp -r config-templates/authelia /opt/stacks/core/
|
||||
cp .env /opt/stacks/core/
|
||||
cd /opt/stacks/core
|
||||
docker compose up -d
|
||||
|
||||
# Deploy infrastructure stack
|
||||
sudo mkdir -p /opt/stacks/infrastructure
|
||||
cp ../docker-compose/infrastructure.yml /opt/stacks/infrastructure/
|
||||
cp ../.env /opt/stacks/infrastructure/
|
||||
cd /opt/stacks/infrastructure
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Post-Setup Configuration
|
||||
## 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`
|
||||
|
||||
### Configure Authelia
|
||||
### 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:
|
||||
- `dashboards.yml` - Homepage and Homarr
|
||||
- `media.yml` - Plex, Jellyfin, Sonarr, Radarr
|
||||
- `productivity.yml` - Nextcloud, Gitea, wikis
|
||||
- `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
|
||||
@@ -236,6 +167,7 @@ Use Dockge to deploy stacks like:
|
||||
- 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
|
||||
```bash
|
||||
|
||||
216
docs/manual-setup.md
Normal file
216
docs/manual-setup.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Manual Setup Guide
|
||||
|
||||
If you prefer manual control or the automated script fails, follow these steps for manual installation.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Fresh Debian/Ubuntu server or existing system
|
||||
- Root/sudo access
|
||||
- Internet connection
|
||||
|
||||
## Step 1: Update System
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
```
|
||||
|
||||
## Step 2: Install Docker
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
|
||||
|
||||
# Add Docker's official GPG key
|
||||
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
|
||||
|
||||
# Set up repository
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
|
||||
# Install Docker Engine
|
||||
sudo apt update
|
||||
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
|
||||
# Or use convenience script
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Add user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
sudo usermod -aG sudo $USER
|
||||
|
||||
# Log out and back in, or run: newgrp docker
|
||||
```
|
||||
|
||||
## Step 3: Clone Repository
|
||||
|
||||
```bash
|
||||
cd ~
|
||||
git clone https://github.com/kelinfoxy/AI-Homelab.git
|
||||
cd AI-Homelab
|
||||
```
|
||||
|
||||
## Step 4: Configure Environment
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env # Edit all required variables
|
||||
```
|
||||
|
||||
**Required variables:**
|
||||
- `DOMAIN` - Your DuckDNS domain
|
||||
- `DUCKDNS_TOKEN` - Your DuckDNS token
|
||||
- `ACME_EMAIL` - Your email for Let's Encrypt
|
||||
- `AUTHELIA_JWT_SECRET` - Generate with: `openssl rand -hex 64`
|
||||
- `AUTHELIA_SESSION_SECRET` - Generate with: `openssl rand -hex 64`
|
||||
- `AUTHELIA_STORAGE_ENCRYPTION_KEY` - Generate with: `openssl rand -hex 64`
|
||||
- `SURFSHARK_USERNAME` and `SURFSHARK_PASSWORD` - If using VPN
|
||||
|
||||
## Step 5: Create Infrastructure
|
||||
|
||||
```bash
|
||||
# Create directories
|
||||
sudo mkdir -p /opt/stacks /mnt/{media,database,downloads,backups}
|
||||
sudo chown -R $USER:$USER /opt/stacks /mnt
|
||||
|
||||
# Create networks
|
||||
docker network create traefik-network
|
||||
docker network create homelab-network
|
||||
docker network create dockerproxy-network
|
||||
docker network create media-network
|
||||
```
|
||||
|
||||
## Step 6: Generate Authelia Password Hash
|
||||
|
||||
```bash
|
||||
# Generate password hash (takes 30-60 seconds)
|
||||
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'YourSecurePassword'
|
||||
|
||||
# Copy the hash starting with $argon2id$...
|
||||
```
|
||||
|
||||
## Step 7: Configure Authelia
|
||||
|
||||
```bash
|
||||
# Copy Authelia config templates
|
||||
mkdir -p /opt/stacks/core/authelia
|
||||
cp config-templates/authelia/* /opt/stacks/core/authelia/
|
||||
|
||||
# Edit users_database.yml
|
||||
nano /opt/stacks/core/authelia/users_database.yml
|
||||
|
||||
# Replace password hash and email in the users section:
|
||||
users:
|
||||
admin:
|
||||
displayname: "Admin User"
|
||||
password: "$argon2id$v=19$m=65536,t=3,p=4$..." # Your hash here
|
||||
email: your.email@example.com
|
||||
groups:
|
||||
- admins
|
||||
- users
|
||||
```
|
||||
|
||||
## Step 8: Deploy Core Services
|
||||
|
||||
```bash
|
||||
# Deploy core infrastructure
|
||||
sudo mkdir -p /opt/stacks/core
|
||||
cp docker-compose/core.yml /opt/stacks/core/docker-compose.yml
|
||||
cp -r config-templates/traefik /opt/stacks/core/
|
||||
cp .env /opt/stacks/core/
|
||||
|
||||
# Update Traefik email
|
||||
sed -i "s/admin@example.com/$ACME_EMAIL/" /opt/stacks/core/traefik/traefik.yml
|
||||
|
||||
cd /opt/stacks/core
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Step 9: Deploy Infrastructure Stack
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/stacks/infrastructure
|
||||
cp docker-compose/infrastructure.yml /opt/stacks/infrastructure/docker-compose.yml
|
||||
cp .env /opt/stacks/infrastructure/
|
||||
cd /opt/stacks/infrastructure
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Step 10: Deploy Dashboards
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/stacks/dashboards
|
||||
cp docker-compose/dashboards.yml /opt/stacks/dashboards/docker-compose.yml
|
||||
cp -r config-templates/homepage /opt/stacks/dashboards/
|
||||
cp .env /opt/stacks/dashboards/
|
||||
|
||||
# Replace Homepage domain variables
|
||||
find /opt/stacks/dashboards/homepage -type f \( -name "*.yaml" -o -name "*.yml" \) -exec sed -i "s/{{HOMEPAGE_VAR_DOMAIN}}/$DOMAIN/g" {} \;
|
||||
|
||||
cd /opt/stacks/dashboards
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Step 11: Verify Deployment
|
||||
|
||||
```bash
|
||||
# Check running containers
|
||||
docker ps
|
||||
|
||||
# Check logs if any service fails
|
||||
docker logs container-name
|
||||
|
||||
# Access services
|
||||
echo "Dockge: https://dockge.$DOMAIN"
|
||||
echo "Authelia: https://auth.$DOMAIN"
|
||||
echo "Traefik: https://traefik.$DOMAIN"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Permission issues:**
|
||||
```bash
|
||||
# Ensure proper ownership
|
||||
sudo chown -R $USER:$USER /opt/stacks
|
||||
|
||||
# Check group membership
|
||||
groups $USER
|
||||
```
|
||||
|
||||
**Container won't start:**
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs container-name
|
||||
|
||||
# Check compose file syntax
|
||||
docker compose config
|
||||
```
|
||||
|
||||
**Network conflicts:**
|
||||
```bash
|
||||
# List existing networks
|
||||
docker network ls
|
||||
|
||||
# Remove and recreate if needed
|
||||
docker network rm network-name
|
||||
docker network create network-name
|
||||
```
|
||||
|
||||
## When to Use Manual Setup
|
||||
|
||||
- Automated script fails on your system
|
||||
- You want full control over each step
|
||||
- You're using a non-Debian/Ubuntu distribution
|
||||
- You need custom configurations
|
||||
- You're troubleshooting deployment issues
|
||||
|
||||
## Switching to Automated
|
||||
|
||||
If manual setup works, you can switch to the automated scripts for future updates:
|
||||
|
||||
```bash
|
||||
# Just run the deploy script
|
||||
cd ~/AI-Homelab
|
||||
./scripts/deploy-homelab.sh
|
||||
```
|
||||
|
||||
The deploy script is idempotent - it won't break existing configurations.
|
||||
@@ -23,58 +23,12 @@ Your homelab uses separate stacks for organization:
|
||||
|
||||
## Deployment Scripts
|
||||
|
||||
### setup-homelab.sh
|
||||
For detailed information about the deployment scripts, their features, and usage, see [scripts/README.md](../scripts/README.md).
|
||||
|
||||
First-run system preparation and Authelia configuration:
|
||||
|
||||
```bash
|
||||
sudo ./scripts/setup-homelab.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Pre-flight checks (internet, disk space 50GB+)
|
||||
- Installs Docker Engine + Compose V2
|
||||
- Configures user groups and firewall
|
||||
- Generates Authelia secrets automatically
|
||||
- Creates admin user with secure password hash
|
||||
- Sets up Docker networks and directory structure
|
||||
- Detects NVIDIA GPU and offers driver installation
|
||||
|
||||
**Safe to re-run** - skips completed steps
|
||||
|
||||
### deploy-homelab.sh
|
||||
|
||||
Deploys all core services and prepares additional stacks:
|
||||
|
||||
```bash
|
||||
./scripts/deploy-homelab.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Validates Docker installation
|
||||
- Deploys core stack (4 containers)
|
||||
- Deploys infrastructure stack (6 containers)
|
||||
- Deploys dashboards with configured URLs (2 containers)
|
||||
- Copies 7 additional stacks to Dockge (not started)
|
||||
- Optional: Pre-pull images for additional stacks
|
||||
- Opens Dockge in browser
|
||||
|
||||
### reset-test-environment.sh
|
||||
|
||||
**Testing/development only** - safely removes all deployed services:
|
||||
|
||||
```bash
|
||||
sudo ./scripts/reset-test-environment.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Gracefully stops all Docker Compose stacks
|
||||
- Removes Docker volumes (after 3s wait)
|
||||
- Cleans stack directories and temp files
|
||||
- Removes Docker networks
|
||||
- Prunes unused Docker resources
|
||||
|
||||
**Warning:** This is destructive! Only use for testing or complete reset.
|
||||
**Quick summary:**
|
||||
- `setup-homelab.sh` - First-run system setup and Authelia configuration
|
||||
- `deploy-homelab.sh` - Deploy all core services and prepare additional stacks
|
||||
- `reset-test-environment.sh` - Testing/development only - removes all deployed services
|
||||
|
||||
## Common Commands
|
||||
|
||||
|
||||
@@ -7,18 +7,16 @@ This document provides a comprehensive overview of all 60+ pre-configured servic
|
||||
| Stacks (10) | Services (70 + 6db) | SSO | Storage | Access URLs |
|
||||
|-------|----------|-----|---------|-------------|
|
||||
| **📦 core.yaml (4)** | **Deploy First** | | | |
|
||||
| ├─ DuckDNS | Dynamic DNS updater | - | /opt/stacks/core/duckdns | No UI |
|
||||
| ├─ Traefik | Reverse proxy + SSL | ✓ | /opt/stacks/core/traefik | traefik.${DOMAIN} |
|
||||
| ├─ Authelia | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} |
|
||||
| └─ Gluetun | VPN (Surfshark) | - | /opt/stacks/core/gluetun | No UI |
|
||||
| ├─ [DuckDNS](service-docs/duckdns.md) | Dynamic DNS updater | - | /opt/stacks/core/duckdns | No UI |
|
||||
| ├─ [Traefik](service-docs/traefik.md) | Reverse proxy + SSL | ✓ | /opt/stacks/core/traefik | traefik.${DOMAIN} |
|
||||
| ├─ [Authelia](service-docs/authelia.md) | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} |
|
||||
| └─ [Gluetun](service-docs/gluetun.md) | VPN (Surfshark) | - | /opt/stacks/core/gluetun | No UI |
|
||||
| **🔧 infrastructure.yaml (6+5)** | **Deployed: 6** | | | |
|
||||
| ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/infrastructure | dockge.${DOMAIN} |
|
||||
| ├─ Pi-hole | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} |
|
||||
| ├─ Dozzle | Docker log viewer | ✓ | /opt/stacks/infrastructure | dozzle.${DOMAIN} |
|
||||
| ├─ Glances | System monitoring | ✓ | /opt/stacks/infrastructure | glances.${DOMAIN} |
|
||||
| └─ Docker Proxy | Secure socket access | - | /opt/stacks/infrastructure | No UI |
|
||||
| **⚠️ Disabled:** | | | | |
|
||||
| ├─ Watchtower | Auto updates (disabled) | - | Docker API issue | No UI |
|
||||
| ├─ [Dockge](service-docs/dockge.md) | Stack manager (PRIMARY) | ✓ | /opt/stacks/infrastructure | dockge.${DOMAIN} |
|
||||
| ├─ [Pi-hole](service-docs/pihole.md) | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} |
|
||||
| ├─ [Dozzle](service-docs/dozzle.md) | Docker log viewer | ✓ | /opt/stacks/infrastructure | dozzle.${DOMAIN} |
|
||||
| ├─ [Glances](service-docs/glances.md) | System monitoring | ✓ | /opt/stacks/infrastructure | glances.${DOMAIN} |
|
||||
| └─ [Docker Proxy](service-docs/docker-proxy.md) | Secure socket access | - | /opt/stacks/infrastructure | No UI |
|
||||
| **📦 alternatives.yaml (5)** | **Not deployed** | | | |
|
||||
| ├─ Portainer | Container management | ✓ | /opt/stacks/alternatives | portainer.${DOMAIN} |
|
||||
| ├─ Authentik Server | SSO with web UI | ✓ | /opt/stacks/alternatives | authentik.${DOMAIN} |
|
||||
@@ -95,42 +93,6 @@ This document provides a comprehensive overview of all 60+ pre-configured servic
|
||||
|
||||
**Legend:** ✓ = Protected by SSO | ✗ = Bypasses SSO | - = No web UI
|
||||
|
||||
## Quick Deployment Order
|
||||
|
||||
1. **Create Networks** (one-time setup)
|
||||
```bash
|
||||
docker network create traefik-network
|
||||
docker network create homelab-network
|
||||
docker network create dockerproxy-network
|
||||
```
|
||||
|
||||
2. **Deploy Core Stack** (required first)
|
||||
```bash
|
||||
cd /opt/stacks/core/
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
3. **Deploy Infrastructure**
|
||||
```bash
|
||||
cd /opt/stacks/infrastructure/
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
4. **Deploy Dashboards**
|
||||
```bash
|
||||
cd /opt/stacks/dashboards/
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
5. **Deploy Additional Stacks** (as needed)
|
||||
- Media: `/opt/stacks/media/`
|
||||
- Extended Media: `/opt/stacks/media-extended/`
|
||||
- Home Automation: `/opt/stacks/homeassistant/`
|
||||
- Productivity: `/opt/stacks/productivity/`
|
||||
- Utilities: `/opt/stacks/utilities/`
|
||||
- Monitoring: `/opt/stacks/monitoring/`
|
||||
- Development: `/opt/stacks/development/`
|
||||
|
||||
## Toggling SSO (Authelia) On/Off
|
||||
|
||||
You can easily enable or disable SSO protection for any service by modifying its Traefik labels in the docker-compose.yml file.
|
||||
@@ -192,137 +154,6 @@ docker compose -f /opt/stacks/stack-name/docker-compose.yml down
|
||||
- **Gradual Exposure**: Comment out SSO only when ready to expose a service
|
||||
- **Quick Toggle**: AI assistant can modify these labels automatically when you ask
|
||||
|
||||
## Authelia Customization
|
||||
|
||||
### Available Customization Options
|
||||
|
||||
**1. Branding and Appearance**
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
|
||||
```yaml
|
||||
# Custom logo and branding
|
||||
theme: dark # Options: light, dark, grey, auto
|
||||
|
||||
# No built-in web UI for configuration
|
||||
# All settings managed via YAML files
|
||||
```
|
||||
|
||||
**2. User Management**
|
||||
Users are managed in `/opt/stacks/core/authelia/users_database.yml`:
|
||||
|
||||
```yaml
|
||||
users:
|
||||
username:
|
||||
displayname: "Display Name"
|
||||
password: "$argon2id$v=19$m=65536..." # Generated with authelia hash-password
|
||||
email: user@example.com
|
||||
groups:
|
||||
- admins
|
||||
- users
|
||||
```
|
||||
|
||||
Generate password hash:
|
||||
```bash
|
||||
docker run --rm authelia/authelia:4.37 authelia hash-password 'yourpassword'
|
||||
```
|
||||
|
||||
**3. Access Control Rules**
|
||||
Customize who can access what in `configuration.yml`:
|
||||
|
||||
```yaml
|
||||
access_control:
|
||||
default_policy: deny
|
||||
|
||||
rules:
|
||||
# Public services (no auth)
|
||||
- domain:
|
||||
- "jellyfin.yourdomain.com"
|
||||
- "plex.yourdomain.com"
|
||||
policy: bypass
|
||||
|
||||
# Admin only services
|
||||
- domain:
|
||||
- "dockge.yourdomain.com"
|
||||
- "portainer.yourdomain.com"
|
||||
policy: two_factor
|
||||
subject:
|
||||
- "group:admins"
|
||||
|
||||
# All authenticated users
|
||||
- domain: "*.yourdomain.com"
|
||||
policy: one_factor
|
||||
```
|
||||
|
||||
**4. Two-Factor Authentication (2FA)**
|
||||
- TOTP (Time-based One-Time Password) via apps like Google Authenticator, Authy
|
||||
- Configure in `configuration.yml` under `totp:` section
|
||||
- Per-user enrollment via Authelia UI at `https://auth.${DOMAIN}`
|
||||
|
||||
**5. Session Management**
|
||||
Edit `configuration.yml`:
|
||||
|
||||
```yaml
|
||||
session:
|
||||
name: authelia_session
|
||||
expiration: 1h # How long before re-login required
|
||||
inactivity: 5m # Timeout after inactivity
|
||||
remember_me_duration: 1M # "Remember me" checkbox duration
|
||||
```
|
||||
|
||||
**6. Notification Settings**
|
||||
Email notifications for password resets, 2FA enrollment:
|
||||
|
||||
```yaml
|
||||
notifier:
|
||||
smtp:
|
||||
host: smtp.gmail.com
|
||||
port: 587
|
||||
username: your-email@gmail.com
|
||||
password: app-password
|
||||
sender: authelia@yourdomain.com
|
||||
```
|
||||
|
||||
### No Web UI for Configuration
|
||||
|
||||
⚠️ **Important**: Authelia does **not** have a configuration web UI. All configuration is done via YAML files:
|
||||
- `/opt/stacks/core/authelia/configuration.yml` - Main settings
|
||||
- `/opt/stacks/core/authelia/users_database.yml` - User accounts
|
||||
|
||||
This is **by design** and makes Authelia perfect for AI management and security-first approach:
|
||||
- AI can read and modify YAML files
|
||||
- Version control friendly
|
||||
- No UI clicks required
|
||||
- Infrastructure as code
|
||||
- Secure by default
|
||||
|
||||
**Web UI Available For:**
|
||||
- Login page: `https://auth.${DOMAIN}`
|
||||
- User profile: Change password, enroll 2FA
|
||||
- Device enrollment: Manage trusted devices
|
||||
|
||||
**Alternative with Web UI: Authentik**
|
||||
If you need a web UI for user management, Authentik is included in the infrastructure stack:
|
||||
- **Authentik**: Full-featured SSO with web UI for user/group management
|
||||
- Access at: `https://authentik.${DOMAIN}`
|
||||
- Includes PostgreSQL database and Redis cache
|
||||
- More complex but offers GUI-based configuration
|
||||
- Deploy only if you need web-based user management
|
||||
|
||||
**Other Alternatives:**
|
||||
- **Keycloak**: Enterprise-grade SSO with web UI
|
||||
- **Authelia + LDAP**: Use LDAP with web management (phpLDAPadmin, etc.)
|
||||
|
||||
### Quick Configuration with AI
|
||||
|
||||
Since all Authelia configuration is file-based, you can use the AI assistant to:
|
||||
- Add/remove users
|
||||
- Modify access rules
|
||||
- Change session settings
|
||||
- Update branding
|
||||
- Enable/disable features
|
||||
|
||||
Just ask: "Add a new user to Authelia" or "Change session timeout to 2 hours"
|
||||
|
||||
## Storage Recommendations
|
||||
|
||||
| Data Type | Recommended Location | Reason |
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
# Services Reference
|
||||
|
||||
AI instructions:
|
||||
the contents of this file was moved to services-overview.yaml
|
||||
Reference in New Issue
Block a user