docker-hdhomerundvr

Docker container for the HDHomeRun DVR Server by SiliconDust.

HDHomeRun DVR Server version: 20250815
Base image: ubuntu:22.04

Features

• Runs the HDHomeRun DVR recording engine inside a Docker container
• supervisord keeps the process alive — auto-restarts if the DVR daemon crashes
• Container-level restart: unless-stopped policy recovers from container failures
• Timezone configurable via the TZ environment variable
• Host networking for full HDHomeRun device discovery (UDP broadcast)

Requirements

• A working HDHomeRun network tuner with up-to-date firmware (see below)
• Docker and Docker Compose installed on the host

Quick Start

Option A: Docker Hub

Use the published image from Docker Hub:

https://hub.docker.com/repository/docker/yoshiofthewire/hdhomerundvr/general

Option B: Build Locally

# 1. Clone the repository
git clone https://github.com/Yoshiofthewire/docker-hdhomerundvr.git
cd docker-hdhomerundvr

# 2. Edit docker-compose.yml and set your recordings path and timezone
#    volumes:
#      - /your/recordings/path:/hdhomerun
#    environment:
#      - TZ=America/New_York

# 3. Build and start
docker compose up -d --build

Configuration

Environment Variables

Volumes

Ports

Note: network_mode: host is used in docker-compose.yml so that UDP broadcast device discovery works correctly. In host mode, the ports mapping is bypassed, so the ports above are documentation only.

Updating the HDHomeRun Firmware

Before the first install or when updating firmware:

1. Install the HDHomeRun Windows or Mac application.
2. When prompted to install the DVR server component, select Don't Install.
3. You will be prompted to configure the tuner after setup completes.
4. Re-run the tuner setup — this will update the firmware.
5. You may need to re-scan channels after the firmware update.

How It Works

flowchart TD
    A[Docker container] --> B[supervisord\nPID 1, nodaemon=true]
    B --> C[hdhomerun_wrapper.sh]
    C --> D[hdhomerun_record_x64 start\nStarts DVR daemon]
    C --> E[Monitors DVR process\nevery 15 seconds]
    E --> F[If the DVR process disappears, the wrapper exits non-zero]
    F --> G[supervisord restarts the wrapper\nup to 10 retries]
    H[SIGTERM from Docker] --> I[Wrapper calls hdhomerun_record_x64 stop]

• supervisord runs as PID 1 in the foreground (nodaemon=true), preventing spurious container exits.
• hdhomerun_wrapper.sh wraps the DVR daemon (which forks to the background) and stays alive to monitor it.
• If the DVR process disappears, the wrapper exits with a non-zero code so supervisord restarts it (up to 10 retries).
• SIGTERM from Docker is caught cleanly — the wrapper calls hdhomerun_record_x64 stop before exiting.

License

GPL v2.0