Lumastra on Kubernetes

A media server built for Kubernetes, with a Helm chart

Lumastra is a self-hosted media server for Kubernetes, installed with a Helm chart. Its web replicas, background worker, playback router, PostgreSQL database and Valkey services run as separate workloads. Scale the part that is busy, and restart one part without stopping the rest.

Movies, series, music, audiobooks (through Audiobookshelf) and Live TV. AGPL-3.0, free.

Separate services, not a monolith

Most media servers are one process with a local database. That fits one machine, not a cluster. The chart deploys each job as its own workload.

Web replicas

The web pods serve the UI, the API and video. Two by default. Add more when more people stream.

A router that keeps streams sticky

An nginx router sends every request of one playback session to the same web pod. Your Ingress needs no session affinity.

A worker of its own

Scans, artwork and analysis run in a separate worker pod with its own limits. Put it on another node to keep scans away from playback.

PostgreSQL and two Valkeys

Use CloudNativePG or your own PostgreSQL. The chart bundles one Valkey for the task queue (persistent, no eviction) and one for the cache (LRU).

Made for how you run a cluster

Rolling updates

Web pods update one at a time and drain first. With shared transcode storage, another pod picks up a running stream. Pod disruption budgets keep one web pod and one router up.

GitOps

The chart never creates a secret. It reads one you provide, so Argo CD or Flux can render it offline. Pin a release tag or an image digest.

Probes and metrics

Startup, readiness and liveness probes on every app pod. A /metrics endpoint, an optional ServiceMonitor and worker alerts for Prometheus.

Ingress or Gateway API

Expose it with an Ingress or an HTTPRoute. Network policies are included.

Single sign-on, native

OIDC or forward auth checked at the router, used natively by the web app and the Apple apps. Apple TV signs in through your provider with a QR code.

GPU transcoding

Intel Quick Sync, VA-API or NVIDIA NVENC, through a device plugin resource or a host path.

Pods run as a non-root user with a read-only root filesystem and all capabilities dropped.

Using Jellyfin apps on Kubernetes

Streamyfin, Moonfin and Jellyfin for Android TV connect to Lumastra's Jellyfin-compatible API at /j on your Lumastra address. No Jellyfin server runs in the cluster.

Connect a Jellyfin app Streamyfin and Jellyfin apps

Install with Helm

An outline. The guide has every step, including a one-node k3s install with CloudNativePG.

Helm, with an existing Secret and your own PostgreSQL
kubectl create namespace lumastra
kubectl -n lumastra create secret generic lumastra \
  --from-literal=LUMASTRA_MASTER_KEY="$(openssl rand -hex 32)" \
  --from-literal=CACHE_PASSWORD="$(openssl rand -hex 24)" \
  --from-literal=DATABASE_URL="postgres://lumastra:<password>@<host>:5432/lumastra"

helm install lumastra oci://ghcr.io/lumastra/charts/lumastra --version 0.2.0 -n lumastra \
  --set image.tag=0.2.0 \
  --set secrets.existingSecret=lumastra \
  --set app.origin=https://media.example.com

For a database the chart manages, install the CloudNativePG operator, set database.mode=cnpg and leave out DATABASE_URL. Then add your media under libraries and an ingress block. Back up LUMASTRA_MASTER_KEY.

Good to know

One host and no cluster? Docker Compose runs the same services and is fully supported. Docker Compose guide