Deploying HandBrake Web

Introduction

HandBrake Web provides a browser-based interface to the popular HandBrake video transcoding tool. This Docker container packages HandBrake with a web-accessible GUI, allowing you to convert videos between formats, compress media files, and apply presets from any device with a web browser. The container uses noVNC to deliver the HandBrake desktop application through your browser.

Built on the jlesage/handbrake Docker image, this deployment includes automatic video conversion features through watch folders, making it ideal for batch processing workflows. The web interface provides full access to HandBrake’s encoding options, presets, and queue management.

Key highlights of HandBrake Web:

• Browser-Based Access: Full HandBrake GUI accessible through any web browser
• Video Transcoding: Convert videos to MP4, MKV, WebM, and other formats
• Preset Support: Use built-in presets or create custom encoding profiles
• Automatic Conversion: Watch folder monitors for new files and converts automatically
• Queue Management: Queue multiple videos for batch processing
• Hardware Encoding: Support for Intel QSV, NVIDIA NVENC, and AMD VCE when available
• Cross-Platform: Access from any device with a modern web browser

This guide walks through deploying HandBrake Web on Klutch.sh using Docker, configuring storage volumes, and setting up automatic video conversion.

Prerequisites

Before deploying HandBrake Web on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your HandBrake configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of video formats and transcoding concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

handbrake-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the jlesage HandBrake image:

FROM jlesage/handbrake:latest

# Environment variables for configuration
ENV USER_ID=${PUID:-1000}
ENV GROUP_ID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}
ENV KEEP_APP_RUNNING=1
ENV CLEAN_TMP_DIR=1

# Optional: Set VNC password for security
ENV VNC_PASSWORD=${VNC_PASSWORD}

# Optional: Configure automatic conversion
ENV AUTOMATED_CONVERSION_PRESET=${AUTOMATED_CONVERSION_PRESET:-General/Very Fast 1080p30}
ENV AUTOMATED_CONVERSION_FORMAT=${AUTOMATED_CONVERSION_FORMAT:-mp4}
ENV AUTOMATED_CONVERSION_KEEP_SOURCE=${AUTOMATED_CONVERSION_KEEP_SOURCE:-1}

# Create directories
RUN mkdir -p /storage /watch /output

# Expose the web interface port
EXPOSE 5800

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:5800/ || exit 1

Advanced Dockerfile with Custom Presets

For advanced configurations:

FROM jlesage/handbrake:latest

ENV USER_ID=${PUID:-1000}
ENV GROUP_ID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}
ENV KEEP_APP_RUNNING=1

# Display configuration
ENV DISPLAY_WIDTH=1920
ENV DISPLAY_HEIGHT=1080

# Automatic conversion settings
ENV AUTOMATED_CONVERSION_PRESET=${AUTOMATED_CONVERSION_PRESET}
ENV AUTOMATED_CONVERSION_FORMAT=mp4
ENV AUTOMATED_CONVERSION_KEEP_SOURCE=1
ENV AUTOMATED_CONVERSION_OUTPUT_SUBDIR=converted
ENV AUTOMATED_CONVERSION_SOURCE_STABLE_TIME=5
ENV AUTOMATED_CONVERSION_CHECK_INTERVAL=5

# Security
ENV VNC_PASSWORD=${VNC_PASSWORD}
ENV SECURE_CONNECTION=0

EXPOSE 5800

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:5800/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
PUID	No	1000	User ID for file ownership
PGID	No	1000	Group ID for file ownership
TZ	No	Etc/UTC	Container timezone
VNC_PASSWORD	No	-	Password for web interface access
DISPLAY_WIDTH	No	1920	Web interface display width
DISPLAY_HEIGHT	No	1080	Web interface display height
AUTOMATED_CONVERSION_PRESET	No	-	HandBrake preset for automatic conversion
AUTOMATED_CONVERSION_FORMAT	No	mp4	Output format for automatic conversion
AUTOMATED_CONVERSION_KEEP_SOURCE	No	1	Keep source files after conversion
KEEP_APP_RUNNING	No	0	Keep HandBrake running after closing window

Deploying HandBrake Web on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial HandBrake Web deployment configuration"
git remote add origin https://github.com/yourusername/handbrake-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “handbrake” or “video-converter”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your HandBrake repository.

Configure HTTP Traffic

• Select HTTP as the traffic type
• Set the internal port to 5800

Set Environment Variables

Configure the following environment variables:

Variable	Value
PUID	1000
PGID	1000
TZ	Your timezone (e.g., America/New_York)
VNC_PASSWORD	A secure password for web access
KEEP_APP_RUNNING	1

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/config	1 GB	HandBrake configuration and settings
/storage	50+ GB	Source video files for manual conversion
/watch	50+ GB	Watch folder for automatic conversion
/output	100+ GB	Converted video output directory

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start HandBrake Web with HTTPS enabled.

Access HandBrake Web

Once deployment completes, access HandBrake at https://your-app-name.klutch.sh. If you set a VNC password, enter it when prompted.

Using HandBrake Web

Manual Video Conversion

1. Upload video files to the /storage volume
2. Open the web interface and click Open Source
3. Navigate to /storage and select your video
4. Choose a preset or configure encoding settings
5. Click Start to begin conversion
6. Converted files appear in /output

Automatic Conversion

1. Configure AUTOMATED_CONVERSION_PRESET in environment variables
2. Upload videos to the /watch folder
3. HandBrake automatically detects and converts new files
4. Converted files appear in the output directory

Using Presets

HandBrake includes many built-in presets:

• General: Fast 1080p30, Very Fast 1080p30, HQ 1080p30
• Web: Gmail, YouTube, Vimeo
• Devices: Apple, Android, Roku, PlayStation
• Matroska: H.264, H.265, VP9

Access custom presets through the Presets menu in the interface.

Troubleshooting

Web Interface Won’t Load

• Verify port 5800 is configured correctly
• Check container logs for startup errors
• Ensure sufficient memory is allocated

Conversion Fails

• Verify source video format is supported
• Check available storage space
• Review HandBrake logs in /config/log

File Permission Issues

• Verify PUID/PGID match your volume permissions
• Check volume mount paths are correct

Additional Resources

• Official HandBrake Website
• jlesage/docker-handbrake GitHub
• HandBrake Docker Hub
• HandBrake Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying HandBrake Web on Klutch.sh provides a powerful, browser-accessible video transcoding solution with automatic conversion capabilities. The web interface makes video encoding accessible from any device, while persistent storage ensures your configuration and media files are preserved across deployments. Whether you need occasional manual conversions or automated batch processing, HandBrake Web on Klutch.sh delivers professional video transcoding with minimal setup.