Docker Compose Deployment

Deploy Dispatcharr using Docker Compose with options for all-in-one, modular, or development setups

Docker Compose Deployment

Docker Compose provides a declarative way to deploy Dispatcharr with persistent configuration. Choose the deployment mode that fits your needs.

Deployment Modes

Mode	File	Description	Best For
All-in-One	docker-compose.aio.yml	Single container with embedded Redis and SQLite	Quick setup, testing, small deployments
Modular	docker-compose.yml	Separate containers for web, Celery, PostgreSQL, Redis	Production, scalability, granular control
Development	docker-compose.dev.yml	Dev environment with debugging tools	Contributors, plugin developers

All-in-One Deployment (Recommended)

Perfect for most users - everything runs in a single container with minimal configuration.

Setup

1. Create docker-compose.aio.yml

   services:
     dispatcharr:
       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
   
   volumes:
     dispatcharr_data:
   
2. Start the service

   docker compose -f docker-compose.aio.yml up -d
   
3. Access the web interface

   Navigate to http://localhost:9191

Hardware Acceleration (AIO)

Intel/AMD GPU

services:
  dispatcharr:
    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
    devices:
      - /dev/dri:/dev/dri  # VA-API support

volumes:
  dispatcharr_data:

Process Priority (AIO)

Optimize streaming performance with priority configuration:

services:
  dispatcharr:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    restart: unless-stopped
    container_name: dispatcharr
    cap_add:
      - SYS_NICE
    ports:
      - 9191:9191
    volumes:
      - dispatcharr_data:/data
    environment:
      - DISPATCHARR_ENV=aio
      - REDIS_HOST=localhost
      - CELERY_BROKER_URL=redis://localhost:6379/0
      - UWSGI_NICE_LEVEL=-5   # High priority for streaming
      - CELERY_NICE_LEVEL=5   # Low priority for background tasks

volumes:
  dispatcharr_data:

The SYS_NICE capability is required when using negative nice values.

Modular Deployment

Separate containers for web, Celery workers, PostgreSQL, and Redis. Ideal for production deployments requiring scalability and fine-grained control.

Setup

1. Create docker-compose.yml

   services:
     web:
       image: ghcr.io/dispatcharr/dispatcharr:latest
       container_name: dispatcharr_web
       restart: unless-stopped
       ports:
         - 9191:9191
       volumes:
         - ./data:/data
       depends_on:
         - db
         - redis
       environment:
         - DISPATCHARR_ENV=modular
         - POSTGRES_HOST=db
         - POSTGRES_PORT=5432
         - POSTGRES_DB=dispatcharr
         - POSTGRES_USER=dispatch
         - POSTGRES_PASSWORD=secret
         - REDIS_HOST=redis
         - REDIS_PORT=6379
         - DISPATCHARR_LOG_LEVEL=info
   
     celery:
       image: ghcr.io/dispatcharr/dispatcharr:latest
       container_name: dispatcharr_celery
       restart: unless-stopped
       depends_on:
         - db
         - redis
         - web
       volumes:
         - ./data:/data
       extra_hosts:
         - "host.docker.internal:host-gateway"
       entrypoint: ["/app/docker/entrypoint.celery.sh"]
       environment:
         - DISPATCHARR_ENV=modular
         - POSTGRES_HOST=db
         - POSTGRES_PORT=5432
         - POSTGRES_DB=dispatcharr
         - POSTGRES_USER=dispatch
         - POSTGRES_PASSWORD=secret
         - REDIS_HOST=redis
         - REDIS_PORT=6379
         - DISPATCHARR_LOG_LEVEL=info
         - DJANGO_SETTINGS_MODULE=dispatcharr.settings
         - PYTHONUNBUFFERED=1
   
     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:
       image: redis:latest
       container_name: dispatcharr_redis
       restart: unless-stopped
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 5s
         retries: 5
   
   volumes:
     postgres_data:
   
2. Start all services

   docker compose up -d
   
3. Verify services are running

   docker compose ps
   

Security Notice: Change the default PostgreSQL password (POSTGRES_PASSWORD=secret) before deploying to production!

Redis Authentication (Modular)

For production environments, enable Redis authentication:

Password-only (Redis <6)

