Whatbox Logo
Login for certain variables to be updated with your slot's information

Wiki > Dispatcharr

Whatbox has limited support for containers; they may stop working at any time.

Dispatcharr is an IPTV and EPG manager. It combines your M3U playlists and guide data, lets you organize and filter channels, and serves them to Plex, Jellyfin, Emby and IPTV players as an HDHomeRun tuner, an M3U/EPG pair or an Xtream Codes account.

This article runs the official all-in-one container image with rootless Podman. The container includes its own PostgreSQL database, Redis and web server.

13940 was randomly generated for this article; you may use any 5-digit port between 10000 and 32767. Dispatcharr's default port, 9191, can't be used on Whatbox.

Create your admin account in step 7 before you do anything else. Dispatcharr's own setup page doesn't work on Whatbox, so the account is made from SSH.

Installation

  1. Connect to your slot via SSH.

  2. Create the folders for Dispatcharr and its data:

     mkdir -p ~/dispatcharr/data

  3. Create the Compose file:

     nano ~/dispatcharr/compose.yaml

  4. Paste in the following. Change TZ to your time zone so the guide and recordings line up with your local time:

     services:
   dispatcharr:
     image: ghcr.io/dispatcharr/dispatcharr:latest
     container_name: dispatcharr
     restart: unless-stopped
     ports:
       - "127.0.0.1:13940:9191"
     volumes:
       - /home/user/dispatcharr/data:/data
     environment:
       - DISPATCHARR_ENV=aio
       - REDIS_HOST=localhost
       - CELERY_BROKER_URL=redis://localhost:6379/0
       - DISPATCHARR_LOG_LEVEL=info
       - UWSGI_WORKERS=2
       - CELERY_MAX_WORKERS=2
       - TZ=America/Toronto

    Save with Ctrl + S and exit with Ctrl + X.

    127.0.0.1 keeps Dispatcharr private to your slot until your admin account exists. Step 8 opens it up, unless you use a Managed Link instead.

  5. Start Dispatcharr:

     cd ~/dispatcharr && podman-compose up -d

  6. The first start downloads the image (about 3 GB) and sets up the database, which takes a few minutes. Dispatcharr is ready when this prints 200:

     curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:13940/

    If it prints 000, wait a little and run it again. You can read the startup log with podman logs dispatcharr.

  7. Create your admin account. You'll be asked for a username, an email address (you can leave it empty) and a unique password twice (do not reuse your Whatbox password):

     podman exec -it dispatcharr bash -lc "python manage.py createsuperuser"

    A few log lines appear before the first question; that's normal. It prints Superuser created successfully. when it worked.

  8. (Optional) If you plan to use HTTPS only, skip this step and set up HTTPS via Managed Links instead. Otherwise, make Dispatcharr reachable from outside your slot, then recreate the container:

     sed -i 's|"127.0.0.1:13940:9191"|"13940:9191"|' ~/dispatcharr/compose.yaml
 cd ~/dispatcharr && podman-compose down && podman-compose up -d

  9. Visit http://server.whatbox.ca:13940 (or your Managed Link address if you skipped step 8) and log in with the account from step 7.

Configuration

Configure Dispatcharr from its web interface. The Dispatcharr documentation covers every page; start with Getting Started:

  • Playlists and guide data: add your M3U playlists and XMLTV sources under M3U & EPG Manager, then pick the channels you want under Channels.
  • Connecting Plex, Jellyfin or Emby: add Dispatcharr as an HDHomeRun tuner, or use the M3U and EPG links shown on the Channels page. Use the same address you use to open Dispatcharr.
  • Streaming: by default Dispatcharr passes streams through without transcoding. Hardware transcoding isn't available on Whatbox, and every stream counts toward your slot's traffic.
  • Other users: add accounts under Users.

Settings in compose.yaml

Settings for the container itself are environment variables in ~/dispatcharr/compose.yaml. After changing them, recreate the container:

cd ~/dispatcharr && podman-compose down && podman-compose up -d

UWSGI_WORKERS and CELERY_MAX_WORKERS set how many worker processes Dispatcharr runs. The values above are lower than Dispatcharr's defaults to keep memory use down on a shared server; raise them only if the web interface becomes slow with many simultaneous streams.

Files in the data folder

Dispatcharr's database, logs, logos and recordings are kept in ~/dispatcharr/data. Most of these files belong to the container's own user, so your account can't change or delete them directly. Prefix commands with podman unshare to work with them, for example:

podman unshare ls ~/dispatcharr/data/recordings

Automatically Restart (optional)

Rootless containers don't start again by themselves after the server reboots. This script starts Dispatcharr if it isn't running.

  1. Create a restart script:

     touch ~/dispatcharr_restart.cron
 nano -w ~/dispatcharr_restart.cron

  2. Paste in the following:

     #!/bin/bash
 if [ -n "$(podman ps -q --filter name='^dispatcharr$' --filter status=running)" ]
 then
     echo "Dispatcharr is running."
 else
     echo "Dispatcharr is not running, starting Dispatcharr"
     podman start dispatcharr
 fi
 exit

    Save and exit.

  3. Make the script executable:

     chmod +x ~/dispatcharr_restart.cron

  4. Open your crontab:

     EDITOR=nano crontab -e

  5. Add these lines, then save and exit:

     @reboot /home/user/dispatcharr_restart.cron >/dev/null 2>&1
 */5 * * * * /home/user/dispatcharr_restart.cron >/dev/null 2>&1

