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

README.md

@@ -4,7 +4,7 @@ Leverage Github Copilot in VS Code as a complete homelab management interface.
 
 ## Overview
 
-This repository provides a comprehensive, production-ready homelab infrastructure using Docker Compose with Dockge, featuring 40+ pre-configured services. Integrated AI assistance through GitHub Copilot helps you create, modify, and manage Docker services while maintaining consistency across your entire server stack.
+This repository provides a comprehensive, production-ready homelab infrastructure using Docker Compose with Dockge, featuring 60+ pre-configured services. Integrated AI assistance through GitHub Copilot helps you create, modify, and manage Docker services while maintaining consistency across your entire server stack.
 
 The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia for Single Sign-On, Gluetun for VPN routing, and DuckDNS for dynamic DNS - all managed through file-based configurations that the AI can manage.
 
@@ -23,7 +23,7 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
 - **AI-Powered Management**: GitHub Copilot integration with specialized instructions for Docker service management
 - **Automated Setup & Deployment**: Two-script installation process with intelligent error handling
 - **Dockge Structure**: All stacks organized in `/opt/stacks/` for easy management via Dockge web UI
-- **40+ Pre-configured Services**: Production-ready compose files across infrastructure, media, home automation, productivity, and monitoring
+- **60+ Pre-configured Services**: Production-ready compose files across infrastructure, media, home automation, productivity, and monitoring
 - **Traefik Reverse Proxy**: Automatic HTTPS with Let's Encrypt via file-based configuration (no web UI needed)
 - **Authelia SSO**: Single Sign-On protection for all admin interfaces with automated password generation
 - **Gluetun VPN**: Surfshark WireGuard integration for secure downloads
@@ -63,7 +63,26 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
    cd AI-Homelab
    ```
 
-2. **Run first-run setup script:**
+2. **Create and configure environment file:**
+   ```bash
+   cp .env.example .env
+   nano .env  # Edit with your domain, API keys, and passwords
+   ```
+   > Alternatively you can ssh in from VS Code using the Remote-SSH plugin and edit in a nice editor
+
+   **IMPORTANT:** Keep your `.env` file in the repository folder (`~/AI-Homelab/.env`). The deploy script will automatically copy it where needed.
+
+   **Required variables:**
+   - `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 features
+   
+   **Note:** Authelia secrets (`AUTHELIA_JWT_SECRET`, `AUTHELIA_SESSION_SECRET`, `AUTHELIA_STORAGE_ENCRYPTION_KEY`) are automatically generated by the setup script, leave default values for now.
+   
+   > See [Getting Started](docs/getting-started.md) for detailed instructions
+
+3. **Run first-run setup script:**
    
    This automated script handles system preparation and Authelia configuration. Safe to run on partially configured systems - it skips completed steps.
    
@@ -81,25 +100,6 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
    
    **Important:** Log out and back in (or run `newgrp docker`) after setup completes.
 
-3. **Create and configure environment file:**
-   ```bash
-   cp .env.example .env
-   nano .env  # Edit with your domain, API keys, and passwords
-   ```
-   > Alternatively you can ssh in from VS Code using the Remote-SSH plugin and edit in a nice editor
-
-   **IMPORTANT:** Keep your `.env` file in the repository folder (`~/AI-Homelab/.env`). The deploy script will automatically copy it where needed.
-
-   **Required variables:**
-   - `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 features
-   
-   **Note:** Authelia secrets (`AUTHELIA_JWT_SECRET`, `AUTHELIA_SESSION_SECRET`, `AUTHELIA_STORAGE_ENCRYPTION_KEY`) are automatically generated by the setup script. You can pre-generate them if desired using `openssl rand -hex 64`.
-   
-   > See [Getting Started](docs/getting-started.md) for detailed instructions
-
 4. **Run deployment script:**
    
    This automated script will:
@@ -116,8 +116,6 @@ The infrastructure uses Traefik for reverse proxy with automatic SSL, Authelia f
    ./scripts/deploy-homelab.sh
    ```
    
-   **Login credentials:** Check script output or `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt`
-   
    **Note:** The script will prompt to optionally pre-pull images for additional stacks. This takes time but speeds up future deployments. Default is no.
 
 5. **Deploy additional stacks through Dockge:**

docs/authelia-customization.md

@@ -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)

docs/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`
+   - Username: `admin` (default username - or the custom username you specified during setup)
-   - Password: Check `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt` or see script output
+   - 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
+## Post-Setup Next Steps
-```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
 
 ### 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
