Installation

Dispatcharr can be installed using Docker on various platforms, including Windows, macOS, Proxmox, and Unraid. This guide provides detailed instructions for each method.

Prerequisites

Ensure Docker and Docker Compose are installed on your platform.

• Docker Desktop for Windows
• Docker Desktop for Mac
• Docker on Linux
• Docker on Proxmox (LXC)
• Docker on Unraid

---

Docker Compose

Dispatcharr is deployed using the following docker-compose.yml:

services:
  dispatcharr:
    # build:
    #   context: .
    #   dockerfile: Dockerfile
    image: ghcr.io/dispatcharr/dispatcharr:latest
    restart: unless-stopped
    container_name: dispatcharr
    ports:
      - 9191:9191
    volumes:
      - dispatcharr_data:/data
    environment:
      - DISPATCHARR_ENV=aio
      - REDIS_HOST=localhost
      - CELERY_BROKER_URL=redis://localhost:6379/0
      - DISPATCHARR_LOG_LEVEL=info
      # Legacy CPU Support (Optional)
      # Uncomment to enable legacy NumPy build for older CPUs (circa 2009)
      # that lack support for newer baseline CPU features
      #- USE_LEGACY_NUMPY=true
      # Process Priority Configuration (Optional)
      # Lower values = higher priority. Range: -20 (highest) to 19 (lowest)
      # Negative values require cap_add: SYS_NICE (uncomment below)
      #- UWSGI_NICE_LEVEL=-5   # uWSGI/FFmpeg/Streaming (default: 0, recommended: -5 for high priority)
      #- CELERY_NICE_LEVEL=5   # Celery/EPG/Background tasks (default: 5, low priority)
    #
    # Uncomment to enable high priority for streaming (required if UWSGI_NICE_LEVEL < 0)
    #cap_add:
    #  - SYS_NICE
    # Optional for hardware acceleration
    #devices:
    #  - /dev/dri:/dev/dri  # For Intel/AMD GPU acceleration (VA-API)
    # Uncomment the following lines for NVIDIA GPU support
    # NVidia GPU support (requires NVIDIA Container Toolkit)
    #deploy:
    #  resources:
    #      reservations:
    #          devices:
    #              - driver: nvidia
    #                count: all
    #                capabilities: [gpu]


volumes:
  dispatcharr_data:

---

Installation Steps

Windows Docker

1. Install and open Docker Desktop.
2. Create a directory, e.g., C:\Dispatcharr, and inside it create a docker-compose.yml with the provided content.
3. Open a PowerShell or Command Prompt window in this directory.

4. Start Dispatcharr with:

   docker compose up -d
   

---

macOS Docker

1. Install and start Docker Desktop.
2. Create a directory for Dispatcharr, e.g., ~/Dispatcharr.
3. Create a docker-compose.yml file with the provided content.

4. Launch Terminal and navigate to your directory:

   cd ~/Dispatcharr
   

5. Run the container:

   docker compose up -d
   

---

Linux Docker

Warning

Some distros use outdated versions of Docker so it is recommended to install directly from Docker

Install Docker using the official instructions, such as those for Ubuntu

Ubuntu example

1. Uninstall old versions.

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

2. Setup Dockers own apt repository for up-to-date versions.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get 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:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

3. Install Docker.

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

1. Create and navigate to your Dispatcharr directory.

   mkdir ~/dispatcharr && cd ~/dispatcharr
   

2. Add your own docker-compose.yml or use the provided example.

3. Launch Dispatcharr:

   docker compose up -d
   

Note

If you wish to use the docker compose commands without sudo you may need to follow Dockers official guide here.

---

Proxmox

1. Create an Ubuntu LXC container or VM with Docker and Docker Compose installed.

   apt install docker.io docker-compose -y
   

2. Create and navigate to your Dispatcharr directory:

   mkdir ~/dispatcharr && cd ~/dispatcharr
   

3. Add your docker-compose.yml.

4. Launch Dispatcharr:

   docker compose up -d
   

---

Unraid

1. Select the "Apps" tab of your Unraid server
2. Search "Dispatcharr" and Select Install
3. Leave the defaults unless you need to change them

---

Modular Deployment

By default, Dispatcharr runs in all-in-one (AIO) mode with Redis and PostgreSQL bundled inside a single container. Modular deployment separates these into individual containers, giving you control over database versions, resource allocation, and connection security.

Note

