From 3cdf8606ff40b97ffe2a4bc270c0f2ec254d813c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 12 Jan 2026 01:57:22 +0000
Subject: [PATCH] Implement core stack, add SSO to dashboards, and create
 compact services reference

- Create core.yml combining DuckDNS, Traefik, Authelia, and Gluetun into single stack
  - Simplifies initial deployment (deploy all core services with one command)
  - All core services in /opt/stacks/core/ directory
  - Reduces complexity for first-time setup

- Add Authelia SSO protection to Homepage and Homarr dashboards
  - Prevents exposing service list before authentication
  - Both dashboards now require sign-in to access

- Redesign services-reference.md with compact tree-view table
  - Reduced from ~460 lines to ~150 lines while keeping all info
  - Single comprehensive table with tree structure
  - Shows: Stack, Services, SSO status, Storage paths, Access URLs
  - Fits on 1-2 screen heights as requested

- Add comprehensive "Toggling SSO On/Off" section
  - Quick guide to enable/disable Authelia middleware
  - Use cases for development vs production
  - AI can automatically toggle SSO when asked

- Add "Authelia Customization" section with:
  - Branding and appearance options
  - User management via YAML files
  - Access control rules examples
  - 2FA/TOTP configuration
  - Session management settings
  - Email notification setup
  - Explanation of no web UI (by design, perfect for AI)
  - Alternatives with web UI (Authentik, Keycloak)

- Update .github/copilot-instructions.md
  - Add core stack explanation
  - Update file organization to show core stack structure
  - Add SSO toggling instructions

- Update docs/getting-started.md
  - Simplify Step 7 to deploy single core stack
  - Remove separate steps for DuckDNS, Traefik, Authelia
  - Add verification and troubleshooting for core deployment
  - Update subsequent steps to Step 8, 9, 10

Co-authored-by: kelinfoxy <67766943+kelinfoxy@users.noreply.github.com>
---
 .github/copilot-instructions.md |  96 +++-
 docker-compose/core.yml         | 137 ++++++
 docker-compose/dashboards.yml   |   4 +-
 docs/getting-started.md         | 162 ++++---
 docs/services-reference.md      | 771 +++++++++++++-------------------
 5 files changed, 627 insertions(+), 543 deletions(-)
 create mode 100644 docker-compose/core.yml

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 5712a42..c8c757f 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -242,29 +242,83 @@ environment:
 
 ```
 /opt/stacks/
-├── stack-name/
-│   ├── docker-compose.yml    # Stack definition
-│   ├── config/               # Service configurations
-│   ├── .env                  # Stack-specific secrets
-│   └── README.md            # Stack documentation
-├── traefik/
-│   ├── docker-compose.yml
-│   ├── traefik.yml          # Traefik static config
-│   ├── dynamic/             # Dynamic configuration
-│   │   └── routes.yml       # Route definitions
-│   ├── acme.json           # Let's Encrypt certificates
+├── core/                        # Core infrastructure (deploy FIRST)
+│   ├── docker-compose.yml       # DuckDNS, Traefik, Authelia, Gluetun
+│   ├── duckdns/                 # DuckDNS config
+│   ├── traefik/
+│   │   ├── traefik.yml          # Traefik static config
+│   │   ├── dynamic/             # Dynamic configuration
+│   │   │   └── routes.yml       # Route definitions
+│   │   └── acme.json           # Let's Encrypt certificates
+│   ├── authelia/
+│   │   ├── configuration.yml    # Authelia config
+│   │   └── users_database.yml   # User definitions
+│   ├── gluetun/                 # VPN config
+│   └── .env                     # Core secrets
+├── infrastructure/
+│   ├── docker-compose.yml       # Dockge, Portainer, Pi-hole, etc.
+│   ├── config/
 │   └── .env
-├── authelia/
-│   ├── docker-compose.yml
-│   ├── configuration.yml    # Authelia config
-│   ├── users_database.yml   # User definitions
+├── dashboards/
+│   ├── docker-compose.yml       # Homepage, Homarr
+│   ├── config/
 │   └── .env
-├── gluetun/
-│   ├── docker-compose.yml
-│   └── .env                # VPN credentials
-└── duckdns/
-    ├── docker-compose.yml
-    └── .env                # DuckDNS token
+├── media/
+│   ├── docker-compose.yml       # Plex, Jellyfin, Sonarr, Radarr, etc.
+│   ├── config/
+│   └── .env
+└── [other stacks...]
+```
+
+## Core Infrastructure Stack
+
+The `core` stack contains the four essential services that must be deployed **FIRST**:
+
+1. **DuckDNS** - Dynamic DNS updater for Let's Encrypt
+2. **Traefik** - Reverse proxy with automatic SSL certificates
+3. **Authelia** - SSO authentication for all services
+4. **Gluetun** - VPN client (Surfshark WireGuard) for secure downloads
+
+**Why combined in one stack?**
+- These services depend on each other
+- Simplifies initial deployment (one command)
+- Easier to manage core infrastructure together
+- Reduces network configuration complexity
+
+**Deployment:**
+```bash
+cd /opt/stacks/core/
+docker compose up -d
+```
+
+All other stacks depend on the core stack being deployed first.
+
+## Toggling SSO (Authelia) On/Off
+
+You can easily enable or disable SSO protection for any service by modifying its Traefik labels.
+
+### To Enable SSO
+Add the Authelia middleware label:
+```yaml
+labels:
+  - "traefik.http.routers.servicename.middlewares=authelia@docker"
+```
+
+### To Disable SSO
+Remove or comment out the middleware label:
+```yaml
+labels:
+  # - "traefik.http.routers.servicename.middlewares=authelia@docker"
+```
+
+**Common Use Cases:**
+- **Development**: Enable SSO to protect services during testing
+- **Production**: Disable SSO for services needing direct app/API access (Plex, Jellyfin)
+- **Quick Toggle**: AI can modify these labels when you ask to enable/disable SSO
+
+After changes, redeploy:
+```bash
+docker compose up -d
 ```
 
 ## VPN Integration with Gluetun
