Install

Docker on any Linux Tested

Any Linux machine with Docker, including a VPS from any host.

1. Make a folder

   Terminal

   $ mkdir -p ~/leyla && cd ~/leyla

2. Save the compose file there

   As compose.yaml. Set PUID and PGID from what id prints, and the three folders.

3. Start it

   Terminal

   $ docker compose up -d

On a VPS, put Leyla behind a reverse proxy for HTTPS (Caddy, nginx, Traefik or a Cloudflare tunnel), then tell Leyla about it under Admin, Server, Remote access.

Synology

DSM 7.2 and later.

1. Install Container Manager

   From Package Center.

2. Make Leyla’s folders

   In File Station: docker/leyla/data and docker/leyla/plugins.

3. Find your account’s numbers

   Control Panel → Terminal & SNMP → enable SSH, then ssh you@nas and id. A DSM account is usually 1026, group 100.

4. Create the project

   Container Manager → Project → Create, path docker/leyla, “Create docker-compose.yml”, and paste the compose file. Set PUID, PGID and your media path (/volume1/video or wherever your films live).

5. Hardware transcoding, if the box has it

   If ls /dev/dri over SSH lists renderD128 (most Intel “+” models), uncomment the devices block. AMD Ryzen models such as the DS923+ have none: leave it commented, or the container won’t start.

QNAP

QTS 5 and QuTS hero.

1. Install Container Station

2. Make a share folder

   Container/leyla, with data and plugins in it.

3. Create the application

   Container Station → Applications → Create, and paste the compose file. Paths start with /share/: /share/Container/leyla/data, and /share/Multimedia:/media:ro for your media. For PUID/PGID, run id over SSH as your own account, not admin.

4. Intel models

   Uncomment devices if /dev/dri exists.

unRAID

Docker → Add Container, and choose the Leyla template. It asks for the app data, plugins and media folders, and fills in PUID 99 and PGID 100. Until Leyla is in Community Applications, beta households get the template’s address with their invitation.

For Intel or AMD transcoding keep /dev/dri. For NVIDIA, install the Nvidia-Driver plugin, add --runtime=nvidia to Extra Parameters and set NVIDIA_VISIBLE_DEVICES.

TrueNAS Scale

24.10 and later. Apps → Discover → ⋮ → Install via YAML, and paste the compose file. Use datasets you made for Leyla (/mnt/<pool>/apps/leyla/data and …/plugins) and your media dataset.

TrueNAS’s apps user is 568, group 568: either use it and give it read access to your media, or use your own account’s numbers. For an Intel or AMD GPU, uncomment devices. For NVIDIA, install the drivers under Apps → Settings and add to the service:

    runtime: nvidia
    environment:
      NVIDIA_VISIBLE_DEVICES: all
      NVIDIA_DRIVER_CAPABILITIES: compute,video,utility

OpenMediaVault

Version 7. Install openmediavault-compose from omv-extras. Services → Compose → Files → Create, paste the compose file, and use your shared folders’ full paths (/srv/dev-disk-by-uuid-…/media). OMV’s first user is usually 1000, group 100.

TerraMaster

TOS 6. Install Docker Manager from the App Center, then Project → Create and paste the compose file. Volumes are /Volume1/…; PUID/PGID from id over SSH.

Raspberry Pi

A Pi 4 or 5 with the 64-bit Raspberry Pi OS; the 32-bit one isn’t supported. Install Docker, then follow Docker on any Linux:

$ curl -fsSL https://get.docker.com | sh

On a Pi Keep the data folder on a USB SSD, not the SD card. A Pi has no hardware encoder Leyla uses, so what needs converting is converted on its CPU; playing files as they are and copying them are what a Pi does well.

Debian, Ubuntu, Fedora Containers only

For a machine where you’d rather not run Docker: a .deb (Debian 12+, Ubuntu 22.04+), an .rpm (RHEL, Rocky and Alma 9+, Fedora) and a tarball, for amd64 and arm64. They need glibc 2.34 or later. They install and serve in each distribution’s container; not yet on a real machine.

$ sudo apt install ./leyla_<version>_amd64.deb

$ sudo dnf install ./leyla-<version>.x86_64.rpm

