This repository provides a Nix flake that allows for declarative configuration of Users, Libraries, Settings, etc.

Features

• Declarative users
  • permissions
• Libraries
  • User specific library access
• Server Settings
  • System
  • Network
  • Encoding (HW acceleration)
  • Branding settings
• Automatic backups
• API keys

Documentation

Automatically generated documentation outlining all options is available in documentation.md

FAQ

Frequently asked questions and common problems are documented in FAQ.md

Usage

Setup

Add the flake to your inputs and import the nixosModule in your configuration.

Example minimal flake.nix:

{
  description = "An example using declarative-jellyfin flake";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
    declarative-jellyfin.url = "github:Sveske-Juice/declarative-jellyfin";
  };

  outputs = {
    nixpkgs,
    declarative-jellyfin,
    ...
  }: {
    nixosConfigurations."your-hostname" = nixpkgs.lib.nixosSystem {
      modules = [
        declarative-jellyfin.nixosModules.default # <- this imports the NixOS module that provides the options
        ./configuration.nix # <- your host entrypoint
      ];
    };
  };
}

Examples

See the example directory for example configs.

General server settings

You can configure system settings through the services.declarative-jellyfin.system options.

Example:

services.declarative-jellyfin.system = {
  serverName = "My Declarative Jellyfin Server";
  # Use Hardware Acceleration for trickplay image generation
  trickplayOptions = {
    enableHwAcceleration = true;
    enableHwEncoding = true;
  };
  UICulture = "da"; # Make the UI language danish
};

Users

You can configure users with the options provided by services.declarative-jellyfin.users.

Example:

services.declarative-jellyfin.users = {
  admin = {
    mutable = false; # overwrite user settings
    permissions.isAdministrator = true;
    hashedPasswordFile = config.sops.secrets.jellyfin-admin-passwd.path;
  };
  "Alice Doe" = {
    password = "123"; # WARNING: plain text!
    permissions.enableMediaPlayback = false; # this user is not allowed to play media
  };
};

Generate user password hash

Jellyfin uses pbkdf2-sha512 hashes to store passwords. Use the genhash script bundled in this flake with the parameters the jellyfin DB expects:

$ nix run github:Sveske-Juice/declarative-jellyfin#genhash -- -i 210000 -l 128 -u -k "your super secret password"

Usage with sops-nix

Extract the secret and use the hashedPasswordFile:

sops.secrets.example-user-password = {
    owner = config.services.jellyfin.user;
    group = config.services.jellyfin.group;
};
services.declarative-jellyfin.users.example-user.hashedPasswordFile = config.sops.secrets.example-user-password.path;

Libraries

You can configure libraries with the options provided by services.declarative-jellyfin.libraries.

Below are some examples of different types of libraries:

services.declarative-jellyfin.libraries.Movies = {
  enabled = true;
  contentType = "movies";
  pathInfos = ["/data/Movies"];
};

services.declarative-jellyfin.libraries.Shows = {
  enabled = true;
  contentType = "tvshows";
  pathInfos = ["/data/Shows"];
};

services.declarative-jellyfin.libraries."Family photos" = {
  enabled = true;
  contentType = "homevideos";
  pathInfos = ["/data/Famility/Photos" "/data/Family/Videos"];
};

services.declarative-jellyfin.libraries.Books = {
  enabled = true;
  contentType = "books";
  pathInfos = ["/data/Books"];
};

services.declarative-jellyfin.libraries.Music = {
  enabled = true;
  contentType = "music";
  pathInfos = ["/data/Music"];
};

See the source code for possible library content types.

Limit a user's access to specific libraries

To whitelist the libraries the user have access to, you can use services.declarative-jellyfin.users.<name>.preferences.enabledLibraries:

services.declarative-jellyfin.users.your-username = {
  # ...
  preferences = {
    enabledLibraries = ["Movies" "Photos and Videos"]; # Libraries that the user has access to
  };
  permissions = {
    enableAllFolders = false;
  };
};

It's important to disable permissions.enableAllFolders otherwise the preferences won't have any effect.

Hardware Acceleration

First figure out what HW acceleration methods your system supports: https://jellyfin.org/docs/general/post-install/transcoding/hardware-acceleration/

Then configure the options through services.declarative-jellyfin.encoding.

Example with AMD VA-API:

# AMD VA-API and VDPAU should work out of the box with mesa
hardware.graphics.enable = true;
users.users.${config.services.jellyfin.user}.extraGroups = ["video" "render"];

services.declarative-jellyfin = {
    # ... other configuration ...
    encoding = {
      enableHardwareEncoding = true;
      hardwareAccelerationType = "vaapi";
      enableDecodingColorDepth10Hevc = true; # enable if your system supports
      allowHevcEncoding = true; # enable if your system supports
      allowAv1Encoding = true; # enable if your system supports
      hardwareDecodingCodecs = [ # enable the codecs your system supports
        "h264"
        "hevc"
        "mpeg2video"
        "vc1"
        "vp9"
        "av1"
      ];
    };
};

Use vainfo from libva-utils to see the codec capabilities for your VA-API device.

Plugins

Plugins are very difficult to manage declaratively, so for now you can only manage the plugin repositories declaratively

services.declarative-jellyfin = {
    system.pluginRepositories = [
        {
          content = {
            Name = "Jellyfin Stable";
            Url = "https://repo.jellyfin.org/files/plugin/manifest.json";
          };
          tag = "RepositoryInfo"; # Needed to generate the correct XML
        }

        {
          content = {
            Name = "Intro Skipper";
            Url = "https://intro-skipper.org/manifest.json";
          };
          tag = "RepositoryInfo"; # Needed to generate the correct XML
        }
    ];
};

This will download the specified verson of the plugin and install it for you during evaluation.

Configuring plugins

This is still not possible, but is being worked on.

Migrating from existing config

Declarative Jellyfin is designed to be a drop-in replacement for the normal jellyfin service.

- services.jellyfin = {
+ services.declarative-jellyfin = {

API Keys

Example:

services.declarative-jellyfin.apikeys = {
  Jellyseerr = {
    keyPath = config.sops.secrets.my-jellyfin-jellyseerr-key.path;
  };
  "Homarr Dashboard" = {
    key = "78878bf9fc654ff78ae332c63de5aeb6"; # WARNING: plain-text!
  };
};

Known Issues

Intro Skipper stops working after a while

Don't know why this happens. A workaround is to restart jellyfin (through the dashboard, restarting the service doesn't count) which will make it work again for a while.