diff --git a/docker-compose/core.yml b/docker-compose/core.yml
new file mode 100644
index 0000000..c9956f1
--- /dev/null
+++ b/docker-compose/core.yml
@@ -0,0 +1,137 @@
+# Core Infrastructure Stack
+# Essential services required for the homelab to function
+# Deploy this stack FIRST before any other services
+# Place in /opt/stacks/core/docker-compose.yml
+
+services:
+  # DuckDNS - Dynamic DNS updater
+  # Updates your public IP automatically for Let's Encrypt SSL
+  duckdns:
+    image: lscr.io/linuxserver/duckdns:latest
+    container_name: duckdns
+    restart: unless-stopped
+    environment:
+      - PUID=${PUID:-1000}
+      - PGID=${PGID:-1000}
+      - TZ=${TZ}
+      - SUBDOMAINS=${DUCKDNS_SUBDOMAINS}  # Your subdomain(s), comma separated
+      - TOKEN=${DUCKDNS_TOKEN}            # Your DuckDNS token
+      - UPDATE_IP=ipv4                    # or ipv6, or both
+    volumes:
+      - /opt/stacks/core/duckdns:/config
+    labels:
+      - "homelab.category=infrastructure"
+      - "homelab.description=Dynamic DNS updater"
+
+  # Traefik - Reverse proxy with automatic SSL
+  # Routes all traffic and manages Let's Encrypt certificates
+  traefik:
+    image: traefik:v2.11
+    container_name: traefik
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    networks:
+      - traefik-network
+    ports:
+      - "80:80"      # HTTP
+      - "443:443"    # HTTPS
+      - "8080:8080"  # Dashboard (protected with Authelia)
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /opt/stacks/core/traefik/traefik.yml:/traefik.yml:ro
+      - /opt/stacks/core/traefik/dynamic:/dynamic:ro
+      - /opt/stacks/core/traefik/acme.json:/acme.json
+    environment:
+      - CF_DNS_API_TOKEN=${CF_DNS_API_TOKEN}  # If using Cloudflare DNS challenge
+      - DUCKDNS_TOKEN=${DUCKDNS_TOKEN}        # If using DuckDNS
+    labels:
+      - "traefik.enable=true"
+      # Dashboard
+      - "traefik.http.routers.traefik.rule=Host(`traefik.${DOMAIN}`)"
+      - "traefik.http.routers.traefik.entrypoints=websecure"
+      - "traefik.http.routers.traefik.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.traefik.middlewares=authelia@docker"
+      - "traefik.http.routers.traefik.service=api@internal"
+      # Global HTTP to HTTPS redirect
+      - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)"
+      - "traefik.http.routers.http-catchall.entrypoints=web"
+      - "traefik.http.routers.http-catchall.middlewares=redirect-to-https"
+      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
+    depends_on:
+      - duckdns
+
+  # Authelia - SSO authentication
+  # Protects all admin services with single sign-on
+  authelia:
+    image: authelia/authelia:4.37
+    container_name: authelia
+    restart: unless-stopped
+    networks:
+      - traefik-network
+    volumes:
+      - /opt/stacks/core/authelia/configuration.yml:/config/configuration.yml:ro
+      - /opt/stacks/core/authelia/users_database.yml:/config/users_database.yml
+      - authelia-data:/config
+    environment:
+      - TZ=${TZ}
+      - AUTHELIA_JWT_SECRET=${AUTHELIA_JWT_SECRET}
+      - AUTHELIA_SESSION_SECRET=${AUTHELIA_SESSION_SECRET}
+      - AUTHELIA_STORAGE_ENCRYPTION_KEY=${AUTHELIA_STORAGE_ENCRYPTION_KEY}
+      - AUTHELIA_NOTIFIER_SMTP_PASSWORD=${SMTP_PASSWORD}  # If using email notifications
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.authelia.rule=Host(`auth.${DOMAIN}`)"
+      - "traefik.http.routers.authelia.entrypoints=websecure"
+      - "traefik.http.routers.authelia.tls.certresolver=letsencrypt"
+      - "traefik.http.services.authelia.loadbalancer.server.port=9091"
+      # Authelia middleware for other services
+      - "traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.${DOMAIN}"
+      - "traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true"
+      - "traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email"
+    depends_on:
+      - traefik
+
+  # Gluetun - VPN client (Surfshark WireGuard)
+  # Routes download clients through VPN for security
+  gluetun:
+    image: qmcgaw/gluetun:latest
+    container_name: gluetun
+    restart: unless-stopped
+    cap_add:
+      - NET_ADMIN
+    devices:
+      - /dev/net/tun:/dev/net/tun
+    networks:
+      - homelab-network
+      - traefik-network
+    ports:
+      - "8888:8888/tcp"  # HTTP proxy
+      - "8388:8388/tcp"  # Shadowsocks
+      - "8388:8388/udp"  # Shadowsocks
+      - "8080:8080"      # qBittorrent web UI
+      - "6881:6881"      # qBittorrent
+      - "6881:6881/udp"  # qBittorrent
+    volumes:
+      - /opt/stacks/core/gluetun:/gluetun
+    environment:
+      - VPN_SERVICE_PROVIDER=surfshark
+      - VPN_TYPE=wireguard
+      - WIREGUARD_PRIVATE_KEY=${SURFSHARK_PRIVATE_KEY}
+      - WIREGUARD_ADDRESSES=${SURFSHARK_ADDRESSES}
+      - SERVER_COUNTRIES=${VPN_SERVER_COUNTRIES:-Netherlands}
+      - TZ=${TZ}
+    labels:
+      - "homelab.category=infrastructure"
+      - "homelab.description=VPN client for secure downloads"
+
+volumes:
+  authelia-data:
+    driver: local
+
+networks:
+  traefik-network:
+    external: true
+  homelab-network:
+    external: true
diff --git a/docker-compose/dashboards.yml b/docker-compose/dashboards.yml
index 2e83333..8ff4531 100644
--- a/docker-compose/dashboards.yml
+++ b/docker-compose/dashboards.yml
@@ -28,8 +28,8 @@ services:
       - "traefik.http.routers.homepage.rule=Host(`home.${DOMAIN}`)"
       - "traefik.http.routers.homepage.entrypoints=websecure"
       - "traefik.http.routers.homepage.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.homepage.middlewares=authelia@docker"
       - "traefik.http.services.homepage.loadbalancer.server.port=3000"