services:
  redis:
    image: redis:latest
    container_name: dispatcharr_redis
    restart: unless-stopped
    command: ["redis-server", "--requirepass", "your_strong_redis_password"]
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "your_strong_redis_password", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  web:
    environment:
      - REDIS_HOST=redis
      - REDIS_PASSWORD=your_strong_redis_password

  celery:
    environment:
      - REDIS_HOST=redis
      - REDIS_PASSWORD=your_strong_redis_password

Hardware Acceleration (Modular)

Add GPU support to the web service:

services:
  web:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr_web
    restart: unless-stopped
    ports:
      - 9191:9191
    volumes:
      - ./data:/data
    depends_on:
      - db
      - redis
    group_add:
      - video
    devices:
      - /dev/dri:/dev/dri
    environment:
      - DISPATCHARR_ENV=modular
      # ... other environment variables

Development Deployment

For developers contributing to Dispatcharr or building plugins.

Setup

1. Create docker-compose.dev.yml

   services:
     dispatcharr:
       image: ghcr.io/dispatcharr/dispatcharr:base
       container_name: dispatcharr_dev
       restart: unless-stopped
       ports:
         - 5656:5656  # Debug port
         - 9191:9191  # Web interface
         - 8001:8001  # WebSocket port
       volumes:
         - ../:/app
         - ./data:/data
       environment:
         - DISPATCHARR_ENV=dev
         - REDIS_HOST=localhost
         - CELERY_BROKER_URL=redis://localhost:6379/0
         - DISPATCHARR_LOG_LEVEL=debug
   
     pgadmin:
       image: dpage/pgadmin4
       restart: unless-stopped
       environment:
         PGADMIN_DEFAULT_EMAIL: [e-mail]
         PGADMIN_DEFAULT_PASSWORD: admin
       volumes:
         - dispatcharr_dev_pgadmin:/var/lib/pgadmin
       ports:
         - 8082:80
   
     redis-commander:
       image: rediscommander/redis-commander:latest
       restart: unless-stopped
       environment:
         - REDIS_HOSTS=dispatcharr:dispatcharr:6379:0
         - TRUST_PROXY=true
         - ADDRESS=0.0.0.0
       ports:
         - 8081:8081
   
   volumes:
     dispatcharr_dev_pgadmin:
   
2. Start development environment

   docker compose -f docker-compose.dev.yml up -d
   
3. Access development tools

   • Web Interface: http://localhost:9191
   • pgAdmin: http://localhost:8082 ([e-mail] / admin)
   • Redis Commander: http://localhost:8081

The development environment uses the base image and mounts your local code directory for live development.

Upgrading

1. Pull the latest images

   docker compose pull
   
2. Stop and recreate containers

   docker compose down
   docker compose up -d
   
3. Verify upgrade

   docker compose logs -f
   

Always backup your data before upgrading:

# For AIO
docker run --rm -v dispatcharr_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/dispatcharr-backup.tar.gz /data

# For Modular
docker compose exec db pg_dump -U dispatch dispatcharr > backup.sql
cp -r ./data ./data.backup

Common Operations

View Logs

All services

docker compose logs -f

Restart Services

All services

docker compose restart

Database Management (Modular)

Backup database

docker compose exec db pg_dump -U dispatch dispatcharr > backup-$(date +%Y%m%d).sql

Troubleshooting

Services Won’t Start

# Check service status
docker compose ps

# View detailed logs
docker compose logs

# Recreate containers
docker compose down
docker compose up -d

Database Connection Issues (Modular)

# Check database health
docker compose exec db pg_isready -U dispatch -d dispatcharr

# Verify network connectivity
docker compose exec web ping db

# Check environment variables
docker compose exec web env | grep POSTGRES

Redis Connection Issues

# Test Redis connectivity
docker compose exec redis redis-cli ping

# Check Redis logs
docker compose logs redis

# Verify environment variables
docker compose exec web env | grep REDIS

Reset Everything

This will delete all data! Back up first if needed.

# Stop and remove containers, networks, volumes
docker compose down -v

# Start fresh
docker compose up -d

Next Steps

• Configure your first M3U source
• Set up EPG data
• Create stream profiles
• Enable HDHomeRun emulation