The package makes a leyla system user, installs Leyla and its own ffmpeg under /usr/lib/leyla, and starts the leyla service. Data lives in /var/lib/leyla, settings in /etc/leyla/leyla.env. Give the leyla user read access to your media:

$ sudo setfacl -R -m u:leyla:rX /srv/media

For hardware transcoding the package recommends your distribution’s VAAPI and Intel media drivers; NVIDIA needs the proprietary driver. Removing the package keeps your data and settings.

Windows Early

Windows 10 and 11, x64. It builds and gets as far as creating its database, but hasn’t been installed on a real Windows machine yet. Try it if you’re curious; don’t move your household onto it.

1. Run the setup

   Leyla-Setup-<version>.exe: press Install. It puts Leyla in C:\Program Files\Leyla and starts the Leyla service, which runs at boot, with the Microsoft runtime its database needs, and lets your home network in through the firewall. For many PCs at once, the same install comes as leyla-<version>-windows-x64.msi.

2. Let it read your media

   The service runs as NETWORK SERVICE. Most drives already let it read; a network share has to allow this computer’s account.

3. Open it

   The setup opens it in your browser when it finishes. Later, http://localhost:10001 on that computer.

Data, plugins and logs are in C:\ProgramData\Leyla, and uninstalling keeps them.

What every install needs

Data

A folder mounted at /app/data: the database, artwork and downloads. On an SSD if the box has one.

Plugins

A writable folder at /app/plugins, for plugins installed from Leyla’s store.

Media

Your films and shows at /media, read-only. Mount several folders under it if they live on different shares (/media/films, /media/tv).

Who

PUID and PGID: the user and group that own your media. Leyla runs as that account and makes the data folder its own on the first start.

Port

10001. Open http://<the box>:10001 and follow the setup.

The compose file

Most boxes below take this one file as it is. Change the lines marked CHANGE; the section for your box says what to put there.

# Leyla on a NAS, a Raspberry Pi or any Docker host, from the published
# image. One file for every box: Synology Container Manager, QNAP Container
# Station, TerraMaster Docker Manager, OpenMediaVault's compose plugin and
# TrueNAS Scale's "Install via YAML" all take it as it is. Change the lines
# marked CHANGE; docs/guides/install.md says what to put on each box.
#
# (The repository's own docker-compose.yml builds from source instead.)
services:
  leyla:
    image: tropicalthink/leyla:latest
    container_name: leyla
    restart: unless-stopped
    # Leyla is PID 1 without this; init reaps a database backend whose
    # parent was killed. The grace period is Leyla's drain plus the
    # database's shutdown checkpoint.
    init: true
    stop_grace_period: 2m
    environment:
      # CHANGE: the user and group that own your media (`id <you>` on the
      # box's command line; Synology and QNAP accounts are 1000-something
      # and group 100). Leyla runs as this account.
      PUID: "1026"
      PGID: "100"
      LEYLA__PLAYBACK__DEMAND_SCRATCH_DIR: /run/leyla-playback
    ports:
      - "10001:10001"
    volumes:
      # CHANGE: a folder for Leyla's database, artwork and downloads. An SSD
      # volume if the box has one.
      - /volume1/docker/leyla/data:/app/data
      # CHANGE: plugins installed from Leyla's store.
      - /volume1/docker/leyla/plugins:/app/plugins
      # CHANGE: your films and shows, read-only. Mount several folders under
      # /media if they live on different shares (/media/films, /media/tv).
      - /volume1/video:/media:ro
    # Playback scratch: in memory, bounded, inside the memory limit below.
    tmpfs:
      - /run/leyla-playback:rw,nosuid,nodev,noexec,size=1g,mode=0700
    # A ceiling, not a reservation.
    mem_limit: 4g
    # Hardware transcoding with Intel Quick Sync or AMD (VAAPI), on boxes
    # that have /dev/dri (most Intel Synology "+" models, QNAP, TerraMaster,
    # unRAID, an Intel mini PC). Uncomment it on such a box; Leyla joins the
    # device's group itself. Leave it out on a box without /dev/dri, or the
    # container will not start.
    # devices:
    #   - /dev/dri:/dev/dri

Hardware transcoding

Leyla tests each encoder on the machine it runs on, for the kinds of video it will really be asked to convert, and uses only what passes. Everything else falls back to the CPU.