Installation

HD Homey can be installed using Docker (recommended), or from source for development purposes.

Prerequisites

Before installing HD Homey, ensure you have:

• An HDHomeRun device on your local network
• Network connectivity between HD Homey and your HDHomeRun device
• For Docker installations: Docker and Docker Compose
• For source installations: Node.js 22+ and npm

Docker Compose (Recommended)

Docker Compose is the recommended installation method for production deployments. It handles all dependencies and provides easy updates.

Step 1: Create Configuration Files

Create a new directory for HD Homey and download the configuration files:

# Create directory
mkdir hd-homey && cd hd-homey

# Download compose.yml
curl -O https://raw.githubusercontent.com/shaunburdick/hd-homey/main/compose.yml

# Download .env-example
curl -O https://raw.githubusercontent.com/shaunburdick/hd-homey/main/.env-example

Step 2: Configure Environment Variables

Create your .env file with a secure authentication secret:

# Copy example file
cp .env-example .env

# Generate a secure random secret (macOS/Linux)
sed -i "s/some-random-string/$(openssl rand -base64 32)/" .env

# Or manually edit .env and set AUTH_SECRET

Required Variables:

• AUTH_SECRET - Encryption key for session authentication (32+ characters)

Optional Variables (with auto-detection/defaults):

• HD_HOMEY_PROXY_HOST - Your external URL (default: auto-detected from request)
• HD_HOMEY_DB_PATH - Database file path (default: ./data/db/hd_homey.db)
• HD_HOMEY_TRANSCODE_DIR - Transcoding directory (default: ${HD_HOMEY_DB_PATH}/transcoding)
• FFMPEG_PATH - FFmpeg binary path (default: auto-detected from PATH)
• BETTER_AUTH_URL - Auth base URL (default: auto-detected)

See Environment Variables for complete configuration options.

Step 3: Start HD Homey

Launch the application using Docker Compose:

docker compose up -d

Step 4: Verify Installation

Check that HD Homey is running:

# View logs
docker compose logs -f

# Look for: "✓ Ready in XXms"

Access HD Homey at http://localhost:3000 (or your configured hostname) and create your first admin account.

TIP

The first user created automatically becomes an administrator.

Docker Run

For a simpler single-container deployment without Docker Compose:

# Create a volume for persistent data
docker volume create hd-homey-data

# Run HD Homey
docker run -d \
  --name hd-homey \
  -p 3000:3000 \
  -v hd-homey-data:/app/data \
  -e AUTH_SECRET=$(openssl rand -base64 32) \
  ghcr.io/shaunburdick/hd-homey:latest

# For remote access, optionally add:
# -e HD_HOMEY_PROXY_HOST=https://tuner.example.com

# View logs
docker logs -f hd-homey

From Source

Install from source for development or if you prefer not to use Docker.

Step 1: Clone Repository

git clone https://github.com/shaunburdick/hd-homey.git
cd hd-homey

Step 2: Install Dependencies

npm ci

Step 3: Configure Environment

# Copy example environment file
cp .env-example .env

# Edit .env and set AUTH_SECRET
# Generate with: openssl rand -base64 32

Step 4: Start Development Server

npm run dev

The application will be available at http://localhost:3000.

FFmpeg Required

Source installations require FFmpeg to be installed and available in your PATH with H.264 and AAC codec support for video transcoding.

Production Build

To create a production build from source:

# Build the application
npm run build

# Start production server
npm start

Updating HD Homey

Docker Compose Update

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

# View logs to confirm successful update
docker compose logs -f

Docker Run Update

# Stop and remove old container
docker stop hd-homey
docker rm hd-homey

# Pull latest image
docker pull ghcr.io/shaunburdick/hd-homey:latest

# Start new container (use same docker run command as installation)

Source Update

# Pull latest code
git pull origin main

# Install updated dependencies
npm ci

# Restart development server
npm run dev

Uninstalling

Docker Compose

# Stop and remove containers
docker compose down

# Remove data volumes (WARNING: This deletes your database!)
docker compose down -v

# Remove downloaded files
cd .. && rm -rf hd-homey

Docker Run

# Stop and remove container
docker stop hd-homey
docker rm hd-homey

# Remove volume (WARNING: This deletes your database!)
docker volume rm hd-homey-data

Source Installation

# Remove the cloned directory
rm -rf hd-homey

Next Steps

• Quick Start Guide - Complete the initial setup
• Your First Stream - Add a tuner and watch live TV
• Environment Variables - Advanced configuration options