---

Note: This repository is a portfolio project demonstrating the HELIOS architecture and user experience. It is not a turnkey deployment and is not intended to be cloned or run as-is.

🎯 What is HELIOS?

HELIOS is a self-hosted media management and server administration system running as Docker containers inside a Proxmox VE virtual machine. It automates the full media lifecycle — request, indexing, download, post-processing, and streaming — while providing centralized dashboards for container and server operations.

This repository showcases the architecture and engineering around that system: modular Docker Compose orchestration, a shared Bash operational library, non-destructive image-update tooling with health checks, NVIDIA GPU passthrough for Plex transcoding, and file-based Docker Secrets management.

🛠️ System Components

Category	Service		Purpose
🎬 Media Management		Wizarr	User Invitation & Onboarding
		Radarr	Movie Collection & Downloads
		Sonarr	TV Series Collection & Downloads
		Bazarr	Subtitle Management
		Seerr	Media Request & Discovery
		Prowlarr	Indexer Management
		Recyclarr	TRaSH Guide Sync
		SABnzbd	Usenet Download Client
		Plex	Media Server & Streaming
		Plex Auto Languages	Automated Language Management
📊 Server Management		Portainer	Container Management
		Tautulli	Media Server Analytics
		Homarr	Dashboard & Service Management
		FlareSolverr	Proxy & Anti-Bot Protection
🔧 Infrastructure		Proxmox VE	Virtualization Platform
		Docker	Containerization Platform

🔄 How It Fits Together

The media stack forms an invite-to-streaming pipeline:

1. Wizarr — admins generate self-serve invite links with optional expiry, one-time use, and library-tier access. Invitees click the link, sign in via Plex OAuth, and walk through a multi-step onboarding wizard that hands them off to Seerr and surfaces server-status channels. Wizarr auto-adds the user as a Plex friend in the background — no manual invite handling.
2. Seerr — users browse and request content. Requests are routed to Radarr (movies) or Sonarr (TV). New Plex sign-ins are auto-imported with default permissions.
3. Prowlarr — centralized indexer manager. Feeds indexers and API keys into Sonarr and Radarr so each *arr doesn't maintain its own.
4. Radarr / Sonarr — monitor requests, search Prowlarr-fed indexers, hand releases to SABnzbd, then import and rename finished files into the media libraries.
5. SABnzbd — Usenet client. Downloads into /mnt/usenet/incomplete/, moves to /mnt/usenet/complete/ on success for *arr post-processing.
6. Recyclarr — runs weekly (@weekly cron). Syncs TRaSH Guide custom formats and quality profiles into Sonarr/Radarr so their release scoring stays current without manual tuning.
7. Bazarr — watches Sonarr/Radarr for imports, pulls subtitles from configured providers, writes them alongside the media files.
8. Plex — serves the finished libraries at /mnt/media/movies and /mnt/media/tv. Transcodes via NVIDIA GPU when clients can't direct-play.
9. Plex Auto Languages — watches Plex sessions and auto-sets audio and subtitle preferences per user based on their configured language.

Operational services run alongside the pipeline:

• Homarr — landing dashboard with service status, quick links, and live Docker integration
• Portainer (+ Agent) — container, image, network, and volume management over an isolated agent network
• Tautulli — Plex watch history, stats, and notifications
• FlareSolverr — Cloudflare bypass proxy used by Prowlarr for protected indexers

🧩 Architecture Notes

• Modular Compose: the root docker-compose.yml uses Compose v2 include to pull in deployments/console/docker-compose.yml and deployments/media/docker-compose.yml. Each sub-stack uses x-common YAML anchors for DRY service configuration (restart policy, PUID/PGID, TZ, UMASK).
• 3-network topology:
  • helios_proxy — external access (Homarr, FlareSolverr, Tautulli)
  • helios_console_agent_network — isolated Portainer ↔ Agent channel
  • helios_default — main network for all media services
