diff --git a/config-templates/traefik/traefik.yml b/config-templates/traefik/traefik.yml index 3f6eba0..0451a31 100644 --- a/config-templates/traefik/traefik.yml +++ b/config-templates/traefik/traefik.yml @@ -29,17 +29,13 @@ certificatesResolvers: acme: email: ACME_EMAIL_PLACEHOLDER # Will be replaced by deploy script storage: /acme.json - # HTTP challenge - Simple setup, port 80 must be accessible - # Works for individual domain certificates - httpChallenge: - entryPoint: web - # DNS challenge - For wildcard certificates (advanced) - # Uncomment and comment out httpChallenge to use: - # dnsChallenge: - # provider: duckdns - # resolvers: - # - "1.1.1.1:53" - # - "8.8.8.8:53" + # DNS challenge - For wildcard certificates (*.yourdomain.duckdns.org) + # Works with DuckDNS - requires DUCKDNS_TOKEN in environment + dnsChallenge: + provider: duckdns + resolvers: + - "1.1.1.1:53" + - "8.8.8.8:53" providers: docker: diff --git a/docs/authelia-customization.md b/docs/authelia-customization.md index 6c23972..af702a4 100644 --- a/docs/authelia-customization.md +++ b/docs/authelia-customization.md @@ -110,12 +110,12 @@ This is **by design** and makes Authelia perfect for AI management and security- ## Alternative with Web UI: Authentik -If you need a web UI for user management, Authentik is included in the infrastructure stack: +If you need a web UI for user management, Authentik is included in the alternatives 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 +- Deploy via Dockge when needed **Other Alternatives:** - **Keycloak**: Enterprise-grade SSO with web UI diff --git a/docs/getting-started.md b/docs/getting-started.md index 565ed7a..ec07941 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,6 +2,17 @@ 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. +## Getting Started Checklist + +- [ ] Configure `.env` file with your domain and tokens +- [ ] Run setup script (generates Authelia secrets and admin user) +- [ ] Log out and back in for Docker group permissions +- [ ] Run deployment script (deploys all core services) +- [ ] Access Dockge web UI +- [ ] Set up 2FA with Authelia +- [ ] Deploy additional stacks as needed via Dockge +- [ ] Configure Homepage dashboard widgets + ## Quick Setup (Recommended) For most users, the automated setup script handles everything: @@ -182,17 +193,6 @@ docker compose logs -f docker compose up -d --build service-name ``` -## Getting Started Checklist - -- [ ] Run setup script or manual setup -- [ ] Configure `.env` file -- [ ] Deploy core infrastructure -- [ ] Access Dockge web UI -- [ ] Set up Authelia authentication -- [ ] Deploy additional stacks as needed -- [ ] Configure Homepage dashboard -- [ ] Install VS Code with Copilot - ## Next Steps 1. **Explore services** through Dockge @@ -201,37 +201,4 @@ docker compose up -d --build service-name 4. **Add external services** via Traefik proxying 5. **Use AI assistance** for custom configurations -Happy homelabbing! 🚀 - -## Deployment Improvements (Round 4) - -The repository has been enhanced with the following improvements for better user experience: - -### Automated Configuration -- **Email Substitution**: Deploy script automatically configures Traefik with your ACME_EMAIL -- **Password Generation**: Authelia admin password is auto-generated and saved to `/opt/stacks/core/authelia/ADMIN_PASSWORD.txt` -- **Network Creation**: Docker networks are created automatically before deployment - -### Volume Path Standardization -- All compose files now use **relative paths** (e.g., `./service/config`) for portability -- Stacks work correctly when deployed via Dockge or docker compose -- Large shared data still uses absolute paths (`/mnt/media`, `/mnt/downloads`) - -### SSL Certificate Configuration -- **Default**: HTTP challenge (simple setup, works immediately) -- **Optional**: DNS challenge for wildcard certificates (see comments in traefik.yml) -- Certificates are automatically requested and renewed by Traefik - -### What's Automated -✅ Docker network creation -✅ Traefik email configuration -✅ Authelia password generation -✅ Domain configuration in Authelia -✅ Directory structure creation -✅ Service deployment - -### What You Configure -📝 `.env` file with your domain and API keys -📝 DuckDNS token -📝 VPN credentials (if using Gluetun) -📝 Service-specific settings via Dockge +Happy homelabbing! 🚀 diff --git a/docs/services-overview.md b/docs/services-overview.md index 1067271..8de978b 100644 --- a/docs/services-overview.md +++ b/docs/services-overview.md @@ -6,34 +6,34 @@ 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** | | | | +| **📦 [core.yaml](../docker-compose/core.yml) (4)** | **Deploy First** | | | | | ├─ [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** | | | | +| **🔧 [infrastructure.yaml](../docker-compose/infrastructure.yml) (6+5)** | **Deployed: 6** | | | | | ├─ [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** | | | | +| **📦 [alternatives.yaml](../docker-compose/alternatives.yml) (5)** | **Not deployed** | | | | | ├─ Portainer | Container management | ✓ | /opt/stacks/alternatives | portainer.${DOMAIN} | | ├─ Authentik Server | SSO with web UI | ✓ | /opt/stacks/alternatives | authentik.${DOMAIN} | | │ ├─ authentik-worker | Background tasks | - | /opt/stacks/alternatives | No UI | | │ ├─ authentik-db | PostgreSQL | - | /opt/stacks/alternatives | No UI | | │ └─ authentik-redis | Cache/messaging | - | /opt/stacks/alternatives | No UI | -| **📊 dashboards.yaml** (2) | | | | | +| **📊 [dashboards.yaml](../docker-compose/dashboards.yml)** (2) | | | | | | ├─ Homepage | App dashboard (AI cfg) | ✓ | /opt/stacks/dashboards | home.${DOMAIN} | | └─ Homarr | Modern dashboard | ✓ | /opt/stacks/dashboards | homarr.${DOMAIN} | -| **🎬 media** (6) | | | | | +| **🎬 [media.yml](../docker-compose/media.yml)** (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.yaml** (10) | | | | | +| **📚 [media-extended.yaml](../docker-compose/media-extended.yml)** (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} | @@ -44,7 +44,7 @@ This document provides a comprehensive overview of all 60+ pre-configured servic | ├─ 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.yaml** (7) | | | | | +| **🏠 [homeassistant.yaml](../docker-compose/homeassistant.yml)** (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} | @@ -52,7 +52,7 @@ This document provides a comprehensive overview of all 60+ pre-configured servic | ├─ 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.yaml** (8 + 6 DBs) | | | | | +| **💼 [productivity.yaml](../docker-compose/productivity.yml)** (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} | @@ -67,7 +67,7 @@ This document provides a comprehensive overview of all 60+ pre-configured servic | │ └─ 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.yaml** (7) | | | | | +| **🛠️ [utilities.yaml](../docker-compose/utilities.yml)** (7) | | | | | | ├─ Vaultwarden | Password manager | ✗ | /opt/stacks/utilities | bitwarden.${DOMAIN} | | ├─ Backrest | Backup (restic) | ✓ | /opt/stacks/utilities, /mnt/backups | backrest.${DOMAIN} | | ├─ Duplicati | Encrypted backups | ✓ | /opt/stacks/utilities, /mnt/backups | duplicati.${DOMAIN} | @@ -75,7 +75,7 @@ This document provides a comprehensive overview of all 60+ pre-configured servic | ├─ 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.yaml** (8) | | | | | +| **📈 [monitoring.yaml](../docker-compose/monitoring.yml)** (8) | | | | | | ├─ Prometheus | Metrics collection | ✓ | /opt/stacks/monitoring | prometheus.${DOMAIN} | | ├─ Grafana | Visualization | ✓ | /opt/stacks/monitoring | grafana.${DOMAIN} | | ├─ Loki | Log aggregation | - | /opt/stacks/monitoring | Via Grafana | @@ -83,7 +83,7 @@ This document provides a comprehensive overview of all 60+ pre-configured servic | ├─ 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.yaml** (6) | | | | | +| **👨‍💻 [development.yaml](../docker-compose/development.yml)** (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 | diff --git a/scripts/setup-homelab.sh b/scripts/setup-homelab.sh index b855289..1856f59 100755 --- a/scripts/setup-homelab.sh +++ b/scripts/setup-homelab.sh @@ -559,29 +559,53 @@ if [ "${NVIDIA_REBOOT_NEEDED:-false}" = true ]; then echo " 2. REBOOT YOUR SYSTEM for NVIDIA drivers to load" echo " Run: sudo reboot" echo "" -echo " 3. After reboot, navigate to your AI-Homelab repository:" +echo " 3. After reboot, run the deployment script to deploy your homelab" else -echo " 2. Navigate to your AI-Homelab repository:" +echo " 2. Run the deployment script to deploy your homelab" fi -echo " cd ~/AI-Homelab" -echo "" -if [ "${NVIDIA_REBOOT_NEEDED:-false}" = true ]; then -echo " 4. Run the deployment script:" -else -echo " 3. Run the deployment script:" -fi -echo " ./scripts/deploy-homelab.sh" -echo "" -if [ "${NVIDIA_REBOOT_NEEDED:-false}" = true ]; then -echo " 5. Access Dockge at: https://dockge.yourdomain.duckdns.org" -else -echo " 4. Access Dockge at: https://dockge.yourdomain.duckdns.org" -fi -echo " (Use your configured domain and Authelia credentials)" echo "" echo "==========================================" echo "" log_info "Setup complete!" +echo "" + +# Prompt to run deployment script if [ "${NVIDIA_REBOOT_NEEDED:-false}" != true ]; then - log_info "Please log out and log back in." + echo "" + read -p "Would you like to run the deployment script now? [Y/n]: " -n 1 -r RUN_DEPLOY + echo "" + + # Default to yes if empty + RUN_DEPLOY=${RUN_DEPLOY:-Y} + + if [[ $RUN_DEPLOY =~ ^[Yy]$ ]]; then + log_info "Starting deployment script..." + echo "" + + # Check if user needs to log out first for Docker group + if ! groups "$ACTUAL_USER" | grep -q docker; then + log_warning "You need to log out and back in for Docker group permissions." + log_info "Run this command after logging back in:" + echo "" + echo " cd ~/AI-Homelab && ./scripts/deploy-homelab.sh" + echo "" + else + # Run deployment script as the actual user + cd "$(dirname "$0")/.." || exit 1 + su - "$ACTUAL_USER" -c "cd $PWD && ./scripts/deploy-homelab.sh" + fi + else + log_info "Deployment skipped. Run it manually when ready:" + echo "" + echo " cd ~/AI-Homelab" + echo " ./scripts/deploy-homelab.sh" + echo "" + fi +else + log_info "Please reboot your system for NVIDIA drivers, then run:" + echo "" + echo " cd ~/AI-Homelab" + echo " ./scripts/deploy-homelab.sh" + echo "" fi + diff --git a/tasks.txt b/tasks.txt new file mode 100644 index 0000000..e5af700 --- /dev/null +++ b/tasks.txt @@ -0,0 +1,12 @@ +getting-started.md + Move Getting Started Checklist to just before Simple Setup + Remove Round 4 Deployment inprovments section + Update location reference to alternatives 'If you need a web UI for user management, Authentik is included in the infrastructure stack:' + +manual-setup.md + Ensure manual steps aligned with the two scripts and include everything + +In services-overview.md make the stack names link to the stack compose file + +Modify setup script so that on success it prompts the user to choose to run the deployment script, defaults to yes, and update all relevant documentation +In all documentation ensure there is no info that conflicts with the project requirement of using wildcard certs with DNS Challenge. \ No newline at end of file