Bare Metal Installation

Install Dispatcharr directly on your server without Docker. This method is for advanced users who need direct system integration.

Important Notices:

Only Debian-based distributions are supported (Ubuntu, Debian, etc.)
NOT RECOMMENDED for your primary machine - use a VM or LXC container
NO OFFICIAL SUPPORT - Docker is the only officially supported deployment method
This installation method may have unexpected issues

Prerequisites

Debian-based OS (Ubuntu 20.04+, Debian 11+, or similar)
Root/sudo access
At least 2GB RAM
10GB free disk space
Clean system or isolated VM/LXC container

For the best experience, run the installation script in a clean virtual machine or LXC container.

Automated Installation (Debian)

The easiest way to install on Debian-based systems is using the provided installation script.

Download the installation script

wget https://raw.githubusercontent.com/Dispatcharr/Dispatcharr/main/debian_install.sh

Or using curl:

curl -O https://raw.githubusercontent.com/Dispatcharr/Dispatcharr/main/debian_install.sh

Make the script executable

chmod +x debian_install.sh

Run the installation script as root

sudo ./debian_install.sh

The script will:

Display a disclaimer and safety warning
Prompt you to type “I understand” to continue
Install all required system packages
Set up PostgreSQL and Redis
Create a dedicated dispatcharr user
Clone the Dispatcharr repository
Build the frontend and backend
Configure systemd services
Set up Nginx as a reverse proxy

Access the web interface

Once installation completes, the script will display your server IP address. Navigate to http://YOUR_SERVER_IP:9191

What Gets Installed

The installation script sets up the following components:

System Packages

Build Tools: git, curl, wget, build-essential, gcc
Python: python3, python3-dev, python3-venv, python3-pip
Database: PostgreSQL 17
Cache: Redis server
Web Server: Nginx
Media Tools: FFmpeg, Streamlink
Runtime: Node.js 24

Services

Four systemd services are created and enabled:

Service	Description	Port
`dispatcharr.service`	Main web application (Gunicorn)	9191
`dispatcharr-celery.service`	Background task worker	-
`dispatcharr-celerybeat.service`	Task scheduler	-
`dispatcharr-daphne.service`	WebSocket server (ASGI)	8001

Directory Structure

/opt/dispatcharr/          # Application directory
  ├── env/                 # Python virtual environment
  ├── frontend/            # Built frontend assets
  ├── logo_cache/          # Cached channel logos
  ├── media/               # Media files
  └── .env                 # Environment configuration

/data/                     # Data directory
  ├── logos/               # Channel logos
  ├── recordings/          # Stream recordings
  ├── uploads/
  │   ├── m3us/            # Uploaded M3U files
  │   └── epgs/            # Uploaded EPG files
  ├── m3us/                # Processed M3U playlists
  ├── epgs/                # Processed EPG data
  ├── plugins/             # Custom plugins
  └── db/                  # PostgreSQL data (owned by postgres)

Configuration

Default Settings

The installation script uses these default values:

Setting	Value
Application Directory	`/opt/dispatcharr`
Data Directory	`/data`
System User	`dispatcharr`
PostgreSQL Database	`dispatcharr`
PostgreSQL User	`dispatch`
PostgreSQL Password	`secret`
HTTP Port	`9191`
WebSocket Port	`8001`

Security: Change the default PostgreSQL password after installation!

sudo -u postgres psql
ALTER USER dispatch WITH PASSWORD 'new_secure_password';

Then update /opt/dispatcharr/.env and restart services.

Customizing Configuration

Edit the installation script before running to customize:

# Configuration section (around line 45)
DISPATCH_USER="dispatcharr"
DISPATCH_GROUP="dispatcharr"
APP_DIR="/opt/dispatcharr"
DISPATCH_BRANCH="main"
POSTGRES_DB="dispatcharr"
POSTGRES_USER="dispatch"
POSTGRES_PASSWORD="secret"  # Change this!
NGINX_HTTP_PORT="9191"
WEBSOCKET_PORT="8001"

Environment Variables

The script creates /opt/dispatcharr/.env with a secure Django secret key. You can add additional environment variables:

sudo nano /opt/dispatcharr/.env

Common variables:

DJANGO_SECRET_KEY=<auto-generated>
DISPATCHARR_LOG_LEVEL=info
DEBUG=False

After editing, restart services:

sudo systemctl restart dispatcharr dispatcharr-celery dispatcharr-celerybeat dispatcharr-daphne

Managing Services

Service Status

sudo systemctl status dispatcharr dispatcharr-celery dispatcharr-celerybeat dispatcharr-daphne

Start/Stop/Restart

sudo systemctl restart dispatcharr dispatcharr-celery dispatcharr-celerybeat dispatcharr-daphne

View Logs

sudo journalctl -u dispatcharr -f

Upgrading

The installation script supports upgrades. Simply run it again:

Stop services

