HomelabARR CE - Container Deployment Guide¶

🎯 Overview¶

This guide categorizes the 287+ containers in HomelabARR CE by deployment requirements, based on systematic testing and validation.

📊 Container Categories¶

✅ Category 1: Ready to Deploy (Recommended Start)¶

These containers deploy successfully with minimal setup:

Dashboard & Management: - Yacht (Container Management) ✅ TESTED - Portainer (Container Management) ✅ TESTED
- Heimdall (Dashboard) ✅ TESTED - Flame (Dashboard) ✅ TESTED - CloudCMD (File Manager) ✅ TESTED - Dashy, Homepage, Fenrus (Other Dashboards)

Addons & Utilities: - Glances, Netdata (System Monitoring) - Librespeed (Network Testing) - Notifiarr (Notifications) - Uptime Kuma (Service Monitoring)

Self-hosted Services: - Bitwarden (Password Manager) - Nextcloud (File Sync) - Organizr (Service Organizer) - Home Assistant (Smart Home)

⚠️ Category 2: Image Version Issues¶

These containers may fail due to outdated Docker image references:

Common Issues: - :version-X.X.X tags that no longer exist - Registry changes (hotio → linuxserver) - Deprecated image repositories

Known Fixes: - Heimdall: version-2.6.1 → latest ✅ FIXED - Overseerr: version-1.33.2 → latest ✅ FIXED
- Flame: jamesread/flame → pawelmalak/flame ✅ FIXED

Requires Manual Review: ~64 containers with version-specific tags

✅ Category 3: Media Stack (unionfs volume)¶

These containers use a shared unionfs volume that maps to /mnt on the host. Ensure /mnt exists before deploying:

sudo mkdir -p /mnt
sudo chown 1000:1000 /mnt

Media Stack apps: - Plex, Jellyfin, Emby (Media Servers) - Radarr, Sonarr, Lidarr (Media Managers) - qBittorrent, SABnzbd, NZBGet (Download Clients) - Bazarr, Tautulli, Prowlarr (Supporting Services)

No plugins required — these use Docker's native bind mount driver.

🚀 Quick Start Guide¶

For New Users (Start Here):¶

1. Begin with Category 1 containers (guaranteed success)
2. Test with simple containers: Yacht, Heimdall, Flame
3. Use provided .env.test file for configuration
4. Deploy one container at a time following our testing protocol

For Advanced Users:¶

1. Install native Docker bind mounts for full media stack
2. Fix image versions as needed
3. Deploy entire stack with proper volume mounting

🛠️ Testing Protocol¶

# 1. Validate YAML syntax
docker compose -f apps/path/container.yml --env-file .env.test config

# 2. Deploy container  
docker compose -f apps/path/container.yml --env-file .env.test up -d

# 3. Verify deployment
docker ps --filter "name=container_name"

# 4. Clean up
docker compose -f apps/path/container.yml --env-file .env.test down

📋 Environment Configuration¶

Required .env.test Variables:¶

DOMAIN=localhost.local
ID=1000
TZ=America/New_York
UMASK=002
RESTARTAPP=unless-stopped
SECURITYOPS=no-new-privileges
SECURITYOPSSET=true
APPFOLDER=/opt/appdata
DOCKERNETWORK=proxy

# Container-specific variables (add as needed)
PORTAINERIMAGE=portainer/portainer-ce:latest
JELLYFINIMAGE=jellyfin/jellyfin:latest
RADARRIMAGE=lscr.io/linuxserver/radarr:latest
# ... etc

🔧 Known Issues & Solutions¶

Issue 1: Missing Environment Variables¶

Symptom: service "name" has neither an image nor a build context specified Solution: Add container-specific variables to .env.test

Issue 2: Outdated Image Tags¶

Symptom: pull access denied or repository does not exist Solution: Update image reference to latest or correct registry

Issue 3: Docker Bind Mount Volumes¶

Symptom: volume driver "local" configuration error Solution: Install plugin or skip unionfs containers for now

Issue 4: Network Configuration¶

Symptom: Network-related errors Solution: Our automated fixes standardized networks to proxy

📈 Success Statistics¶

From Systematic Testing: - ✅ 6/6 Category 1 containers deployed successfully - ❌ 2/2 Category 3 containers failed as expected
- 🔧 3 image fixes applied during testing - 📝 287 YAML files processed by automated fixes

🎯 Recommendations¶

For Production Use:¶

1. Start with Category 1 containers to build confidence
2. Install native bind mount plugin for media server functionality
3. Review image versions before deploying Category 2 containers
4. Use our fixing scripts to standardize configurations

For Testing:¶

1. Use the systematic approach we've established
2. Test one container at a time with proper cleanup
3. Document any new issues discovered
4. Contribute fixes back to the repository

🔗 Related Files¶

• CONTAINER_TESTING_CHECKLIST.md - Detailed testing progress (moved to .claude/local-notes/)
• scripts/fix-all-issues.sh - Master fixing script
• scripts/validate-yml.sh - YAML validation framework
• .env.test - Testing environment variables

Generated by HomelabARR CE Systematic Testing
Date: $(date)
Branch: yaml-fixes-systematic-testing