Building Project Hestia into a Platform I Can Explain

Project Hestia is the media-services platform in my home Cyber Operations Center. It runs on Atlas v1 and brings together Jellyfin, Seerr and the services that handle requests, downloads, library management and enrichment.

The working system came first. The next step was getting the public project to explain that system properly. I wanted someone opening the repository to understand what each service does, how the pieces connect and which parts still depend on configuration outside Git.

The useful part is how the services connect

Jellyfin handles playback and keeps household users, viewing history and resume state together. Seerr handles discovery and requests. Radarr and Sonarr manage the movie and television libraries, Prowlarr supplies the indexer integration, and qBittorrent handles the transfers.

That sounds straightforward until the boundaries need to be documented. The library managers search through Prowlarr, but they submit downloads to qBittorrent themselves. The architecture diagram needed to show that accurately. A neat diagram is only useful if it describes what the applications actually do.

Recyclarr keeps selected custom-format policy in a tracked configuration file. Bazarr and Trailarr add subtitles and trailers. Vanguarr provides the recommendation layer, with Jellyfin remaining the source of truth for viewing history.

Filesystem paths are part of the design

The download client and library managers share the same data root inside their containers as /data. Jellyfin gets the media and transcode directories through its own mounts. Keeping those paths consistent makes the import workflow easier to understand and avoids unnecessary path translation between services.

The host configuration root and bulk data root are separate and configurable. That gives me a clearer boundary between application state and the media workspace, and a path toward moving Hestia from Atlas v1 to Atlas v2 later.

There are still host dependencies. The supplied Compose definition maps /dev/dri into Jellyfin and Trailarr, and Jellyfin uses the host's video and render group IDs. Those IDs are examples from Atlas, not values I should expect to work on every Linux machine.

Publishing the definition without publishing the household

The public repository contains Compose, documentation and sanitized policy. It does not contain the live application databases, API keys, account details, viewing history or media files.

That distinction also matters for reproducibility. Someone can read and adapt the infrastructure definition, but cloning it does not recreate my configured applications. The API connections, indexers, root folders and accounts still need to be set up in the deployment.

I also wanted the security documentation to be honest about access. A Docker bridge is not the same as an isolated network, and the current published ports bind to all host interfaces. External access controls belong to the deployment layer and are not installed by this Compose file.

Polishing the project without disturbing the working stack

For the v1.0 presentation pass, I prepared a complete README, expanded the architecture and deployment guides, clarified the environment example and strengthened the repository validator. I also added a GitHub Actions workflow for Linux validation.

I kept the Compose changes to comments and formatting. Rendering the old and new definitions produced identical configurations. That was the right boundary for this pass: make the project easier to understand without introducing an unnecessary behavior change into the working platform.

The repository content checks passed, including tests that deliberately introduced unsafe files and credential examples. The secret scans found no leaks in the prepared tree or repository history. Bash and ShellCheck could not run in the Windows sandbox. After the prepared changes were opened as a GitHub pull request, the Linux workflow passed the repository validation, Bash syntax and ShellCheck checks. Keeping those two results separate gave me a clearer account of what had actually been tested.

Knowing what this version includes

Vanguarr is part of the platform, but I do not yet have enough genuine viewing history to judge the quality of personalized recommendations. I want that evaluation to come from actual use.

Backup and restore are outside the scope of Hestia at this point. Most container images also still use mutable tags. Those are boundaries of this version, not features I am going to imply are finished because the repository looks better.

What I am taking from this work is that documenting an integrated platform forces me to check my assumptions. The service list is the easy part. Explaining the paths, state, API relationships and access boundaries is where the design becomes much clearer.

The repository polish has passed Linux validation and is merged, and Hestia v1.0 is published on GitHub. The public project and this journal now describe the same platform. That gives me a clear account of what Hestia actually is today.

Explore Project Hestia on GitHub ↗