sudo systemctl stop dispatcharr dispatcharr-celery dispatcharr-celerybeat dispatcharr-daphne

Back up your data

# Backup database
sudo -u postgres pg_dump dispatcharr > ~/dispatcharr-backup-$(date +%Y%m%d).sql

# Backup data directory
sudo tar czf ~/dispatcharr-data-backup-$(date +%Y%m%d).tar.gz /data

# Backup configuration
sudo cp /opt/dispatcharr/.env ~/dispatcharr-env-backup-$(date +%Y%m%d)

Run the installation script again

sudo ./debian_install.sh

The script will:

Detect the existing installation
Pull the latest code from GitHub
Rebuild the frontend
Update Python dependencies
Run database migrations
Restart all services

Verify the upgrade

sudo systemctl status dispatcharr
sudo journalctl -u dispatcharr -n 50

Manual Installation

If you’re using a non-Debian distribution or want full control, follow these manual steps:

Manual installation requires deep knowledge of Linux system administration. The automated script is strongly recommended.

Install system dependencies

Install equivalent packages for your distribution:

Python 3.10+
PostgreSQL 13+
Redis 6+
Node.js 18+
FFmpeg
Nginx
Streamlink

Create user and directories

sudo useradd -m -s /bin/bash dispatcharr
sudo mkdir -p /opt/dispatcharr /data/{logos,recordings,uploads/{m3us,epgs},m3us,epgs,plugins,db}
sudo chown dispatcharr:dispatcharr /opt/dispatcharr /data
sudo chown postgres:postgres /data/db

Set up PostgreSQL

sudo -u postgres createdb dispatcharr
sudo -u postgres createuser dispatch
sudo -u postgres psql -c "ALTER USER dispatch WITH PASSWORD 'secret';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE dispatcharr TO dispatch;"
sudo -u postgres psql -c "ALTER DATABASE dispatcharr OWNER TO dispatch;"

Clone and build Dispatcharr

sudo -u dispatcharr git clone https://github.com/Dispatcharr/Dispatcharr.git /opt/dispatcharr
cd /opt/dispatcharr

# Install UV package manager
sudo -u dispatcharr curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
sudo -u dispatcharr python3 -m venv env
sudo -u dispatcharr env/bin/pip install -q gunicorn

# Install dependencies
sudo -u dispatcharr bash -c 'export UV_PROJECT_ENVIRONMENT=/opt/dispatcharr/env && ~/.local/bin/uv sync --no-dev'

# Build frontend
cd frontend
sudo -u dispatcharr npm install --legacy-peer-deps
sudo -u dispatcharr npm run build

Configure Django

cd /opt/dispatcharr

# Generate secret key
sudo -u dispatcharr bash -c 'echo "DJANGO_SECRET_KEY=$(env/bin/python -c "import secrets; print(secrets.token_urlsafe(64))")" > .env'
sudo -u dispatcharr chmod 600 .env

# Run migrations
sudo -u dispatcharr bash -c 'export POSTGRES_DB=dispatcharr POSTGRES_USER=dispatch POSTGRES_PASSWORD=secret POSTGRES_HOST=localhost && env/bin/python manage.py migrate'
sudo -u dispatcharr bash -c 'export POSTGRES_DB=dispatcharr POSTGRES_USER=dispatch POSTGRES_PASSWORD=secret POSTGRES_HOST=localhost && env/bin/python manage.py collectstatic --noinput'

Create systemd services

Use the service file templates from the debian_install.sh script (lines 284-398) and adapt them for your system paths.

Configure Nginx

Use the Nginx configuration from the script (lines 401-427) and adapt for your setup.

Troubleshooting

Installation Fails

lsb_release -a  # Verify Debian-based OS
python3 --version  # Should be 3.10+

Services Won’t Start

# Check service status
sudo systemctl status dispatcharr

# View detailed logs
sudo journalctl -u dispatcharr -n 100 --no-pager

# Check configuration
sudo -u dispatcharr /opt/dispatcharr/env/bin/python /opt/dispatcharr/manage.py check

# Verify database connection
sudo -u dispatcharr bash -c 'export POSTGRES_DB=dispatcharr POSTGRES_USER=dispatch POSTGRES_PASSWORD=secret POSTGRES_HOST=localhost && /opt/dispatcharr/env/bin/python /opt/dispatcharr/manage.py dbshell'

Database Connection Issues

sudo -u postgres psql -c "SELECT version();"
sudo -u postgres psql -l | grep dispatcharr

Redis Connection Issues

# Test Redis
redis-cli ping

# Check Redis service
sudo systemctl status redis-server

# View Redis logs
sudo journalctl -u redis-server -n 50

Permission Issues

# Fix data directory permissions
sudo chown -R dispatcharr:dispatcharr /data
sudo chown -R postgres:postgres /data/db
sudo chmod +x /data

# Fix application directory permissions
sudo chown -R dispatcharr:dispatcharr /opt/dispatcharr

