- setup-homelab.sh: Fixed syntax errors, placeholder detection, and hardcoded paths
- deploy-homelab.sh: Refactored from inline code to function-based structure
- Both scripts now use consistent function organization for better readability
- Enhanced credential handling and error checking
- All scripts validated for syntax correctness
Fixes:
- docker-compose/infrastructure.yml:
- Uncommented Watchtower service
- Updated image from 1.7.1 to latest
- Changed DOCKER_API_VERSION from 1.44 to 1.52 (current Docker version)
- Added default empty value for WATCHTOWER_NOTIFICATION_URL
- scripts/deploy-homelab.sh:
- Removed "temporarily disabled" note
- Added Watchtower to infrastructure stack list
- docs/services-overview.md:
- Updated infrastructure stack count from 7 to 8
- Added Watchtower to service list
Watchtower now runs successfully with scheduled updates at 4 AM daily
Changes:
- scripts/setup-homelab.sh: Remove interactive deployment prompt
- Users must now run deploy script manually
- Simplifies both scripts (no sudo workarounds needed)
- Clearer two-step process: setup then deploy
- Documentation updates:
- README.md: Updated step 3-4 with manual deployment
- docs/getting-started.md: Removed step 6 (log out), clarified steps
- docs/manual-setup.md: Added sudo to deploy command
- docs/troubleshooting/COMMON-ISSUES.md: Added sudo to all deploy commands
Rationale:
- Automatic deployment via 'su -' cannot work with sudo requirement
- Manual two-step process is clearer and more reliable
- Setup focuses on configuration, deploy focuses on services
- setup-homelab.sh: Save AUTHELIA_ADMIN_* credentials to .env file
- deploy-homelab.sh: Check .env file as fallback if temp files don't exist
- .env.example: Document auto-generated Authelia admin variables
This ensures credentials survive reboots (e.g., when NVIDIA drivers are installed)
and the deploy script can find them even when run manually after reboot.
- setup-homelab.sh: Store temp files in /opt/stacks/.setup-temp instead of /tmp
- deploy-homelab.sh: Read credentials from new persistent location
- reset-test-environment.sh: Clean up new temp directory
This fixes the issue where credentials were inaccessible when deploy script
runs via 'su -' (login shell) from setup script, as /tmp files created by
root are not accessible across the su boundary.
- getting-started.md: Moved checklist before Simple Setup, removed Round 4 section
- authelia-customization.md: Updated Authentik reference to alternatives stack
- services-overview.md: Added clickable links to all stack compose files
- setup-homelab.sh: Added prompt to run deployment script after setup (defaults to yes)
- traefik.yml: Changed default to DNS challenge for wildcard certificates (DuckDNS)
All documentation now reflects wildcard certificate usage with DNS challenge.
Critical fix for argon2 password hash preservation:
- Root cause: Bash variable expansion of $ characters in argon2id hashes
- Solution: Write hash directly from Docker output to file, bypass bash variables entirely
- setup-homelab.sh: Stream Docker output directly to /tmp/authelia_password_hash.tmp
- deploy-homelab.sh: Read hash file in Python to avoid any bash expansion
- Result: Password hash correctly preserved with full $argon2id$v=19$m=... format
Other changes:
- Added DOCKER_API_VERSION=1.44 env var for watchtower (API compatibility)
- Watchtower still has issues with Docker 29.1.4 - keeping version pinned for investigation
Tested on Debian 12 with Docker 29.1.4:
✅ All 11 critical containers healthy
✅ Authelia authentication working correctly
✅ Password hash preserved through entire deployment workflow
⚠️ Watchtower restart loop (non-critical, under investigation)
Issue: sed with | delimiter still has problems with $ in argon2 hash
Attempted fix: Escape special characters before sed replacement
Note: Manual sed with double quotes works, suggesting escaping strategy
may need refinement. Need to test if this resolves the issue.
Issue: Heredoc variable expansion was mangling password hashes containing $ characters
Solution: Use quoted heredoc ('EOF') with placeholders, then sed replace
The unquoted heredoc was interpreting $ in the argon2 hash as shell variable
expansion, corrupting the hash format.
CRITICAL: Previous rounds caused system crashes during cleanup operations
New Safe Reset Script:
- Gracefully stops all containers before cleanup
- Waits for proper shutdown sequences
- Removes Docker volumes only after containers stopped
- Prevents filesystem corruption from aggressive rm operations
- Includes confirmation prompts for safety
Deploy Script Improvements:
- Stops existing containers before config file operations
- Removes dangerous auto-cleanup of Docker volumes
- Adds safety checks before directory removal
- Warns about existing databases instead of auto-removing
Dangerous Operations Removed:
- No more rm -rf while containers running
- No more automatic volume deletion
- No more blind directory removal
- No more container restart during volume operations
Testing Guidelines:
- Always use reset-test-environment.sh for cleanup
- Never run cleanup while containers active
- Monitor system health during operations
- Proper shutdown sequence documented
This prevents the BIOS-level crashes experienced in previous rounds.
- Fix password file ownership (user can now read without sudo)
- Add dashboards stack to automated deployment (Step 5/6)
- Add SSL certificate notes to deploy script output
- Clarify .env file location in documentation (stays in repo folder)
- Update README and getting-started.md with accurate deployment steps
- Add Watchtower notification URL documentation
- Improve user feedback with admin credentials and dashboard URLs
- Remove dashboards from 'Next Steps' since it's now automated
User experience improvements:
- Password file readable by user immediately
- Homepage and Homarr deployed automatically
- Clear guidance on .env file management
- Better SSL certificate expectations
- Add DOCKER_API_VERSION=1.44 to Watchtower (fixes crash loop)
- Add dockerproxy-network creation to deploy script (fixes dashboard deployment)
- Add explicit acme.json file creation with 600 permissions (fixes SSL cert acquisition)
- Fix setup script to correctly resolve user home directory when run with sudo
These fixes resolve all critical blockers discovered in Round 3 testing.
- Refactored README.md, getting-started.md, quick-reference.md
- Enhanced setup-homelab.sh with 9-step automated process
- Created services-overview.md with all stacks
- Added comprehensive documentation for 57 services in docs/service-docs/
- All services include: overview, configuration, resources, educational content
- Coverage: Core, Infrastructure, Dashboards, Media, Media-Extended, Home Assistant, Productivity, Utilities, Monitoring, Development stacks
- Educational focus with links to tutorials, videos, and guides
- Add Vaultwarden (Bitwarden) password manager to utilities.yml
- Self-hosted password manager with web UI
- SMTP configuration for email notifications
- Admin token for management
- Access at bitwarden.${DOMAIN}
- Protected by Authelia SSO
- Create automated first-run setup script (scripts/setup-homelab.sh)
- Installs Docker Engine and Compose V2
- Configures user groups (sudo, docker)
- Enables SSH for remote management
- Detects NVIDIA GPU and provides manual driver installation instructions
- Creates directory structure and Docker networks
- Comprehensive instructions for post-setup deployment
- Remove redundant compose files (now in core.yml)
- Deleted authelia.yml, duckdns.yml, gluetun.yml, traefik.yml
- All services consolidated into unified core.yml stack
- Eliminates confusion and duplication
- Update disk space requirements across documentation
- Changed from "100GB+ system, 1TB+ media" to:
- "120GB+ system drive (NVMe or SSD highly recommended)"
- "2TB+ for media & additional disks for services like Nextcloud"
- Updated in README.md and getting-started.md
- Add preference for LinuxServer.io images
- Updated copilot-instructions.md
- LinuxServer images support PUID/PGID for proper file permissions
- Preference noted in consistency guidelines
- Update core stack documentation
- Emphasize unified core.yml deployment
- Add both deployment methods (cd to directory vs full path)
- Update getting-started.md with correct deployment steps
- Note removal of separate stack files
- Add Bitwarden environment variables to .env.example
- BITWARDEN_ADMIN_TOKEN, SIGNUPS_ALLOWED, INVITATIONS_ALLOWED
- SMTP configuration for email notifications
- Generation instructions included
- Update services-reference.md
- Add Vaultwarden to utilities section (now 7 services)
- Update service count and access URLs
All documentation now consistent with unified core stack approach and includes all requested features.
Co-authored-by: kelinfoxy <67766943+kelinfoxy@users.noreply.github.com>