+- `arr-apps.yml` - Media management (Radarr, Sonarr, Prowlarr, etc.)
-- `media.yml` - Plex, Jellyfin, Sonarr, Radarr
+- `media-servers.yml` - Plex and Jellyfin
-- `productivity.yml` - Nextcloud, Gitea, wikis
+- `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

docs/manual-setup.md

@@ -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.

docs/quick-reference.md

@@ -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:
+**Quick summary:**
-
+- `setup-homelab.sh` - First-run system setup and Authelia configuration
-```bash
+- `deploy-homelab.sh` - Deploy all core services and prepare additional stacks
-sudo ./scripts/setup-homelab.sh
+- `reset-test-environment.sh` - Testing/development only - removes all deployed services
-```
-
-**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.
 
 ## Common Commands
 

docs/services-overview.md

@@ -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 |
+| ├─ [DuckDNS](service-docs/duckdns.md) | Dynamic DNS updater | - | /opt/stacks/core/duckdns | No UI |
-| ├─ Traefik | Reverse proxy + SSL | ✓ | /opt/stacks/core/traefik | traefik.${DOMAIN} |
+| ├─ [Traefik](service-docs/traefik.md) | Reverse proxy + SSL | ✓ | /opt/stacks/core/traefik | traefik.${DOMAIN} |
-| ├─ Authelia | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} |
+| ├─ [Authelia](service-docs/authelia.md) | SSO authentication | - | /opt/stacks/core/authelia | auth.${DOMAIN} |
-| └─ Gluetun | VPN (Surfshark) | - | /opt/stacks/core/gluetun | No UI |
+| └─ [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} |
+| ├─ [Dockge](service-docs/dockge.md) | Stack manager (PRIMARY) | ✓ | /opt/stacks/infrastructure | dockge.${DOMAIN} |
-| ├─ Pi-hole | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} |
+| ├─ [Pi-hole](service-docs/pihole.md) | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} |
-| ├─ Dozzle | Docker log viewer | ✓ | /opt/stacks/infrastructure | dozzle.${DOMAIN} |
+| ├─ [Dozzle](service-docs/dozzle.md) | Docker log viewer | ✓ | /opt/stacks/infrastructure | dozzle.${DOMAIN} |
-| ├─ Glances | System monitoring | ✓ | /opt/stacks/infrastructure | glances.${DOMAIN} |
+| ├─ [Glances](service-docs/glances.md) | System monitoring | ✓ | /opt/stacks/infrastructure | glances.${DOMAIN} |
-| └─ Docker Proxy | Secure socket access | - | /opt/stacks/infrastructure | No UI |
+| └─ [Docker Proxy](service-docs/docker-proxy.md) | Secure socket access | - | /opt/stacks/infrastructure | No UI |
-| **⚠️ Disabled:** | | | | |
-| ├─ Watchtower | Auto updates (disabled) | - | Docker API issue | 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 |

docs/services-reference.md

@@ -1,4 +0,0 @@
-# Services Reference
-
-AI instructions:
-    the contents of this file was moved to services-overview.yaml

tasks.txt

@@ -0,0 +1,41 @@
+README.md
+    Quick setup steps are out of order. the .env file has to be created before running the script
+    also Run deployment script: remove old login credentials from file
+
+updage all references to 40+ services or similar to 60+
+
+getting-started.md
+    add ',leave default values for now' to 'Authelia secrets are generated by the setup script.'
+    remove '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.'
+    remove 'Generates Authelia admin password (saved to /opt/stacks/core/authelia/ADMIN_PASSWORD.txt)'
+    clarify 'Username: admin' is default, or the user you created 
+    replace 'Password: Check /opt/stacks/core/authelia/ADMIN_PASSWORD.txt or see script output' with 'Password: you set in the setup'
+    Manual Setup section should be a seperate .md file and linked to
+
+    Refine and rename Post-Setup Configuration to Post-Setup Next Steps. for example Configure Authelia section the user password is set by the setup script.
+
+    Deploy Additional Stacks
+        dashboards.yml - Homepage and Homarr  -  dashboards are already deployed by the script
+
+    Service Issues section include a blockquote to recomend using Dozzle to view logs 
+
+    replace 'Set up Authelia authentication' with 'Set up 2FA with Authelia'
+
+services-references.md
+    Remove this file.
+
+services-overview.md
+    In the stacks column all the Container names should be a clickable link to the apropriate service-docs file
+    remove '⚠️ Disabled:'
+    remove the Quick Deployments Order section
+    Authemlia Customization section doesn't belong in this file, it should be elsewhere
+
+quick-reference.md
+    Deployment Scripts section should like to the readme.md in the scripts folder, instead of restating it.
+
+For later:
+    reorganize stacks, get *arr apps in one stack, downloaders in another, and transcoders in another. Make Jellyfin the default and put plex in alternatives.
+
+    README.md VS Code expanded instructions. launch the code server, and configure it.
+
+    Refine backup strategy, backrest as the default