# Fix log directory permissions
sudo mkdir -p /var/log/dispatcharr
sudo chown dispatcharr:dispatcharr /var/log/dispatcharr

Frontend Not Loading

# Rebuild frontend
sudo -u dispatcharr bash -c 'cd /opt/dispatcharr/frontend && npm install --legacy-peer-deps && npm run build'

# Collect static files
sudo -u dispatcharr bash -c 'export POSTGRES_DB=dispatcharr POSTGRES_USER=dispatch POSTGRES_PASSWORD=secret POSTGRES_HOST=localhost && /opt/dispatcharr/env/bin/python /opt/dispatcharr/manage.py collectstatic --noinput'

# Restart Nginx
sudo systemctl restart nginx

Uninstallation

To completely remove Dispatcharr:

This will permanently delete all Dispatcharr data, including your database, recordings, and configuration!

# Stop and disable services
sudo systemctl stop dispatcharr dispatcharr-celery dispatcharr-celerybeat dispatcharr-daphne
sudo systemctl disable dispatcharr dispatcharr-celery dispatcharr-celerybeat dispatcharr-daphne

# Remove service files
sudo rm /etc/systemd/system/dispatcharr*.service
sudo systemctl daemon-reload

# Remove Nginx configuration
sudo rm /etc/nginx/sites-enabled/dispatcharr.conf
sudo rm /etc/nginx/sites-available/dispatcharr.conf
sudo systemctl restart nginx

# Drop PostgreSQL database and user
sudo -u postgres dropdb dispatcharr
sudo -u postgres dropuser dispatch

# Remove application and data
sudo rm -rf /opt/dispatcharr
sudo rm -rf /data

# Remove user
sudo userdel -r dispatcharr

# Optional: Remove packages (be careful - may be used by other apps)
# sudo apt remove postgresql redis-server nginx

Performance Tuning

Gunicorn Workers

Adjust the number of workers based on your CPU cores:

sudo nano /etc/systemd/system/dispatcharr.service

Change --workers=4 to --workers=<2 * CPU_CORES + 1>:

ExecStart=/opt/dispatcharr/env/bin/gunicorn \
    --workers=8 \
    --worker-class=gevent \
    --timeout=300 \
    --bind unix:/run/dispatcharr/dispatcharr.sock \
    dispatcharr.wsgi:application

Then reload:

sudo systemctl daemon-reload
sudo systemctl restart dispatcharr

PostgreSQL Tuning

For better database performance:

sudo nano /etc/postgresql/*/main/postgresql.conf

Recommended settings for 4GB+ RAM:

shared_buffers = 256MB
effective_cache_size = 1GB
maintenance_work_mem = 64MB
work_mem = 8MB

Restart PostgreSQL:

sudo systemctl restart postgresql

Redis Optimization

sudo nano /etc/redis/redis.conf

Recommended settings:

maxmemory 512mb
maxmemory-policy allkeys-lru

Restart Redis:

sudo systemctl restart redis-server

Getting Started

Core Features

Integrations

Configuration

Advanced

Deployment

Bare Metal Installation

Bare Metal Installation

Prerequisites

Automated Installation (Debian)

What Gets Installed

System Packages

Services

Directory Structure

Configuration

Default Settings

Customizing Configuration

Environment Variables

Managing Services

Service Status

Start/Stop/Restart

View Logs

Upgrading

Manual Installation

Troubleshooting

Installation Fails

Services Won’t Start

Database Connection Issues

Redis Connection Issues

Permission Issues

Frontend Not Loading

Uninstallation

Performance Tuning

Gunicorn Workers

PostgreSQL Tuning

Redis Optimization

Next Steps

Getting Started

Core Features

Integrations

Configuration

Advanced

Deployment

Documentation Index

​Bare Metal Installation

​Prerequisites

​Automated Installation (Debian)

​What Gets Installed

​System Packages

​Services

​Directory Structure

​Configuration

​Default Settings

​Customizing Configuration

​Environment Variables

​Managing Services

​Service Status

​Start/Stop/Restart

​View Logs

​Upgrading

​Manual Installation

​Troubleshooting

​Installation Fails

​Services Won’t Start

​Database Connection Issues

​Redis Connection Issues

​Permission Issues

​Frontend Not Loading

​Uninstallation

​Performance Tuning

​Gunicorn Workers

​PostgreSQL Tuning

​Redis Optimization

​Next Steps

Bare Metal Installation

Prerequisites

Automated Installation (Debian)

What Gets Installed

System Packages

Services

Directory Structure

Configuration

Default Settings

Customizing Configuration

Environment Variables

Managing Services

Service Status

Start/Stop/Restart

View Logs

Upgrading

Manual Installation

Troubleshooting

Installation Fails

Services Won’t Start

Database Connection Issues

Redis Connection Issues

Permission Issues

Frontend Not Loading

Uninstallation

Performance Tuning

Gunicorn Workers

PostgreSQL Tuning

Redis Optimization

Next Steps