• File-based Docker Secrets stored at /etc/HELIOS/secrets/ (symlinked into the repo). Keeps credentials out of env files and out of git.
• Centralized environment: env.sh is a symlink to /etc/HELIOS/env.sh, auto-loaded by direnv on cd. The .env consumed by Docker Compose is regenerated by system-verify.sh.
• NVIDIA GPU passthrough for Plex, paired with an inline 16 GB plex_transcode tmpfs volume — faster transcoding and auto-cleanup on container stop.
• Docker socket integration for Homarr with proper group permissions so the dashboard can surface live container state without running privileged.

🧰 What's in the Repo

The engineering surface lives in scripts/ and the Compose files:

• scripts/_common.sh — shared Bash library sourced by every script. Provides set -euo pipefail, path and root detection, env sourcing, color logging, ERR/EXIT traps, and opt-out flags: HELIOS_NO_ERREXIT=1 for scripts that need to continue past failures (e.g. test-api-connectivity.sh), and HELIOS_START_MSG for custom banners.
• scripts/docker-rebuild.sh — non-destructive image update. Never runs compose down; only pull + up --remove-orphans, so containers with unchanged images are left running. Features: --dry-run, --skip-prune, --skip-health-check, --project-dir; structured exit codes (0 healthy / 1 partial / 2 complete failure); NVIDIA CDI spec regeneration after driver updates; Plex version drift detection against the PlexPass/public channel; jq-based post-update health check with severity assessment; up to 3 retry attempts for transient D-state failures.
• scripts/system-verify.sh — validates Docker/Compose availability, env vars, secrets file presence and 600 permissions, and external networks/volumes. Auto-generates .env from env.sh for Compose consumption.
• scripts/test-api-connectivity.sh — end-to-end API probes across all services using per-service tokens (Plex token, Homarr API key via ApiKey header, Portainer token via X-API-Key over HTTPS 9443).
• scripts/compose-up.sh / compose-down.sh / compose-refresh.sh — lifecycle scripts. compose-refresh delegates to the other two as subprocesses so each phase produces its own log file.
• scripts/media-clean.sh — purges Usenet complete/ and incomplete/ directories, cycling SABnzbd around the cleanup.

All scripts log dual-output to console and logs/<script>.log.

💾 Storage & Data Layout

/mnt                          # Base storage location (LOAS - Location Of All Storage)
├── media/                    # Media library root
│   ├── movies/               # Movie library (mounted to Radarr, Bazarr, Plex)
│   └── tv/                   # TV library (mounted to Sonarr, Bazarr, Plex)
└── usenet/                   # Download directory
    ├── complete/             # Completed downloads (processed by *arr services)
    └── incomplete/           # Active downloads (SABnzbd working directory)

/etc/HELIOS/                  # Centralized configuration root
├── config/                   # Service configuration directories
│   ├── wizarr/               # Wizarr configuration (SQLite DB + onboarding state)
│   ├── seerr/                # Seerr configuration
│   ├── radarr/               # Radarr configuration
│   ├── sonarr/               # Sonarr configuration
│   ├── bazarr/               # Bazarr configuration
│   ├── prowlarr/             # Prowlarr configuration
│   ├── recyclarr/            # Recyclarr configuration
│   ├── sabnzbd/              # SABnzbd configuration
│   ├── plex/                 # Plex Media Server configuration
│   ├── plexautolanguages/    # Plex Auto Languages configuration
│   ├── tautulli/             # Tautulli configuration
│   ├── flaresolverr/         # FlareSolverr configuration
│   └── homarr/               # Homarr configuration
└── secrets/                  # Docker Secrets (symlinked from project root)

Docker Named Volumes

• helios_portainer_data — Portainer settings and management data
• helios_homarr_data — Homarr dashboard data and application state
• plex_transcode — inline 16 GB tmpfs volume for Plex transcoding (RAM-backed, auto-cleanup on container stop)
• plex_downloads — disk-backed volume for Plex download staging (/downloads inside the container)

File Ownership & Permissions

Follows LinuxServer.io conventions: PUID=1000, PGID=984, UMASK=002. Media libraries, config directories, and download directories are all owned 1000:984 with 755; UMASK=002 makes new files group-writable for multi-user access.

📝 Changelog

Full version history in CHANGELOG.md.

---