k8s-mediaserver-charts

k8s-mediaserver

Your all-in-one Helm chart for your media needs!

A Helm chart for deploying a complete media server stack on Kubernetes, including:

Chart Structure

This repository contains:

All container images used by the chart are from linuxserver.io except Seerr which uses the official image from seerr-team.

Each of the components can be enabled or disabled if you already have something in place in your lab!

Introduction

This Helm chart provides a simple and minimalistic way to deploy a complete media server stack on Kubernetes, with customizations that are strictly related to usability and access, rather than complex customizations.

Each container has its init container in order to initialize configurations on the PV before starting the actual pod and avoid restarting the pods.

The chart is structured as an umbrella chart with individual service charts as dependencies, allowing you to:

Prerequisites

QuickStart

Installation

Option 1: Install All Services (Umbrella Chart)

  1. Add the Helm repository (if using a chart repository):
helm repo add k8s-mediaserver-charts https://95gabor.github.io/k8s-mediaserver-charts
helm repo update
  1. Install the umbrella chart with default values:
# Using local chart directory
helm dependency update ./charts/k8s-mediaserver
helm upgrade --install k8s-mediaserver ./charts/k8s-mediaserver \
  -n k8s-mediaserver --create-namespace

# Or from chart repository
helm upgrade --install k8s-mediaserver k8s-mediaserver-charts/k8s-mediaserver \
  -n k8s-mediaserver --create-namespace
  1. (Optional) Use custom values:
# Copy the default values file
cp ./charts/k8s-mediaserver/values.yaml my-values.yaml

# Edit my-values.yaml with your custom settings

# Install with custom values
helm dependency update ./charts/k8s-mediaserver
helm upgrade --install k8s-mediaserver ./charts/k8s-mediaserver \
  -n k8s-mediaserver --create-namespace \
  -f my-values.yaml

Option 2: Install Individual Services

You can also install individual service charts independently:

# Example: Install only Sonarr
helm upgrade --install sonarr ./charts/sonarr \
  -n sonarr --create-namespace \
  -f ./charts/sonarr/values.yaml

# Example: Install only Plex
helm upgrade --install plex ./charts/plex \
  -n plex --create-namespace \
  -f ./charts/plex/values.yaml

See the charts README for a complete list of available charts.

Upgrading

# Update dependencies first
helm dependency update ./charts/k8s-mediaserver

# Then upgrade
helm upgrade k8s-mediaserver ./charts/k8s-mediaserver \
  -n k8s-mediaserver \
  -f my-values.yaml

Uninstalling

# Uninstall umbrella chart (removes all services)
helm uninstall k8s-mediaserver -n k8s-mediaserver

# Or uninstall individual services
helm uninstall sonarr -n sonarr

Default Access URLs

With default settings, your applications will run at these paths:

Service Link
Sonarr http://k8s-mediaserver.k8s.test/sonarr
Radarr http://k8s-mediaserver.k8s.test/radarr
Transmission http://k8s-mediaserver.k8s.test/transmission
Jackett http://k8s-mediaserver.k8s.test/jackett
Prowlarr http://k8s-mediaserver.k8s.test/prowlarr
Sabnzbd http://k8s-mediaserver.k8s.test/sabnzbd
Seerr http://k8s-mediaserver.k8s.test/seerr
Jellyfin http://k8s-jelly.k8s.test/
PLEX http://k8s-plex.k8s.test/

Configuration

The chart is quite simple to configure, with a low number of parameters to avoid confusion, while still allowing customization to fit the resources inside your cluster.

See the values.yaml file for all available configuration options, or check the Helm chart README for detailed documentation.

General Configuration

Key configuration options:

Service Configuration

Each service can be enabled/disabled and configured individually:

Available Charts

This repository contains the following Helm charts:

Each chart has its own README with detailed documentation. See charts/README.md for more information.

Helpful Use Cases

Using a cluster-external NFS server

This assumes that you have a pre-configured NFS server set up on your network that is accessible from all nodes. If it is not accessible by all nodes, pods will not enter ready state when scheduled on nodes that do not have NFS access.

To add an NFS volume to each resource, edit your values.yaml to match the snippet below. You should change the server: and path: values to match your NFS.

general:
  storage:
    customVolume: true
    volumes:
      nfs:
        server: { SERVER-IP }
        path: /mount/path/on/nfs/server/

Adding annotations to the extra load balancer

If you need an extra load balancer on any service, you can either enable it like this:

plex:
  service:
    extraLbService:
      enabled: true

or like this, if you need to add annotations to it (for use with cloud providers to configure the load balancer for example):

plex:
  service:
    extraLbService:
      enabled: true
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags: "Key=Value"

Development

Setup Development Environment

  1. Install pre-commit:

    pip install pre-commit

  2. Install git hooks:

    pre-commit install
pre-commit install --hook-type commit-msg

    This will automatically run checks before each commit, including:

    • Conventional commit message validation
    • YAML syntax checking
    • Helm chart linting
    • Documentation generation
    • File formatting checks

  3. Run pre-commit on all files (optional):

    pre-commit run --all-files

Development Workflow

Linting

pre-commit run --all-files

Template Rendering

helm template test-release ./charts/k8s-mediaserver -f ./charts/k8s-mediaserver/values.yaml

Packaging

helm package ./charts/k8s-mediaserver

Generating Documentation

helm-docs --chart-search-root=charts

Commit Message Format

This project uses Conventional Commits. Commit messages should follow this format:

<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, test, chore

Examples:

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

Acknowledgments

Special thanks to kubealex (Alessandro Rossi) for creating the original k8s-mediaserver project. This repository is a fork with enhancements including:

Contributors

About the Project

This project is intended as an exercise, and absolutely for fun. This is not intended to promote piracy.

Also feel free to contribute and extend it!

This site is open source. Improve this page.