-      # No Authelia - make it the default landing page
 
   # Homarr - Modern dashboard
   # Access at: https://homarr.${DOMAIN}
@@ -54,8 +54,8 @@ services:
       - "traefik.http.routers.homarr.rule=Host(`homarr.${DOMAIN}`)"
       - "traefik.http.routers.homarr.entrypoints=websecure"
       - "traefik.http.routers.homarr.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.homarr.middlewares=authelia@docker"
       - "traefik.http.services.homarr.loadbalancer.server.port=7575"
-      # No Authelia - dashboard should be accessible
 
 networks:
   homelab-network:
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c62d29a..929c75f 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -134,91 +134,69 @@ docker network create dockerproxy-network
 docker network ls | grep -E "traefik|homelab|media|dockerproxy"
 ```
 
-## Step 7: Deploy Core Infrastructure (IN ORDER)
+## Step 7: Deploy Core Infrastructure Stack
 
-### 7.1 DuckDNS (Dynamic DNS)
+The **core** stack contains all essential services that must be deployed first: DuckDNS, Traefik, Authelia, and Gluetun.
 
 ```bash
-# Create stack directory
-mkdir -p /opt/stacks/duckdns
+# Create core stack directory
+mkdir -p /opt/stacks/core/{duckdns,traefik/dynamic,authelia,gluetun}
 
-# Copy compose file
-cp ~/AI-Homelab/docker-compose/duckdns.yml /opt/stacks/duckdns/docker-compose.yml
-
-# Copy .env
-cp ~/AI-Homelab/.env /opt/stacks/duckdns/.env
-
-# Deploy
-cd /opt/stacks/duckdns
-docker compose up -d
-
-# Verify it's working
-docker compose logs -f
-# Should see: "Your IP was updated to X.X.X.X"
-```
-
-### 7.2 Traefik (Reverse Proxy with SSL)
-
-```bash
-# Create stack directory with dynamic configs
-mkdir -p /opt/stacks/traefik/dynamic
-
-# Copy compose file
-cp ~/AI-Homelab/docker-compose/traefik.yml /opt/stacks/traefik/docker-compose.yml
+# Copy the core compose file
+cp ~/AI-Homelab/docker-compose/core.yml /opt/stacks/core/docker-compose.yml
 
 # Copy configuration templates
