How to Install ErsatzTV Legacy on Docker or Bare Metal

ErsatzTV Legacy is a .NET 10 web application that runs on Linux, Windows, and macOS. The recommended and easiest installation method is Docker, which bundles FFmpeg and all native dependencies in a single container image. For bare-metal or VM installs, you can download a self-contained binary release and run it directly, provided FFmpeg is available on your system.

Prerequisites

Docker (Recommended)
Binary (Linux / Windows / macOS)

Docker Engine 20.10 or newer (or Docker Desktop on Windows/macOS)
Docker Compose v2 plugin (usually bundled with Docker Desktop or the docker-compose-plugin package)
No separate .NET or FFmpeg installation required — the official image is built on top of ghcr.io/ersatztv/ersatztv-ffmpeg and includes a custom FFmpeg 7.1.1 build along with the .NET 10 ASP.NET Core runtime.

.NET 10 ASP.NET Core Runtime — install from https://dotnet.microsoft.com/download/dotnet/10.0
FFmpeg 7.x — must be installed and either on your system PATH or configured inside ErsatzTV Legacy’s FFmpeg settings
- macOS users: the standard Homebrew ffmpeg formula may be missing required filters; install ffmpeg@7 or ffmpeg-full instead
Python 3 — required only if you plan to use Scripted Schedules

Installation

Docker
Binary

The official Docker image is published at ghcr.io/ersatztv/ersatztv and is rebuilt for each release. It targets linux/amd64 and includes FFmpeg, Python 3, and the etv_client Python package for scripted schedules.

Create a docker-compose.yml file

Create a directory for your ErsatzTV Legacy configuration and save the following docker-compose.yml inside it:

services:
    ersatztv:
        image: ghcr.io/ersatztv/ersatztv:latest
        environment:
            TZ: America/Chicago
        ports:
            - "8409:8409"
        volumes:
            - ersatztv:/config
        tmpfs:
            - /transcode

volumes:
    ersatztv:

Set TZ to your local timezone (e.g. Europe/London, Asia/Tokyo) so that schedule times and EPG data are displayed correctly. A full list of valid timezone strings can be found in the IANA Time Zone Database.

Mount your media (optional but recommended)

Add your media paths as read-only bind mounts inside the volumes: section of your docker-compose.yml:

volumes:
    - ersatztv:/config
    - /mnt/media/movies:/media/movies:ro
    - /mnt/media/tv:/media/tv:ro

The paths inside the container (e.g. /media/movies) are what you will enter when configuring a Local library in the ErsatzTV Legacy UI.

Start the container

From the directory containing your docker-compose.yml, run:

docker compose up -d

Docker will pull the ghcr.io/ersatztv/ersatztv:latest image on the first run. This may take a minute or two depending on your connection speed.

Verify the server is running

Open your browser and navigate to:

http://localhost:8409

You should see the ErsatzTV Legacy web interface. The server log is also accessible from within the UI under Settings → Logs.

Binary releases are published on the ErsatzTV Legacy GitHub Releases page. Each release includes builds for:

linux-x64
win-x64
osx-x64
osx-arm64 (Apple Silicon)

Download the binary for your platform

Visit the releases page and download the archive for your operating system. Extract it to a permanent directory, for example:

# Linux example
mkdir -p ~/ersatztv
tar -xzf ErsatzTV-linux-x64.tar.gz -C ~/ersatztv

Install the .NET 10 ASP.NET Core Runtime

Install the .NET 10 runtime from Microsoft’s official download page:

# Example: Ubuntu / Debian
sudo apt-get install -y dotnet-runtime-10.0

For other distributions and operating systems, follow the instructions at https://dotnet.microsoft.com/download/dotnet/10.0.

Ensure FFmpeg is available

ErsatzTV Legacy requires FFmpeg 7.x. Confirm it is installed and on your PATH:

ffmpeg -version

On macOS, the standard brew install ffmpeg formula may be missing filters required by ErsatzTV Legacy. Install ffmpeg@7 or ffmpeg-full via Homebrew instead:

brew install ffmpeg@7

Run ErsatzTV Legacy

Start the server by executing the binary directly:

# Linux / macOS
cd ~/ersatztv
./ErsatzTV

# Windows (PowerShell)
cd C:\ersatztv
.\ErsatzTV.exe

The first launch will create the configuration database and log files alongside the executable. The server listens on port 8409 by default.

Configuration

Default Port

ErsatzTV Legacy binds to port 8409 for both the web UI and the IPTV/streaming endpoints. This port is used for all HTTP access: the management UI, the REST API, and the M3U, XMLTV, and HDHomeRun streaming endpoints.

Config Directory

Installation	Config Location
Docker	`/config` (inside the container, backed by a named volume or bind mount)
Binary	Same directory as the `ErsatzTV` executable

The config directory holds the SQLite database (ersatztv.sqlite3), logs, extracted artwork cache, and the next/ folder for Next engine channel configs. Override the path with the ETV_CONFIG_FOLDER environment variable.

Transcode Directory

Temporary HLS segment files are written to a transcode directory. In Docker, this is mapped to a tmpfs mount at /transcode for performance. Override with ETV_TRANSCODE_FOLDER.

Environment Variables Reference

Variable	Default	Description
`TZ`	System TZ	Container timezone (e.g. `America/New_York`)
`ETV_CONFIG_FOLDER`	`/config` (Docker)	Override for the config/database folder
`ETV_TRANSCODE_FOLDER`	`/transcode` (Docker)	Override for HLS segment scratch space
`ETV_INSTANCE_ID`	(unset)	Disambiguates EPG data from multiple ErsatzTV instances
`TRAKT__CLIENTID`	(unset)	Your Trakt API Client ID for Trakt list integration

Single-Instance Enforcement

ErsatzTV Legacy uses a named system mutex (ErsatzTV.Singleton.74360cd8985c4d1fb6bc9e81887206fe) to ensure only one instance runs per host. If you attempt to start a second instance, the process will print Another instance of ErsatztTV is already running. and exit immediately. Run multiple channels through a single server instance rather than multiple processes.

Hardware Acceleration (Docker)

GPU transcoding requires additional Docker flags beyond the base docker-compose.yml. ErsatzTV Legacy supports NVENC (NVIDIA), VAAPI (Intel/AMD), QSV (Intel), AMF (AMD on Windows), VideoToolbox (macOS), and RKMPP (Rockchip). Use the appropriate Compose file as a starting point:

NVIDIA — requires the NVIDIA Container Toolkit on the host. Use the docker-compose.nvidia.yml variant shown in the Docker tab above, which sets NVIDIA_VISIBLE_DEVICES, NVIDIA_DRIVER_CAPABILITIES, and the deploy.resources.reservations.devices block.
VAAPI (Intel / AMD) — pass the render device into the container. Use the docker-compose.vaapi.yml variant, which maps /dev/dri/renderD128 from host to container. Adjust the device path if your system uses a different render node.

After starting the container with GPU access, configure the hardware accelerator inside Settings → FFmpeg Profiles in the ErsatzTV Legacy UI.

Hardware transcoding profiles must be explicitly assigned to channels. A channel configured with a software-only FFmpeg profile will not use GPU acceleration even if the Docker container has GPU access.

Upgrading

To upgrade to a newer release using Docker, pull the latest image and recreate the container:

docker compose pull
docker compose up -d

ErsatzTV Legacy will automatically migrate its SQLite database to the new schema on startup. Always back up your /config volume before upgrading major versions.

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

How to Install ErsatzTV Legacy on Docker or Bare Metal

Prerequisites

Installation

Configuration

Default Port

Config Directory

Transcode Directory

Environment Variables Reference

Single-Instance Enforcement

Hardware Acceleration (Docker)

Upgrading

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

Documentation Index

​Prerequisites

​Installation

​Configuration

​Default Port

​Config Directory

​Transcode Directory

​Environment Variables Reference

​Single-Instance Enforcement

​Hardware Acceleration (Docker)

​Upgrading

Build docs developers (and LLMs) love

Prerequisites

Installation

Configuration

Default Port

Config Directory

Transcode Directory

Environment Variables Reference

Single-Instance Enforcement

Hardware Acceleration (Docker)

Upgrading