How to Install Mirakurun Using Docker – Step by Step

Why Use Docker for Mirakurun?

Docker is the official recommended method for running Mirakurun. It handles all shared library dependencies automatically, provides a clean isolated runtime environment, and makes updates as simple as pulling a new image. The Mirakurun team actively maintains the Docker image on Docker Hub.

Requirements Before You Start

A Linux machine (Ubuntu, Debian, or Raspberry Pi OS recommended)
A compatible TV tuner (DVB driver or chardev based)
Docker and Docker Compose installed
Basic comfort with the Linux terminal

Step 1 — Install Docker on Linux

If Docker is not yet installed on your machine, use the official installer script:

curl -sSL https://get.docker.com/ | CHANNEL=stable sh

Step 2 — Pull the Mirakurun Docker Image

Download the official Mirakurun image from Docker Hub:

docker pull chinachu/mirakurun

Step 3 — Run the Automated Setup Wizard

For DVB-supported tuners, Mirakurun can auto-detect your hardware and write config files automatically. Run the setup command:

docker compose run --rm -e SETUP=true mirakurun

The wizard will scan for connected tuners and generate tuners.yml and channels.yml for you.

Step 4 — Start Mirakurun

Once setup is complete, start the Mirakurun container in detached mode:

docker compose up -d mirakurun

Step 5 — Verify It Is Running

Open your browser and navigate to the Mirakurun admin UI:

http://YOUR_SERVER_IP:40772/

If the admin panel loads and shows your tuner as connected, Mirakurun is running correctly.

Step 6 — Access the Swagger API Explorer

To explore and test the API interactively, open the Swagger UI:

http://YOUR_SERVER_IP:40772/api/debug

Frequently Asked Questions

What if my tuner is not detected by the setup wizard?▼

The auto-detection only works for DVB driver tuners. If you are using a chardev tuner, you need to edit tuners.yml manually and provide a startup script. See the Tuners.yml guide for details.

Can I run Mirakurun without Docker?▼

Technically yes via npm, but this method is no longer recommended by the Mirakurun team. Docker is the supported and easiest path.

How do I update Mirakurun?▼

Run docker pull chinachu/mirakurun to get the latest image, then docker compose up -d mirakurun to restart with the new version.