Modular deployment is optional. AIO mode works for most users. Consider modular deployment if you need TLS-encrypted database connections, want to use existing external Redis or PostgreSQL instances, or require independent scaling of services.

Modular Docker Compose

# Dispatcharr - Modular Deployment Configuration
# This compose file runs Dispatcharr in modular mode with separate containers
# for web, celery workers, PostgreSQL database, and Redis cache.

services:
  # ============================================================================
  # Web Service
  # ============================================================================
  web:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr_web
    restart: unless-stopped
    ports:
      - 9191:9191
    volumes:
      - ./data:/data
      #- ./certs:/certs:ro  # TLS certificates (optional)
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    extra_hosts:
      - "host.docker.internal:host-gateway"

    # --- Environment Configuration ---
    environment:
      # Deployment Mode
      - DISPATCHARR_ENV=modular

      # PostgreSQL Connection
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432
      - POSTGRES_DB=dispatcharr
      - POSTGRES_USER=dispatch
      - POSTGRES_PASSWORD=secret
      # PostgreSQL TLS (optional) — mount certs via the volume above
      #- POSTGRES_SSL=true                             # required to enable TLS
      #- POSTGRES_SSL_MODE=verify-full                 # optional: verify-full (default) | verify-ca | require
      #- POSTGRES_SSL_CA_CERT=/certs/postgres/ca.crt   # optional: CA cert to verify the server
      #- POSTGRES_SSL_CERT=/certs/postgres/client.crt  # optional: client cert (only if server requires client auth)
      #- POSTGRES_SSL_KEY=/certs/postgres/client.key   # optional: client key  (only if server requires client auth)

      # Redis Connection
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      # Redis Authentication (Optional)
      # Uncomment and set if your Redis requires authentication:
      #- REDIS_PASSWORD=your_strong_redis_password
      #- REDIS_USER=your_redis_username  # For Redis 6+ ACL - see Redis service below
      # Redis TLS (optional) — mount certs via the volume above
      #- REDIS_SSL=true                                # required to enable TLS
      #- REDIS_SSL_VERIFY=true                         # optional: set false for self-signed certs without a CA
      #- REDIS_SSL_CA_CERT=/certs/redis/ca.crt         # optional: CA cert to verify the server
      #- REDIS_SSL_CERT=/certs/redis/client.crt        # optional: client cert (only if server requires client auth)
      #- REDIS_SSL_KEY=/certs/redis/client.key         # optional: client key  (only if server requires client auth)

      # Logging
      - DISPATCHARR_LOG_LEVEL=info

      # Legacy CPU Support (Optional)
      # Uncomment to enable legacy NumPy build for older CPUs (circa 2009)
      # that lack support for newer baseline CPU features:
      #- USE_LEGACY_NUMPY=true

      # Process Priority Configuration (Optional)
      # Lower values = higher priority. Range: -20 (highest) to 19 (lowest)
      # Negative values require cap_add: SYS_NICE (see below)
      #- UWSGI_NICE_LEVEL=-5   # uWSGI/FFmpeg/Streaming (default: 0, recommended: -5 for high priority)

    # --- Advanced Configuration ---
    # Uncomment to enable high priority for streaming (required if UWSGI_NICE_LEVEL < 0)
    #cap_add:
    #  - SYS_NICE

    # --- Hardware Acceleration (Optional) ---
    # Uncomment for GPU access (transcoding acceleration)
    #group_add:
    #  - video
    #  #- render  # Uncomment if your GPU requires it
    #devices:
    #  - /dev/dri:/dev/dri  # For Intel/AMD GPU acceleration (VA-API)

    # NVIDIA GPU Support (requires NVIDIA Container Toolkit)
    # Uncomment the following lines for NVIDIA GPU support
    #deploy:
    #  resources:
    #    reservations:
    #      devices:
    #        - driver: nvidia
    #          count: all
    #          capabilities: [gpu]

  # ============================================================================
  # Celery Service - Background task worker
  # ============================================================================
  celery:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr_celery
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
      web:
        condition: service_started
    volumes:
      - ./data:/data
      #- ./certs:/certs:ro  # TLS certificates (optional)
    extra_hosts:
      - "host.docker.internal:host-gateway"
    entrypoint: ["/app/docker/entrypoint.celery.sh"]

    # --- Environment Configuration ---
    environment:
      # Deployment Mode
      - DISPATCHARR_ENV=modular

      # Internal Service Communication
      # Must match the web service port for DVR recording and internal API calls
      - DISPATCHARR_PORT=9191

      # PostgreSQL — must match web service settings
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432
      - POSTGRES_DB=dispatcharr
      - POSTGRES_USER=dispatch
      - POSTGRES_PASSWORD=secret
      # PostgreSQL TLS — must match web service
      #- POSTGRES_SSL=true
      #- POSTGRES_SSL_MODE=verify-full
      #- POSTGRES_SSL_CA_CERT=/certs/postgres/ca.crt
      #- POSTGRES_SSL_CERT=/certs/postgres/client.crt
      #- POSTGRES_SSL_KEY=/certs/postgres/client.key

      # Redis — must match web service settings
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      #- REDIS_PASSWORD=your_strong_redis_password
      #- REDIS_USER=your_redis_username
      # Redis TLS — must match web service
      #- REDIS_SSL=true
      #- REDIS_SSL_VERIFY=true
      #- REDIS_SSL_CA_CERT=/certs/redis/ca.crt
      #- REDIS_SSL_CERT=/certs/redis/client.crt
      #- REDIS_SSL_KEY=/certs/redis/client.key

      # Logging
      - DISPATCHARR_LOG_LEVEL=info

      # Process Priority Configuration (Optional)
      #- CELERY_NICE_LEVEL=5  # Celery/EPG/Background tasks (default: 5, low priority; Range: -20 to 19)

      # Legacy CPU Support (Optional)
      # Uncomment to enable legacy NumPy build for older CPUs (circa 2009)
      # that lack support for newer baseline CPU features:
      #- USE_LEGACY_NUMPY=true

      # Django Configuration
      - DJANGO_SETTINGS_MODULE=dispatcharr.settings
      - PYTHONUNBUFFERED=1

    # --- Advanced Configuration ---
    # Uncomment to enable high priority for Celery (required if CELERY_NICE_LEVEL < 0)
    #cap_add:
    #  - SYS_NICE

  # ============================================================================
  # PostgreSQL
  # ============================================================================
  db:
    image: postgres:17
    container_name: dispatcharr_db
    restart: unless-stopped
    ports:
      - "5436:5432"
    environment:
      - POSTGRES_DB=dispatcharr
      - POSTGRES_USER=dispatch
      - POSTGRES_PASSWORD=secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dispatch -d dispatcharr"]
      interval: 5s
      timeout: 5s
      retries: 5

  # ============================================================================
  # Redis
  # ============================================================================
  redis:
    image: redis:latest
    container_name: dispatcharr_redis
    restart: unless-stopped

    # --- Authentication Configuration (Optional) ---
    # By default, Redis runs without authentication.
    # Choose ONE of the following options if authentication is required:

    # Option 1: Password-only authentication (Redis <6 or default user)
    #command: ["redis-server", "--requirepass", "your_strong_redis_password"]

    # Option 2: Redis 6+ ACL with username + password (requires custom config file - see Redis documentation for configuration)
    #command: ["redis-server", "/etc/redis/redis.conf"]
    #volumes:
    #  - ./redis.conf:/etc/redis/redis.conf:ro

    # --- Health Check Configuration ---
    healthcheck:
      # Default: No authentication
      test: ["CMD", "redis-cli", "ping"]

      # If using Option 1 (password-only), uncomment this instead:
      #test: ["CMD", "redis-cli", "-a", "your_strong_redis_password", "ping"]

      # If using Option 2 (Redis 6+ ACL), uncomment this instead:
      #test: ["CMD", "redis-cli", "--user", "your_redis_username", "-a", "your_strong_redis_password", "ping"]

      interval: 5s
      timeout: 5s
      retries: 5

# ==============================================================================
# Volumes
# ==============================================================================
volumes:
  postgres_data:

Key Differences from AIO

• DISPATCHARR_ENV=modular replaces DISPATCHARR_ENV=aio
• PostgreSQL and Redis run as separate containers with their own health checks
• The Celery worker runs in a dedicated container with its own entrypoint
• Environment variables for PostgreSQL and Redis must match across the web and celery services
• TLS encryption for database connections is only available in modular mode

TLS Configuration

Modular deployments support TLS encryption for connections between Dispatcharr and external Redis/PostgreSQL services. See Connection Security in the Advanced section for configuration details.

---

Accessing Dispatcharr

Open your web browser and navigate to:

http://localhost:9191

Replace localhost with your server's IP address if accessing remotely.