Stopping Dispatcharr

podman stop dispatcharr

Dispatcharr shuts its database down cleanly before the container exits, which takes a few seconds. Start it again with podman start dispatcharr. podman-compose down also stops it cleanly, and removes the container as well.

Don't stop Dispatcharr while it's starting for the first time or right after an update. It may be moving or upgrading its database then, and interrupting that can damage it.

If you set up automatic restarts, the restart script starts Dispatcharr again within 5 minutes; comment out its crontab lines first to keep it stopped.

  1. On the Manage Links page, click Add a custom app.

  2. Name it dispatcharr, enter port 13940, and open Advanced options to enable WebSockets, which Dispatcharr's interface uses for live updates.

  3. Visit https://dispatcharr.example.box.ca and log in.

  4. Once the link works, make the plain HTTP port private again, and recreate the container:

     sed -i 's|"13940:9191"|"127.0.0.1:13940:9191"|' ~/dispatcharr/compose.yaml
 cd ~/dispatcharr && podman-compose down && podman-compose up -d

    Update the address in Plex, Jellyfin, Emby or your IPTV players to https://dispatcharr.example.box.ca.

Updating

Dispatcharr updates its database automatically the first time a new version starts.

  1. Make a backup under Settings → Backup & Restore in the web interface, and download it.

  2. If you set up the restart script, comment out its two lines in your crontab (EDITOR=nano crontab -e) so it doesn't start Dispatcharr mid-update.

  3. Download the new image and recreate the container:

     cd ~/dispatcharr
 podman-compose pull
 podman-compose down
 podman-compose up -d

  4. Wait until Dispatcharr loads again (or the curl command from step 6 of Installation prints 200), then uncomment the crontab lines.

When a new Dispatcharr version moves to a newer PostgreSQL major version, the first start upgrades the database and keeps the old copy in ~/dispatcharr/data in a folder named db_backup_<version>_<number>. Once Dispatcharr works, delete it with podman unshare rm -r ~/dispatcharr/data/db_backup_*.

Upgrading from the previous version of this article

The previous instructions kept Dispatcharr's data in a Podman volume and checked it with a different restart script. Your channels, settings and users are kept by restoring a backup.

  1. Make a backup under Settings → Backup & Restore in the web interface, and download it.

  2. Remove the old watchdog.sh line from your crontab (EDITOR=nano crontab -e).

  3. Stop the old container and move the old files out of the way:

     cd ~/dispatcharr && podman-compose down
 mv ~/dispatcharr ~/dispatcharr-old

  4. Follow Installation from step 2, then Upload your backup under Settings → Backup & Restore and restore it.

  5. Once everything works, remove the old files and volume:

     rm -r ~/dispatcharr-old
 podman volume rm dispatcharr_dispatcharr_data

Uninstalling

This deletes your channels, settings and recordings. Download anything you want to keep first.

  1. Remove the two dispatcharr_restart.cron lines from your crontab (EDITOR=nano crontab -e).

  2. Stop and remove the container, then delete Dispatcharr's files:

     cd ~/dispatcharr && podman-compose down && cd ~
 podman unshare rm -rf ~/dispatcharr
 rm -f ~/dispatcharr_restart.cron
 podman rmi ghcr.io/dispatcharr/dispatcharr:latest

  3. If you set up a Managed Link, delete it from the Manage Links page.

Troubleshooting

  • The setup page says setup isn't allowed from your address: this is expected on Whatbox. Create your account from SSH with step 7 of Installation.

  • The SECRET_KEY setting must not be empty: manage.py commands must run through bash -lc, as in step 7 of Installation.

  • Forgot your Dispatcharr password: reset it from SSH with podman exec -it dispatcharr bash -lc "python manage.py changepassword <username>".

  • Locked out after changing Network Access settings: run podman exec dispatcharr bash -lc "python manage.py reset_network_access".

  • The page doesn't load at http://server.whatbox.ca:13940: check the ports: line in compose.yaml. It must be "13940:9191" for direct access; "127.0.0.1:13940:9191" only allows the Managed Link.

  • "Permission denied" when reading or deleting files in ~/dispatcharr: the files belong to the container's user. Prefix the command with podman unshare.

  • The restart script starts a second copy, or never starts Dispatcharr: check the podman ps line in dispatcharr_restart.cron matches the one above exactly, including '^dispatcharr$'.

  • Containers won't stop or start: run podman-compose down from ~/dispatcharr, then podman-compose up -d.

  • Podman shows Dispatcharr as stopped or exited, but it's still running: podman has lost track of the container. If you set up the restart script, comment out its crontab lines first. Then stop Dispatcharr's processes directly by sending its main process the normal stop signal, which shuts its database down cleanly:

      pkill -o -u user -fx '/bin/bash /app/docker/entrypoint.sh'

    Wait about 10 seconds, then check that this prints nothing:

      pgrep -u user -fx '/bin/bash /app/docker/entrypoint.sh'

    If it still prints a number, force it with kill -KILL and that number; the database then repairs itself on the next start. Finally, clear podman's records and start Dispatcharr again, and uncomment the crontab lines:

      cd ~/dispatcharr && podman-compose down && podman-compose up -d

  • Anything else: set DISPATCHARR_LOG_LEVEL=debug, recreate the container and read podman logs dispatcharr. See Dispatcharr's troubleshooting page, or ask on Dispatcharr's Discord server, linked from its documentation.