-cp ~/AI-Homelab/config-templates/traefik/traefik.yml /opt/stacks/traefik/
-cp ~/AI-Homelab/config-templates/traefik/dynamic/*.yml /opt/stacks/traefik/dynamic/
+cp ~/AI-Homelab/config-templates/traefik/traefik.yml /opt/stacks/core/traefik/
+cp ~/AI-Homelab/config-templates/traefik/dynamic/*.yml /opt/stacks/core/traefik/dynamic/
+cp ~/AI-Homelab/config-templates/authelia/*.yml /opt/stacks/core/authelia/
 
 # Create acme.json for SSL certificates
-touch /opt/stacks/traefik/acme.json
-chmod 600 /opt/stacks/traefik/acme.json
+touch /opt/stacks/core/traefik/acme.json
+chmod 600 /opt/stacks/core/traefik/acme.json
 
-# Copy .env
-cp ~/AI-Homelab/.env /opt/stacks/traefik/.env
+# Generate password hash for Authelia user
+docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'yourpassword'
+# Copy the output hash
 
-# Deploy
-cd /opt/stacks/traefik
-docker compose up -d
-
-# Check logs
-docker compose logs -f
-# Should see Traefik starting and certificate resolver configured
-```
-
-### 7.3 Authelia (SSO Authentication)
-
-```bash
-# Create stack directory
-mkdir -p /opt/stacks/authelia
-
-# Copy compose file
-cp ~/AI-Homelab/docker-compose/authelia.yml /opt/stacks/authelia/docker-compose.yml
-
-# Copy configuration templates
-cp ~/AI-Homelab/config-templates/authelia/*.yml /opt/stacks/authelia/
-
-# Generate password hash for users_database.yml
-docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'yourpassword'
-# Copy the hash and edit users_database.yml
-
-# Edit users_database.yml
-cd /opt/stacks/authelia
+# Edit users_database.yml with your username and password hash
+cd /opt/stacks/core/authelia
 nano users_database.yml
 # Replace the password hash with your generated one
+# Example:
+# users:
+#   admin:
+#     displayname: "Admin User"
+#     password: "$argon2id$v=19$m=65536..." # Your generated hash
+#     email: admin@example.com
+#     groups:
+#       - admins
 
-# Copy .env
-cp ~/AI-Homelab/.env /opt/stacks/authelia/.env
+# Copy .env file to core stack
+cp ~/AI-Homelab/.env /opt/stacks/core/.env
 
-# Deploy
+# Deploy the entire core stack
+cd /opt/stacks/core
 docker compose up -d
 
-# Check logs
+# Check logs to ensure everything is running
 docker compose logs -f
-# Test login at https://auth.yourdomain.duckdns.org
+
+# You should see:
+# - DuckDNS updating your IP
+# - Traefik starting and acquiring SSL certificates
+# - Authelia initializing
+# - Gluetun connecting to VPN
 ```
 
-### 7.4 Infrastructure Services (Dockge)
+**Verify Core Services:**
+- Traefik dashboard: `https://traefik.yourdomain.duckdns.org` (login with Authelia)
+- Authelia login: `https://auth.yourdomain.duckdns.org`
+- All services should have valid SSL certificates
+
+**Troubleshooting:**
+- If Traefik can't get certificates, check DuckDNS is updating your IP
+- If Authelia won't start, check your password hash and configuration.yml
+- If Gluetun fails, verify your Surfshark credentials in .env
 
 ```bash
 # Create stack directory
@@ -245,7 +223,57 @@ docker compose up -d dockge
 docker compose up -d
 ```
 
-## Step 8: Deploy Additional Stacks
+## Step 8: Deploy Infrastructure Services (Dockge)
+
+```bash
+# Create stack directory
+mkdir -p /opt/stacks/infrastructure
+
+# Copy compose file
+cp ~/AI-Homelab/docker-compose/infrastructure.yml /opt/stacks/infrastructure/docker-compose.yml
+
+# Create necessary subdirectories
+mkdir -p /opt/dockge/data
+mkdir -p /opt/stacks/pihole/{etc-pihole,etc-dnsmasq.d}
+mkdir -p /opt/stacks/glances/config
+
+# Copy .env
+cp ~/AI-Homelab/.env /opt/stacks/infrastructure/.env
+
+# Deploy Dockge first
+cd /opt/stacks/infrastructure
+docker compose up -d dockge
+
+# Access Dockge at https://dockge.yourdomain.duckdns.org (login with Authelia)
+
+# Deploy remaining infrastructure services
+docker compose up -d
+```
+
+## Step 9: Deploy Dashboards (Homepage & Homarr)
+
+```bash
+# Create stack directory
+mkdir -p /opt/stacks/dashboards/{homepage,homarr}
+
+# Copy compose file
+cp ~/AI-Homelab/docker-compose/dashboards.yml /opt/stacks/dashboards/docker-compose.yml
+
+# Copy Homepage configuration templates
+cp ~/AI-Homelab/config-templates/homepage/* /opt/stacks/dashboards/homepage/
+
+# Copy .env
+cp ~/AI-Homelab/.env /opt/stacks/dashboards/.env
+
+# Deploy
+cd /opt/stacks/dashboards
+docker compose up -d
+
+# Access Homepage at https://home.yourdomain.duckdns.org (login with Authelia)
+# Access Homarr at https://homarr.yourdomain.duckdns.org (login with Authelia)
+```
+
+## Step 10: Deploy Additional Stacks
 
 Now use Dockge UI at `https://dockge.yourdomain.duckdns.org` to deploy additional stacks, or continue with command line:
 
diff --git a/docs/services-reference.md b/docs/services-reference.md
index 4a1d4f8..36ce0ef 100644
--- a/docs/services-reference.md
+++ b/docs/services-reference.md
@@ -1,462 +1,327 @@
 # Complete Services Reference
 
-This document lists all 40+ pre-configured services available in the AI-Homelab repository, organized by category.
-
-## Core Infrastructure (4 services)
-
-### Required - Deploy First
-
-1. **DuckDNS** (`duckdns.yml`)
-   - Dynamic DNS updater
-   - Updates your public IP automatically
-   - Integrates with Let's Encrypt for SSL
-   - No web UI - runs silently
-   - Stack: `/opt/stacks/duckdns/`
-
-2. **Traefik** (`traefik.yml`)
-   - Reverse proxy with automatic SSL
-   - HTTP to HTTPS redirect
-   - File-based and Docker label routing
-   - Dashboard: `https://traefik.${DOMAIN}`
-   - Stack: `/opt/stacks/traefik/`
-
-3. **Authelia** (`authelia.yml`)
-   - Single Sign-On (SSO) authentication
-   - TOTP 2FA support
-   - File-based or LDAP user database
-   - Smart bypass rules for media apps
-   - Login: `https://auth.${DOMAIN}`
-   - Stack: `/opt/stacks/authelia/`
-
-4. **Gluetun** (`gluetun.yml`)
-   - VPN client (Surfshark WireGuard)
-   - Includes qBittorrent
-   - Control panel: `http://gluetun:8000`
-   - qBittorrent: `https://qbit.${DOMAIN}`
-   - Stack: `/opt/stacks/gluetun/`
-
-## Infrastructure Tools (7 services)
-
-From `infrastructure.yml` - Stack: `/opt/stacks/infrastructure/`
-
-5. **Dockge** (PRIMARY management tool)
-   - Docker Compose stack manager
-   - Web UI for managing /opt/stacks/
-   - Direct compose file editing
-   - Access: `https://dockge.${DOMAIN}`
-   - SSO: Yes
-
-6. **Portainer** (Secondary)
-   - Docker container management UI
-   - Access: `https://portainer.${DOMAIN}`
-   - SSO: Yes
-
-7. **Pi-hole**
-   - Network-wide ad blocking
-   - DNS server
-   - Access: `https://pihole.${DOMAIN}`
-   - SSO: Yes
-
-8. **Watchtower**
-   - Automatic container updates
-   - Runs 4 AM daily
-   - No web UI
-
-9. **Dozzle**
-   - Real-time Docker log viewer
-   - Access: `https://dozzle.${DOMAIN}`
-   - SSO: Yes
-
-10. **Glances**
-    - System and Docker monitoring
-    - Access: `https://glances.${DOMAIN}`
-    - SSO: Yes
-
-11. **Docker Proxy**
-    - Secure Docker socket access
-    - Backend service
-    - No web UI
-
-## Dashboards (2 services)
-
-From `dashboards.yml` - Stack: `/opt/stacks/dashboards/`
-
-12. **Homepage** (AI-configurable)
-    - Application dashboard with Docker integration
-    - Service widgets for 15+ services
-    - 11 organized categories
-    - Access: `https://home.${DOMAIN}`
-    - SSO: No (landing page)
-
-13. **Homarr**
-    - Modern alternative dashboard
-    - Access: `https://homarr.${DOMAIN}`
-    - SSO: No
-
-## Media Services (6 services)
-
-From `media.yml` - Stack: `/opt/stacks/media/`
-
-14. **Plex**
-    - Media streaming server
-    - Hardware transcoding support
-    - Access: `https://plex.${DOMAIN}`
-    - SSO: No (app access)
-
-15. **Jellyfin**
-    - Open-source media server
-    - Hardware transcoding support
-    - Access: `https://jellyfin.${DOMAIN}`
-    - SSO: No (app access)
-
-16. **Sonarr**
-    - TV show automation
-    - Access: `https://sonarr.${DOMAIN}`
-    - SSO: Yes
-
-17. **Radarr**
-    - Movie automation
-    - Access: `https://radarr.${DOMAIN}`
-    - SSO: Yes
-
-18. **Prowlarr**
-    - Indexer manager
-    - Integrates with Sonarr, Radarr, etc.
-    - Access: `https://prowlarr.${DOMAIN}`
-    - SSO: Yes
-
-19. **qBittorrent**
-    - Torrent client (routes through Gluetun VPN)
-    - See gluetun.yml
-
-## Extended Media (10 services)
-
-From `media-extended.yml` - Stack: `/opt/stacks/media-extended/`
-
-20. **Readarr**
-    - Ebook and audiobook management
-    - Access: `https://readarr.${DOMAIN}`
-    - SSO: Yes
-
-21. **Lidarr**
-    - Music collection manager
-    - Access: `https://lidarr.${DOMAIN}`
-    - SSO: Yes
-
-22. **Lazy Librarian**
-    - Book download automation
-    - Access: `https://lazylibrarian.${DOMAIN}`
-    - SSO: Yes
-
-23. **Mylar3**
-    - Comic book collection manager
-    - Access: `https://mylar.${DOMAIN}`
-    - SSO: Yes
-
-24. **Calibre-Web**
-    - Ebook reader and library management
-    - Access: `https://calibre.${DOMAIN}`
-    - SSO: Yes
-
-25. **Jellyseerr**
-    - Media request management
-    - Integrates with Plex/Jellyfin
-    - Access: `https://jellyseerr.${DOMAIN}`
-    - SSO: No (family access)
-
-26. **FlareSolverr**
-    - Cloudflare bypass for indexers
-    - Used by Prowlarr
-    - No web UI
-
-27. **Tdarr Server**
-    - Distributed transcoding server
-    - Access: `https://tdarr.${DOMAIN}`
-    - SSO: Yes
-
-28. **Tdarr Node**
-    - Transcoding worker
-    - No web UI
-
-29. **Unmanic**
-    - Library optimization and transcoding
-    - Access: `https://unmanic.${DOMAIN}`
-    - SSO: Yes
-
-## Home Automation (7 services)
-
-From `homeassistant.yml` - Stack: `/opt/stacks/homeassistant/`
-
-30. **Home Assistant**
-    - Home automation platform
-    - Uses host networking
-    - Access: `https://ha.${DOMAIN}` (or via proxying external host)
-    - SSO: No (has own auth)
-
-31. **ESPHome**
-    - ESP8266/ESP32 firmware manager
-    - Access: `https://esphome.${DOMAIN}`
-    - SSO: Yes
-
-32. **TasmoAdmin**
-    - Tasmota device management
-    - Access: `https://tasmoadmin.${DOMAIN}`
-    - SSO: Yes
-
-33. **Node-RED**
-    - Flow-based automation programming
-    - Access: `https://nodered.${DOMAIN}`
-    - SSO: Yes
-
-34. **Mosquitto**
-    - MQTT message broker
-    - Ports: 1883, 9001
-    - No web UI
-
-35. **Zigbee2MQTT**
-    - Zigbee to MQTT bridge
-    - Access: `https://zigbee2mqtt.${DOMAIN}`
-    - SSO: Yes
-
-36. **MotionEye**
-    - Video surveillance system
-    - Access: `https://motioneye.${DOMAIN}`
-    - SSO: Yes
-
-## Productivity (8 services + 6 databases)
-
-From `productivity.yml` - Stack: `/opt/stacks/productivity/`
-
-37. **Nextcloud**
-    - File sync and collaboration platform
-    - Access: `https://nextcloud.${DOMAIN}`
-    - SSO: Yes
-    - Database: nextcloud-db (MariaDB)
-
-38. **Mealie**
-    - Recipe manager and meal planner
-    - Access: `https://mealie.${DOMAIN}`
-    - SSO: No (family access)
-
-39. **WordPress**
-    - Blog and website platform
-    - Access: `https://blog.${DOMAIN}`
-    - SSO: No (public blog)
-    - Database: wordpress-db (MariaDB)
-
-40. **Gitea**
-    - Self-hosted Git service
-    - Access: `https://git.${DOMAIN}`
-    - SSO: Yes
-    - Database: gitea-db (PostgreSQL)
-
-41. **DokuWiki**
-    - File-based wiki (no database)
-    - Access: `https://wiki.${DOMAIN}`
-    - SSO: Yes
-
-42. **BookStack**
-    - Documentation platform
-    - Access: `https://docs.${DOMAIN}`
-    - SSO: Yes
-    - Database: bookstack-db (MariaDB)
-
-43. **MediaWiki**
-    - Wiki platform
-    - Access: `https://mediawiki.${DOMAIN}`
-    - SSO: Yes
-    - Database: mediawiki-db (MariaDB)
-
-## Utilities (7 services)
-
-From `utilities.yml` - Stack: `/opt/stacks/utilities/`
-
-44. **Backrest**
-    - Backup management with restic
-    - Access: `https://backrest.${DOMAIN}`
-    - SSO: Yes
-
-45. **Duplicati**
-    - Backup software with encryption
-    - Access: `https://duplicati.${DOMAIN}`
-    - SSO: Yes
-
-46. **Uptime Kuma**
-    - Uptime monitoring and status page
-    - Access: `https://status.${DOMAIN}`
-    - SSO: No (public status)
-
-47. **Code Server**
-    - VS Code in browser
-    - Full stack access
-    - Access: `https://code.${DOMAIN}`
-    - SSO: Yes
-
-48. **Form.io**
-    - Form builder platform
-    - Access: `https://forms.${DOMAIN}`
-    - SSO: Yes
-    - Database: formio-mongo (MongoDB)
-
-49. **Authelia-Redis**
-    - Session storage for Authelia
-    - No web UI
-
-## Monitoring (7 services)
-
-From `monitoring.yml` - Stack: `/opt/stacks/monitoring/`
-
-50. **Prometheus**
-    - Metrics collection
-    - Access: `https://prometheus.${DOMAIN}`
-    - SSO: Yes
-
-51. **Grafana**
-    - Metrics visualization
-    - Access: `https://grafana.${DOMAIN}`
-    - SSO: Yes
-
-52. **Loki**
-    - Log aggregation
-    - No web UI (accessed via Grafana)
-
-53. **Promtail**
-    - Log shipping to Loki
-    - No web UI
-
-54. **Node Exporter**
-    - Host metrics exporter
-    - No web UI
-
-55. **cAdvisor**
-    - Container metrics
-    - Access: Port 8080 (internal)
-
-## Development (6 services)
-
-From `development.yml` - Stack: `/opt/stacks/development/`
-
-56. **GitLab CE**
-    - Git repository with CI/CD
-    - Access: `https://gitlab.${DOMAIN}`
-    - SSO: Yes
-
-57. **PostgreSQL**
-    - SQL database
-    - Port: 5432
-    - No web UI
-
-58. **Redis**
-    - In-memory data store
-    - Port: 6379
-    - No web UI
-
-59. **pgAdmin**
-    - PostgreSQL management UI
-    - Access: `https://pgadmin.${DOMAIN}`
-    - SSO: Yes
-
-60. **Jupyter Lab**
-    - Interactive notebooks
-    - Access: `https://jupyter.${DOMAIN}`
-    - SSO: Yes
-
-## Summary by Stack
-
-| Stack | File | Services Count | Description |
-|-------|------|----------------|-------------|
-| Core Infrastructure | Multiple files | 4 | Traefik, Authelia, DuckDNS, Gluetun |
-| Infrastructure | infrastructure.yml | 7 | Dockge, Portainer, Pi-hole, etc. |
-| Dashboards | dashboards.yml | 2 | Homepage, Homarr |
-| Media | media.yml | 6 | Plex, Jellyfin, *arr apps |
-| Media Extended | media-extended.yml | 10 | Books, comics, music, transcoding |
-| Home Automation | homeassistant.yml | 7 | HA, ESPHome, Node-RED, MQTT, etc. |
-| Productivity | productivity.yml | 14 | Nextcloud, wikis, Git (includes DBs) |
-| Utilities | utilities.yml | 7 | Backups, monitoring, Code Server |
-| Monitoring | monitoring.yml | 7 | Prometheus, Grafana, Loki |
-| Development | development.yml | 6 | GitLab, databases, Jupyter |
-
-**Total: 60+ services (including databases)**
-
-## Access Patterns
-
-### With SSO (Authelia Required)
-- Admin tools (Sonarr, Radarr, Prowlarr, etc.)
-- Infrastructure management (Dockge, Portainer, Grafana)
-- Development tools (GitLab, Code Server, pgAdmin)
-- Personal data (Nextcloud, wikis, BookStack)
-
-### Without SSO (Direct Access)
-- Media streaming (Plex, Jellyfin) - for app access
-- Public services (WordPress, Uptime Kuma, Homepage)
-- Services with own auth (Home Assistant)
-- Family-friendly (Mealie, Jellyseerr)
-
-### Via VPN (Gluetun)
-- qBittorrent
-- Other download clients (add with network_mode: "service:gluetun")
+This document provides a comprehensive overview of all 60+ pre-configured services available in the AI-Homelab repository.
+
+## Services Overview
+
+| Stack | Services | SSO | Storage | Access URLs |
+|-------|----------|-----|---------|-------------|
+| **📦 core** (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 |
+| **🔧 infrastructure** (7) | | | | |
+| ├─ Dockge | Stack manager (PRIMARY) | ✓ | /opt/stacks/infrastructure | dockge.${DOMAIN} |
+| ├─ Portainer | Container management | ✓ | /opt/stacks/infrastructure | portainer.${DOMAIN} |
+| ├─ Pi-hole | DNS + Ad blocking | ✓ | /opt/stacks/infrastructure | pihole.${DOMAIN} |
+| ├─ Watchtower | Auto container updates | - | /opt/stacks/infrastructure | No UI |
+| ├─ 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 |
+| **📊 dashboards** (2) | | | | |
+| ├─ Homepage | App dashboard (AI cfg) | ✓ | /opt/stacks/dashboards | home.${DOMAIN} |
+| └─ Homarr | Modern dashboard | ✓ | /opt/stacks/dashboards | homarr.${DOMAIN} |
+| **🎬 media** (6) | | | | |
+| ├─ Plex | Media server | ✗ | /mnt/media, /mnt/transcode | plex.${DOMAIN} |
+| ├─ Jellyfin | Media server (OSS) | ✗ | /mnt/media, /mnt/transcode | jellyfin.${DOMAIN} |
+| ├─ Sonarr | TV automation | ✓ | /opt/stacks/media, /mnt/media | sonarr.${DOMAIN} |
+| ├─ Radarr | Movie automation | ✓ | /opt/stacks/media, /mnt/media | radarr.${DOMAIN} |
+| ├─ Prowlarr | Indexer manager | ✓ | /opt/stacks/media | prowlarr.${DOMAIN} |
+| └─ qBittorrent | Torrent (via VPN) | ✓ | /mnt/downloads | qbit.${DOMAIN} |
+| **📚 media-extended** (10) | | | | |
+| ├─ Readarr | Ebooks/Audiobooks | ✓ | /opt/stacks/media-ext, /mnt/media | readarr.${DOMAIN} |
+| ├─ Lidarr | Music manager | ✓ | /opt/stacks/media-ext, /mnt/media | lidarr.${DOMAIN} |
+| ├─ Lazy Librarian | Book automation | ✓ | /opt/stacks/media-ext, /mnt/media | lazylibrarian.${DOMAIN} |
+| ├─ Mylar3 | Comic manager | ✓ | /opt/stacks/media-ext, /mnt/media | mylar.${DOMAIN} |
+| ├─ Calibre-Web | Ebook reader | ✓ | /opt/stacks/media-ext, /mnt/media | calibre.${DOMAIN} |
+| ├─ Jellyseerr | Media requests | ✗ | /opt/stacks/media-ext | jellyseerr.${DOMAIN} |
+| ├─ FlareSolverr | Cloudflare bypass | - | /opt/stacks/media-ext | No UI |
+| ├─ Tdarr Server | Transcoding server | ✓ | /opt/stacks/media-ext, /mnt/transcode | tdarr.${DOMAIN} |
+| ├─ Tdarr Node | Transcoding worker | - | /mnt/transcode-cache | No UI |
+| └─ Unmanic | Library optimizer | ✓ | /opt/stacks/media-ext, /mnt/transcode | unmanic.${DOMAIN} |
+| **🏠 homeassistant** (7) | | | | |
+| ├─ Home Assistant | HA platform | ✗ | /opt/stacks/homeassistant | ha.${DOMAIN} |
+| ├─ ESPHome | ESP firmware mgr | ✓ | /opt/stacks/homeassistant | esphome.${DOMAIN} |
+| ├─ TasmoAdmin | Tasmota device mgr | ✓ | /opt/stacks/homeassistant | tasmoadmin.${DOMAIN} |
+| ├─ Node-RED | Automation flows | ✓ | /opt/stacks/homeassistant | nodered.${DOMAIN} |
+| ├─ Mosquitto | MQTT broker | - | /opt/stacks/homeassistant | Ports 1883, 9001 |
+| ├─ Zigbee2MQTT | Zigbee bridge | ✓ | /opt/stacks/homeassistant | zigbee2mqtt.${DOMAIN} |
+| └─ MotionEye | Video surveillance | ✓ | /opt/stacks/homeassistant, /mnt/surveillance | motioneye.${DOMAIN} |
+| **💼 productivity** (8 + 6 DBs) | | | | |
+| ├─ Nextcloud | File sync platform | ✓ | /opt/stacks/productivity, /mnt/nextcloud | nextcloud.${DOMAIN} |
+| │  └─ nextcloud-db | MariaDB | - | /opt/stacks/productivity | No UI |
+| ├─ Mealie | Recipe manager | ✗ | /opt/stacks/productivity | mealie.${DOMAIN} |
+| ├─ WordPress | Blog platform | ✗ | /opt/stacks/productivity | blog.${DOMAIN} |
+| │  └─ wordpress-db | MariaDB | - | /opt/stacks/productivity | No UI |
+| ├─ Gitea | Git service | ✓ | /opt/stacks/productivity, /mnt/git | git.${DOMAIN} |
+| │  └─ gitea-db | PostgreSQL | - | /opt/stacks/productivity | No UI |
+| ├─ DokuWiki | File-based wiki | ✓ | /opt/stacks/productivity | wiki.${DOMAIN} |
+| ├─ BookStack | Documentation | ✓ | /opt/stacks/productivity | docs.${DOMAIN} |
+| │  └─ bookstack-db | MariaDB | - | /opt/stacks/productivity | No UI |
+| ├─ MediaWiki | Wiki platform | ✓ | /opt/stacks/productivity | mediawiki.${DOMAIN} |
+| │  └─ mediawiki-db | MariaDB | - | /opt/stacks/productivity | No UI |
+| └─ Form.io | Form builder | ✓ | /opt/stacks/productivity | forms.${DOMAIN} |
+|    └─ formio-mongo | MongoDB | - | /opt/stacks/productivity | No UI |
+| **🛠️ utilities** (7) | | | | |
+| ├─ Backrest | Backup (restic) | ✓ | /opt/stacks/utilities, /mnt/backups | backrest.${DOMAIN} |
+| ├─ Duplicati | Encrypted backups | ✓ | /opt/stacks/utilities, /mnt/backups | duplicati.${DOMAIN} |
+| ├─ Uptime Kuma | Status monitoring | ✗ | /opt/stacks/utilities | status.${DOMAIN} |
+| ├─ Code Server | VS Code in browser | ✓ | /opt/stacks/utilities | code.${DOMAIN} |
+| ├─ Form.io | Form platform | ✓ | /opt/stacks/utilities | forms.${DOMAIN} |
+| │  └─ formio-mongo | MongoDB | - | /opt/stacks/utilities | No UI |
+| └─ Authelia-Redis | Session storage | - | /opt/stacks/utilities | No UI |
+| **📈 monitoring** (7) | | | | |
+| ├─ Prometheus | Metrics collection | ✓ | /opt/stacks/monitoring | prometheus.${DOMAIN} |
+| ├─ Grafana | Visualization | ✓ | /opt/stacks/monitoring | grafana.${DOMAIN} |
+| ├─ Loki | Log aggregation | - | /opt/stacks/monitoring | Via Grafana |
+| ├─ Promtail | Log shipper | - | /opt/stacks/monitoring | No UI |
+| ├─ Node Exporter | Host metrics | - | /opt/stacks/monitoring | No UI |
+| ├─ cAdvisor | Container metrics | - | /opt/stacks/monitoring | Internal :8080 |
+| └─ Uptime Kuma | Uptime monitoring | ✗ | /opt/stacks/monitoring | status.${DOMAIN} |
+| **👨‍💻 development** (6) | | | | |
+| ├─ GitLab CE | Git + CI/CD | ✓ | /opt/stacks/development, /mnt/git | gitlab.${DOMAIN} |
+| ├─ PostgreSQL | SQL database | - | /opt/stacks/development | Port 5432 |
+| ├─ Redis | In-memory store | - | /opt/stacks/development | Port 6379 |
+| ├─ pgAdmin | PostgreSQL UI | ✓ | /opt/stacks/development | pgadmin.${DOMAIN} |
+| ├─ Jupyter Lab | Notebooks | ✓ | /opt/stacks/development | jupyter.${DOMAIN} |
+| └─ Code Server | VS Code | ✓ | /opt/stacks/development | code.${DOMAIN} |
+
+**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.
+
+### To Enable SSO on a Service
+
+Add the Authelia middleware to the service's Traefik labels:
+
+```yaml
+labels:
+  - "traefik.enable=true"
+  - "traefik.http.routers.servicename.rule=Host(`servicename.${DOMAIN}`)"
+  - "traefik.http.routers.servicename.entrypoints=websecure"
+  - "traefik.http.routers.servicename.tls.certresolver=letsencrypt"
+  - "traefik.http.routers.servicename.middlewares=authelia@docker"  # ← Add this line
+  - "traefik.http.services.servicename.loadbalancer.server.port=8080"
+```
+
+### To Disable SSO on a Service
+
+Remove or comment out the middleware line:
+
+```yaml
+labels:
+  - "traefik.enable=true"
+  - "traefik.http.routers.servicename.rule=Host(`servicename.${DOMAIN}`)"
+  - "traefik.http.routers.servicename.entrypoints=websecure"
+  - "traefik.http.routers.servicename.tls.certresolver=letsencrypt"
+  # - "traefik.http.routers.servicename.middlewares=authelia@docker"  # ← Commented out
+  - "traefik.http.services.servicename.loadbalancer.server.port=8080"
+```
+
+After making changes, redeploy the service:
+```bash
+cd /opt/stacks/stack-name/
+docker compose up -d
+```
+
+**Use Cases for Development/Production:**
+- **Development**: Enable SSO to protect services during testing
+- **Production**: Disable SSO for services that need direct app/API access (Plex, Jellyfin, etc.)
+- **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:
+- AI can read and modify YAML files
+- Version control friendly
+- No UI clicks required
+- Infrastructure as code
+
+**Web UI Available For:**
+- Login page: `https://auth.${DOMAIN}`
+- User profile: Change password, enroll 2FA
+- Device enrollment: Manage trusted devices
+
+**Alternatives with Web UI:**
+If you need a web UI for user management:
+- **Authentik**: More complex but has full web UI
+- **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
 
-### Keep on System Drive (/opt/stacks/)
-- All configuration files
-- Small databases (< 10GB)
-- Application data
+| Data Type | Recommended Location | Reason |
+|-----------|---------------------|--------|
+| Configuration files | `/opt/stacks/stack-name/` | Easy access, version control |
+| Small databases (< 10GB) | `/opt/stacks/stack-name/db/` | Manageable on system drive |
+| Media files (movies, TV, music) | `/mnt/media/` | Large, continuous growth |
+| Downloads | `/mnt/downloads/` | Temporary, high throughput |
+| Backups | `/mnt/backups/` | Large, separate from system |
+| Surveillance footage | `/mnt/surveillance/` | Continuous recording |
+| Large databases (> 10GB) | `/mnt/databases/` | Growth over time |
+| Transcoding cache | `/mnt/transcode-cache/` | High I/O, large temporary files |
+| Git repositories | `/mnt/git/` | Can grow large |
+| Nextcloud data | `/mnt/nextcloud/` | User files, photos |
 
-### Move to Separate Drive (/mnt/)
-- Media files (movies, TV, music, photos) → /mnt/media/
-- Downloads → /mnt/downloads/
-- Backups → /mnt/backups/
-- Surveillance footage → /mnt/surveillance/
-- Large databases → /mnt/databases/
-- Transcoding cache → /mnt/transcode-cache/
+## Configuration Templates
 
-## Quick Deployment Guide
+All configuration templates are available in `config-templates/`:
+- `traefik/` - Static and dynamic Traefik configuration
+- `authelia/` - Complete Authelia setup with user database
+- `homepage/` - Dashboard services, widgets, and Docker integration
+- `prometheus/` - Metrics scrape configurations
+- `loki/` - Log aggregation settings
+- `promtail/` - Log shipping configuration
+- `redis/` - Redis server configuration
 
-1. **Core (Required)**
-   ```bash
-   # Deploy in this order:
-   /opt/stacks/duckdns/
-   /opt/stacks/traefik/
-   /opt/stacks/authelia/
-   /opt/stacks/infrastructure/ (dockge)
-   ```
+## Additional Resources
 
-2. **VPN + Downloads**
-   ```bash
-   /opt/stacks/gluetun/
-   ```
-
-3. **Dashboard**
-   ```bash
-   /opt/stacks/homepage/
-   ```
-
-4. **Choose Your Stacks**
-   - Media: `/opt/stacks/media/` + `/opt/stacks/media-extended/`
-   - Home Automation: `/opt/stacks/homeassistant/`
-   - Productivity: `/opt/stacks/productivity/`
-   - Monitoring: `/opt/stacks/monitoring/`
-   - Development: `/opt/stacks/development/`
-   - Utilities: `/opt/stacks/utilities/`
-
-## Configuration Files
-
-All configuration templates available in `config-templates/`:
-- `traefik/` - Static and dynamic configs
-- `authelia/` - Config and user database
-- `homepage/` - Dashboard services and widgets
-- `prometheus/` - Scrape configurations
-- `loki/` - Log aggregation config
-- And more...
-
-## Next Steps
-
-1. Deploy core infrastructure
-2. Configure Homepage with API keys
-3. Set up Authelia users
-4. Deploy service stacks as needed
-5. Use VS Code + Copilot for AI assistance
-6. Proxy external hosts via Traefik (see docs/proxying-external-hosts.md)
-
-For detailed deployment instructions, see [docs/getting-started.md](../docs/getting-started.md)
+- **Getting Started**: See [docs/getting-started.md](getting-started.md) for detailed deployment
+- **Docker Guidelines**: See [docs/docker-guidelines.md](docker-guidelines.md) for management patterns
+- **Quick Reference**: See [docs/quick-reference.md](quick-reference.md) for common commands
+- **Proxying External Hosts**: See [docs/proxying-external-hosts.md](proxying-external-hosts.md) for Raspberry Pi, NAS, etc.
+- **AI Assistant**: Use GitHub Copilot in VS Code with `.github/copilot-instructions.md` for intelligent homelab management