🎬 The Ultimate Dispatcharr Setup Guide: From Zero to Hero

Welcome to the complete, step-by-step guide to installing Dispatcharr.

We will be using the All-In-One (AIO) method, which is the simplest and most stable way to start.

🎥 Video Walkthrough

You can follow along with this video tutorial:
https://www.youtube.com/watch?v=0yYNIABE0lw

📺 Chapter 0: What is Dispatcharr?

Dispatcharr is an open-source powerhouse for managing IPTV streams and EPG data with elegance and control. Think of it as the **arr* family’s IPTV cousin — simple, smart, and designed for streamers who want reliability and flexibility.

🛠️ Chapter 1: Prepare Your Linux System

Before we install Dispatcharr, we need the "engine" that runs it: Docker. We will use the official Docker repository method for maximum stability.

1.1 Uninstall Old Versions

To avoid conflicts, remove any old versions of Docker:

1
2

sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)

1.2 Set Up the Repository

First, update your package list and install tools to allow apt to use a repository over HTTPS:

1
2
3
4
5
6

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Add the repository to Apt sources:

1
2
3
4
5
6
7
8
9
10

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

1.3 Install Docker Engine

Install the latest version of Docker and its plugins:

1
2

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

1.4 Manage Docker as a Non-Root User

This allows you to run Docker commands without typing sudo every time:

1
2
3
4

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

Important: Log out and log back in so that your group membership is re-evaluated.

📁 Chapter 2: Create the Nest

We need a place to store Dispatcharr's data so your settings aren't lost when you update.

1. Go to your Home directory and create the folder:

1
2
3
4

cd ~
mkdir -p dispatcharr/data
cd dispatcharr

📝 Chapter 3: The Secret Sauce (Config File)

We are going to create a docker-compose.yml file. This is the "instruction manual" for Docker.

1. Create and edit the file:

1
2

nano docker-compose.yml

2. Copy and paste the entire block below:
   (Based on the official AIO configuration for simplicity):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

services:
  dispatcharr:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr
    restart: unless-stopped
    ports:
      - 9191:9191
    volumes:
      - ./data:/data
    environment:
      - DISPATCHARR_ENV=aio
      - REDIS_HOST=localhost
      - CELERY_BROKER_URL=redis://localhost:6379/0
      - DISPATCHARR_LOG_LEVEL=info
      - UWSGI_NICE_LEVEL=-5
      - CELERY_NICE_LEVEL=5
      - TZ=UTC # Change this to your timezone (e.g., America/New_York)

    cap_add:
      - SYS_NICE

    devices:
      - /dev/dri:/dev/dri

3. Save and Exit: Press CTRL + X, then Y, then Enter.

🚀 Chapter 4: Liftoff!

Now we tell Docker to read that manual and start the engine.

1. Start the container:

1
2

docker compose up -d

2. Check if it's running:

1
2

docker ps | grep "dispatcharr"

If you see dispatcharr with a status of "Up", you are successful.

🌐 Chapter 5: The Web Dashboard

Now we leave the terminal and enter the web interface.

1. Open your browser and type:
   http://YOUR-SERVER-IP:9191
   (Example: http://192.168.1.50:9191)
   (Find your IP address using the hostname -I command)
2. Create Your Admin Account:
   The initial superuser creation page features a polished design with a logo and welcome message.

• Email: Enter your email address. (Optional)
• Password: Choose a strong password.

📺 Chapter 6: Adding Your First Stream

1. M3U Playlists: Navigate to Playlists -> M3U Playlists to add your provider's stream URL.
2. EPG Setup: Go to EPG to add your program guide link.
3. Proxy Magic: Dispatcharr will now optimize these streams for you.

⚙️ Chapter 7: Connecting Your Players

1. Get your Link: Hover over the M3U button on the top bar.
2. M3U Link: Copy the generated URL.
3. Play: Paste this into apps like Tivimate or OTT Navigator.

🛠️ Chapter 8: Pro-Tips & Troubleshooting

• Update Dispatcharr: Run docker compose pull then docker compose up -d.
• Backup: Dispatcharr includes an automated configuration backup system with scheduled retention.
• Logs: If you run into issues, check logs with docker logs -f dispatcharr.