# ADR 011: Jellyfin media server

- HTML version: https://robbiepalmer.me/projects/homelab/adrs/011-jellyfin
- Project: Home Lab (https://robbiepalmer.me/projects/homelab.md)
- Status: Accepted
- Date: 2026-08-15

# Context

I want to serve TV shows and movies to my Fire TV Stick from the home hub,
so the media I actually own has a proper home instead of sitting as a pile of
files. I already pay for Netflix, Disney Plus, Amazon Prime, and Apple TV,
and still end up rewatching things. The library I've bought deserves a
better player than the streaming apps I pay for repeatedly.

This stayed **Proposed** until it was built, because adoption is the real
test: the server only earns its place if it's good enough to switch to from
the streaming apps, and that is decided by whether the family actually uses
it, not by the scope of the implementation.

* It's strictly for local use in my own home. It will never be a public
  service, so there's no exposure or multi-user internet angle to design for.
* The UX has to be good enough to switch to from the streaming apps, and
  playback latency has to be low enough to not be noticed.
* Adoption is the acceptance test, and it still gates whether this stays
  running: it only gets kept if it's tested with my family and they actually
  use it.

# Decision

Run **Jellyfin** on the Mac mini to serve my media library to the Fire TV
Stick.

Jellyfin is free, open source, self-hosted, and has a first-class Fire TV
client. The library lives on the hub's storage (the same machine that already
holds the photo backup), served only over the home network/tailnet, not
exposed publicly.

The server runs in **Docker Compose** under **colima** on the hub, declared
as code in `homelab/hosts/mac-mini/jellyfin/` in this repo. The image is
pinned, the media library is mounted read-only from the 10TB HDD, and a
launchd agent keeps the stack running across reboots. It's managed with mise
(`mise run //homelab:...`), so upgrades are a version bump plus a recompose.
The router forwards no ports, so access is over the home LAN (the Fire TV
Stick) and the [Tailscale](/projects/homelab/adrs/000-tailscale) tailnet
(phone and laptop). The tailnet is the lab's trust boundary, per the network
ADR.

# Alternatives

## Plex

* **Pros**: Polished clients, easy setup.
* **Cons**: Closed source, account required, and its newer features keep
  pushing toward the paid tier.
* **Decision**: Rejected. For a home-lab library, open source with no
  account wins.

## Keep using streaming subscriptions only

* **Pros**: Zero maintenance, content discovery built in.
* **Cons**: I already pay for Netflix, Disney Plus, Amazon Prime, and Apple
  TV, and still end up rewatching things; my own library stays a pile of
  files.
* **Decision**: Rejected as the only mechanism. Jellyfin serves content I
  already own; it doesn't replace the subscriptions.

## Emby

* **Pros**: Mature, close to Jellyfin.
* **Cons**: Closed source core; Jellyfin is the actively forked, open-source
  evolution of the same codebase.
* **Decision**: Rejected. Jellyfin is the open, no-account choice.

# Consequences

### Pros

* **Own library, self-hosted**: free, open source, and account-free on the
  Fire TV Stick.
* **Strictly local**: served over the home network/tailnet only, never
  public.
* **Better use of the library I already own**, instead of rewatching the
  same titles on the streaming apps I pay for.

### Cons

* **Media library management** (curation, metadata, storage growth) becomes
  an ongoing task.
* **Storage pressure** on the hub alongside the photo backup.
* **Adoption risk**: if the UX or latency isn't good enough for the family,
  it won't get used, the reason it stayed Proposed until built, and the
  gate on keeping it running.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt