This project provides a Docker container for HandBrake.
The graphical user interface (GUI) of the application can be accessed through a modern web browser, requiring no installation or configuration on the client side, or via any VNC client.
A fully automated mode is also available: drop files into a watch folder and let HandBrake process them without any user interaction.
HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs.
- Quick Start
- Usage
- Docker Image Versioning and Tags
- Docker Image Update
- User/Group IDs
- Accessing the GUI
- Security
- Reverse Proxy
- Shell Access
- Access to Optical Drives
- Automatic Video Conversion
- Intel Quick Sync Video
- Nightly Builds
- Debug Builds
- Support or Contact
Important
The Docker command provided in this quick start is an example, and parameters should be adjusted to suit your needs.
Launch the HandBrake docker container with the following command:
docker run -d \
--name=handbrake \
-p 5800:5800 \
-v /docker/appdata/handbrake:/config:rw \
-v /home/user:/storage:ro \
-v /home/user/HandBrake/watch:/watch:rw \
-v /home/user/HandBrake/output:/output:rw \
jlesage/handbrake
Where:
/docker/appdata/handbrake
: Stores the application's configuration, state, logs, and any files requiring persistency./home/user
: Contains files from the host that need to be accessible to the application./home/user/HandBrake/watch
: The location for videos to be automatically converted./home/user/HandBrake/output
: The destination for converted video files.
Access the HandBrake GUI by browsing to http://your-host-ip:5800
.
Files from the host appear under the /storage
folder in the container.
docker run [-d] \
--name=handbrake \
[-e <VARIABLE_NAME>=<VALUE>]... \
[-v <HOST_DIR>:<CONTAINER_DIR>[:PERMISSIONS]]... \
[-p <HOST_PORT>:<CONTAINER_PORT>]... \
jlesage/handbrake
Parameter | Description |
---|---|
-d | Runs the container in the background. If not set, the container runs in the foreground. |
-e | Passes an environment variable to the container. See Environment Variables for details. |
-v | Sets a volume mapping to share a folder or file between the host and the container. See Data Volumes for details. |
-p | Sets a network port mapping to expose an internal container port to the host). See Ports for details. |
To customize the container's behavior, you can pass environment variables using
the -e
parameter in the format <VARIABLE_NAME>=<VALUE>
.
Variable | Description | Default |
---|---|---|
USER_ID |
ID of the user the application runs as. See User/Group IDs for details. | 1000 |
GROUP_ID |
ID of the group the application runs as. See User/Group IDs for details. | 1000 |
SUP_GROUP_IDS |
Comma-separated list of supplementary group IDs for the application. | (no value) |
UMASK |
Mask controlling permissions for newly created files and folders, specified in octal notation. By default, 0022 ensures files and folders are readable by all but writable only by the owner. See the umask calculator at http://wintelguy.com/umask-calc.pl. |
0022 |
LANG |
Sets the locale, defining the application's language, if supported. Format is language[_territory][.codeset] , where language is an ISO 639 language code, territory is an ISO 3166 country code, and codeset is a character set, like UTF-8 . For example, Australian English using UTF-8 is en_AU.UTF-8 . |
en_US.UTF-8 |
TZ |
TimeZone used by the container. The timezone can also be set by mapping /etc/localtime between the host and the container. |
Etc/UTC |
KEEP_APP_RUNNING |
When set to 1 , the application is automatically restarted if it crashes or terminates. |
0 |
APP_NICENESS |
Priority at which the application runs. A niceness value of -20 is the highest, 19 is the lowest and 0 the default. NOTE: A negative niceness (priority increase) requires additional permissions. The container must be run with the Docker option --cap-add=SYS_NICE . |
0 |
INSTALL_PACKAGES |
Space-separated list of packages to install during container startup. List of available packages can be found at https://pkgs.alpinelinux.org. | (no value) |
PACKAGES_MIRROR |
Mirror of the repository to use when installing packages. List of mirrors is available at https://mirrors.alpinelinux.org. | (no value) |
CONTAINER_DEBUG |
When set to 1 , enables debug logging. |
0 |
DISPLAY_WIDTH |
Width (in pixels) of the application's window. | 1920 |
DISPLAY_HEIGHT |
Height (in pixels) of the application's window. | 1080 |
DARK_MODE |
When set to 1 , enables dark mode for the application. See Dark Mode](#dark-mode) for details. |
0 |
WEB_AUDIO |
When set to 1 , enables audio support, allowing audio produced by the application to play through the browser. See Web Audio for details. |
0 |
WEB_FILE_MANAGER |
When set to 1 , enables the web file manager, allowing interaction with files inside the container through the web browser, supporting operations like renaming, deleting, uploading, and downloading. See Web File Manager for details. |
0 |
WEB_FILE_MANAGER_ALLOWED_PATHS |
Comma-separated list of paths within the container that the file manager can access. By default, the container's entire filesystem is not accessible, and this variable specifies allowed paths. If set to AUTO , commonly used folders and those mapped to the container are automatically allowed. The value ALL allows access to all paths (no restrictions). See Web File Manager for details. |
AUTO |
WEB_FILE_MANAGER_DENIED_PATHS |
Comma-separated list of paths within the container that the file manager cannot access. A denied path takes precedence over an allowed path. See Web File Manager for details. | (no value) |
WEB_AUTHENTICATION |
When set to 1 , protects the application's GUI with a login page when accessed via a web browser. Access is granted only with valid credentials. This feature requires the secure connection to be enabled. See Web Authentication for details. |
0 |
WEB_AUTHENTICATION_TOKEN_VALIDITY_TIME |
Lifetime of a token, in hours. A token is assigned to the user after successful login. As long as the token is valid, the user can access the application's GUI without logging in again. Once the token expires, the login page is displayed again. | 24 |
WEB_AUTHENTICATION_USERNAME |
Optional username for web authentication. Provides a quick and easy way to configure credentials for a single user. For more secure configuration or multiple users, see the Web Authentication section. | (no value) |
WEB_AUTHENTICATION_PASSWORD |
Optional password for web authentication. Provides a quick and easy way to configure credentials for a single user. For more secure configuration or multiple users, see the Web Authentication section. | (no value) |
SECURE_CONNECTION |
When set to 1 , uses an encrypted connection to access the application's GUI (via web browser or VNC client). See Security for details. |
0 |
SECURE_CONNECTION_VNC_METHOD |
Method used for encrypted VNC connections. Possible values are SSL or TLS . See Security for details. |
SSL |
SECURE_CONNECTION_CERTS_CHECK_INTERVAL |
Interval, in seconds, at which the system checks if web or VNC certificates have changed. When a change is detected, affected services are automatically restarted. A value of 0 disables the check. |
60 |
WEB_LISTENING_PORT |
Port used by the web server to serve the application's GUI. This port is internal to the container and typically does not need to be changed. By default, a container uses the default bridge network, requiring each internal port to be mapped to an external port (using the -p or --publish argument). If another network type is used, changing this port may prevent conflicts with other services/containers. NOTE: A value of -1 disables HTTP/HTTPS access to the application's GUI. |
5800 |
VNC_LISTENING_PORT |
Port used by the VNC server to serve the application's GUI. This port is internal to the container and typically does not need to be changed. By default, a container uses the default bridge network, requiring each internal port to be mapped to an external port (using the -p or --publish argument). If another network type is used, changing this port may prevent conflicts with other services/containers. NOTE: A value of -1 disables VNC access to the application's GUI. |
5900 |
VNC_PASSWORD |
Password required to connect to the application's GUI. See the VNC Password section for details. | (no value) |
ENABLE_CJK_FONT |
When set to 1 , installs the open-source font WenQuanYi Zen Hei , supporting a wide range of Chinese/Japanese/Korean characters. |
0 |
HANDBRAKE_DEBUG |
When set to 1 , enables HandBrake debug logging for both the GUI and the automatic video converter. For the latter, increased verbosity is reflected in /config/log/hb/conversion.log (container path). For the GUI, log messages are sent to /config/log/hb/handbrake.debug.log (container path). NOTE: When enabled, a large amount of information is generated, and the log file grows quickly. Enable this temporarily and only when needed. |
0 |
HANDBRAKE_GUI |
Setting this to 1 enables the HandBrake GUI; 0 disables it. |
1 |
HANDBRAKE_GUI_QUEUE_STARTUP_ACTION |
Action to be taken on the HandBrake GUI queue at startup. When set to PROCESS , HandBrake automatically starts encoding items in the queue. When set to CLEAR , the queue is cleared. Any other value results in no action on the queue. |
NONE |
AUTOMATED_CONVERSION |
Setting this to 1 enables the automatic video converter, 0 disables it. |
1 |
AUTOMATED_CONVERSION_PRESET |
HandBrake preset used by the automatic video converter. The preset must be identified in the format <CATEGORY>/<PRESET NAME> . See the Automatic Video Conversion section for details. |
General/Very Fast 1080p30 |
AUTOMATED_CONVERSION_FORMAT |
Video container format used by the automatic video converter for output files, typically the video filename extension. See the Automatic Video Conversion section for details. | mp4 |
AUTOMATED_CONVERSION_KEEP_SOURCE |
When set to 0 , a successfully converted video is removed from the watch folder. |
1 |
AUTOMATED_CONVERSION_VIDEO_FILE_EXTENSIONS |
Space-separated list of file extensions considered as video files. By default, this list is empty, allowing HandBrake to automatically detect if a file is a video, regardless of its extension (except for extensions defined by AUTOMATED_CONVERSION_NON_VIDEO_FILE_EXTENSIONS , which are always considered non-video). This variable is typically unnecessary but useful when only specific video files need conversion. |
(no value) |
AUTOMATED_CONVERSION_NON_VIDEO_FILE_ACTION |
When set to ignore , non-video files in the watch folder are ignored. If set to copy , non-video files are copied as-is to the output folder. |
ignore |
AUTOMATED_CONVERSION_NON_VIDEO_FILE_EXTENSIONS |
Space-separated list of file extensions considered non-video. Most non-video files are properly rejected by HandBrake, but some files, like images, may be convertible despite not being videos. | jpg jpeg bmp png gif txt nfo |
AUTOMATED_CONVERSION_WATCH_DIR |
Path to the watch directory within the container. When set to AUTO (the default), the path is set to /watch for the first watch directory and /watchX for additional ones, where X is the index (e.g., 2 for the second). NOTE: Ensure a volume mapping for this directory is defined when creating the container. |
AUTO |
AUTOMATED_CONVERSION_OUTPUT_DIR |
Root directory inside the container where converted videos are written. NOTE: Ensure a volume mapping for this directory is defined when creating the container. | /output |
AUTOMATED_CONVERSION_OUTPUT_SUBDIR |
Subdirectory of the output folder where converted videos are written. By default, videos are saved directly to /output/ . If set to Home/Movies , videos are written to /output/Home/Movies . Use SAME_AS_SRC to match the source subfolder. For example, if the source is /watch/Movies/MyMovie/MyMovie.mkv , the output is written to /output/Movies/MyMovie/ . |
(no value) |
AUTOMATED_CONVERSION_OVERWRITE_OUTPUT |
When set to 1 , allows overwriting an existing destination file. |
0 |
AUTOMATED_CONVERSION_SOURCE_STABLE_TIME |
Time (in seconds) during which properties (e.g., size, time) of a video file in the watch folder must remain unchanged to avoid processing a file being copied. | 5 |
AUTOMATED_CONVERSION_SOURCE_MIN_DURATION |
Minimum title duration (in seconds). Shorter titles are ignored. Applies only to video disc sources (ISO files, VIDEO_TS folders, or BDMV folders). |
10 |
AUTOMATED_CONVERSION_SOURCE_MAIN_TITLE_DETECTION |
When set to 1 , enables HandBrake's main feature title detection to guess and select the main title. Applies only to video disc sources (ISO files, VIDEO_TS folders, or BDMV folders). |
0 |
AUTOMATED_CONVERSION_CHECK_INTERVAL |
Interval (in seconds) at which the automatic video converter checks for new files. | 5 |
AUTOMATED_CONVERSION_MAX_WATCH_FOLDERS |
Maximum number of watch folders handled by the automatic video converter. | 5 |
AUTOMATED_CONVERSION_NO_GUI_PROGRESS |
When set to 1 , progress of videos converted by the automatic video converter is not shown in the HandBrake GUI. |
0 |
AUTOMATED_CONVERSION_HANDBRAKE_CUSTOM_ARGS |
Custom arguments to pass to HandBrake during conversion. | (no value) |
AUTOMATED_CONVERSION_USE_TRASH |
When set to 1 , the automatic video converter uses the trash directory. This applies only when the converter is configured not to keep source files. In that case, they will be moved to the trash directory (/trash inside the container by default) instead of being permanently deleted. |
0 |
AUTOMATED_CONVERSION_TRASH_DIR |
Location of the trash directory inside the container. | /trash |
Many tools used to manage Docker containers extract environment variables defined by the Docker image to create or deploy the container.
For example, this behavior is seen in:
- The Docker application on Synology NAS
- The Container Station on QNAP NAS
- Portainer
- etc.
While this is useful for users to adjust environment variable values to suit their needs, keeping all of them can be confusing and even risky.
A good practice is to set or retain only the variables necessary for the container to function as desired in your setup. If a variable is left at its default value, it can be removed. Keep in mind that all environment variables are optional; none are required for the container to start.
Removing unneeded environment variables offers several benefits:
- Prevents retaining variables no longer used by the container. Over time, with image updates, some variables may become obsolete.
- Allows the Docker image to update or fix default values. With image updates, default values may change to address issues or support new features.
- Avoids changes to variables that could disrupt the container's
functionality. Some undocumented variables, like
PATH
orENV
, are required but not meant to be modified by users, yet container management tools may expose them. - Addresses a bug in Container Station on QNAP and the Docker application on Synology, where variables without values may not be allowed. This behavior is incorrect, as variables without values are valid. Removing unneeded variables prevents deployment issues on these devices.
The following table describes the data volumes used by the container. Volume
mappings are set using the -v
parameter with a value in the format
<HOST_DIR>:<CONTAINER_DIR>[:PERMISSIONS]
.
Container path | Permissions | Description |
---|---|---|
/config |
rw | Stores the application's configuration, state, logs, and any files requiring persistency. |
/storage |
ro | Contains files from the host that need to be accessible to the application. |
/watch |
rw | The location for videos to be automatically converted. |
/output |
rw | The destination for converted video files. |
/trash |
rw | When trash usage is enabled, converted source files are moved here instead of being deleted. |
The following table lists the ports used by the container.
When using the default bridge network, ports can be mapped to the host using the
-p
parameter with value in the format <HOST_PORT>:<CONTAINER_PORT>
. The
internal container port may not be changeable, but you can use any port on the
host side.
See the Docker Docker Container Networking documentation for details.
Port | Protocol | Mapping to Host | Description |
---|---|---|---|
5800 | TCP | Optional | Port to access the application's GUI via the web interface. Mapping to the host is optional if web access is not needed. For non-default bridge networks, the port can be changed with the WEB_LISTENING_PORT environment variable. |
5900 | TCP | Optional | Port to access the application's GUI via the VNC protocol. Mapping to the host is optional if VNC access is not needed. For non-default bridge networks, the port can be changed with the VNC_LISTENING_PORT environment variable. |
Environment variables, volume mappings, and port mappings are specified when creating the container. To modify these parameters for an existing container, follow these steps:
- Stop the container (if it is running):
docker stop handbrake
- Remove the container:
docker rm handbrake
- Recreate and start the container using the
docker run
command, adjusting parameters as needed.
Note
Since all application data is saved under the /config
container folder,
destroying and recreating the container does not result in data loss, and the
application resumes with the same state, provided the /config
folder
mapping remains unchanged.
Below is an example docker-compose.yml
file for use with
Docker Compose.
Adjust the configuration to suit your needs. Only mandatory settings are included in this example.
version: '3'
services:
handbrake:
image: jlesage/handbrake
ports:
- "5800:5800"
volumes:
- "/docker/appdata/handbrake:/config:rw"
- "/home/user:/storage:ro"
- "/home/user/HandBrake/watch:/watch:rw"
- "/home/user/HandBrake/output:/output:rw"
Each release of a Docker image is versioned, and each version as its own image tag. Before October 2022, the versioning scheme followed semantic versioning.
Since then, the versioning scheme has shifted to
calendar versioning with the format YY.MM.SEQUENCE
,
where:
YY
is the zero-padded year (relative to year 2000).MM
is the zero-padded month.SEQUENCE
is the incremental release number within the month (first release is 1, second is 2, etc).
View all available tags on Docker Hub or check the Releases page for version details.
The Docker image is regularly updated to incorporate new features, fix issues, or integrate newer versions of the containerized application. Several methods can be used to update the Docker image.
If your system provides a built-in method for updating containers, this should be your primary approach.
Alternatively, you can use Watchtower, a container-based solution for automating Docker image updates. Watchtower seamlessly handles updates when a new image is available.
To manually update the Docker image, follow these steps:
- Fetch the latest image:
docker pull jlesage/handbrake
- Stop the container:
docker stop handbrake
- Remove the container:
docker rm handbrake
- Recreate and start the container using the
docker run
command, with the same parameters used during initial deployment.
For Synology NAS users, follow these steps to update a container image:
- Open the Docker application.
- Click Registry in the left pane.
- In the search bar, type the name of the container (
jlesage/handbrake
). - Select the image, click Download, and choose the
latest
tag. - Wait for the download to complete. A notification will appear once done.
- Click Container in the left pane.
- Select your HandBrake container.
- Stop it by clicking Action -> Stop.
- Clear the container by clicking Action -> Reset (or Action -> Clear if you don't have the latest Docker application). This removes the container while keeping its configuration.
- Start the container again by clicking Action -> Start. NOTE: The container may temporarily disappear from the list while it is recreated.
For unRAID users, update a container image with these steps:
- Select the Docker tab.
- Click the Check for Updates button at the bottom of the page.
- Click the apply update link of the container to be updated.
When mapping data volumes (using the -v
flag of the docker run
command),
permission issues may arise between the host and the container. Files and
folders in a data volume are owned by a user, which may differ from the user
running the application. Depending on permissions, this could prevent the
container from accessing the shared volume.
To avoid this, specify the user the application should run as using the
USER_ID
and GROUP_ID
environment variables.
To find the appropriate IDs, run the following command on the host for the user owning the data volume:
id <username>
This produces output like:
uid=1000(myuser) gid=1000(myuser) groups=1000(myuser),4(adm),24(cdrom),27(sudo),46(plugdev),113(lpadmin)
Use the uid
(user ID) and gid
(group ID) values to configure the container.
Assuming the container's ports are mapped to the same host's ports, access the application's GUI as follows:
- Via a web browser:
http://<HOST_IP_ADDR>:5800
- Via any VNC client:
<HOST_IP_ADDR>:5900
By default, access to the application's GUI uses an unencrypted connection (HTTP or VNC).
A secure connection can be enabled via the SECURE_CONNECTION
environment
variable. See the Environment Variables section for
details on configuring environment variables.
When enabled, the GUI is accessed over HTTPS when using a browser, with all HTTP accesses redirected to HTTPS.
For VNC clients, the connection can be secured using on of two methods,
configured via the SECURE_CONNECTION_VNC_METHOD
environment variable:
SSL
: An SSL tunnel is used to transport the VNC connection. Few VNC clients supports this method; SSVNC is one that does.TLS
: A VNC security type negotiated during the VNC handshake. It uses TLS to establish a secure connection. Clients may optionally validate the server’s certificate. Valid certificates must be provided for this validation to succeed. See Certificates for details. TigerVNC is a client that supports TLS encryption.
SSVNC is a VNC viewer that adds encryption to VNC connections by using an SSL tunnel to transport the VNC traffic.
While the Linux version of SSVNC works well, the Windows version has issues.
At the time of writing, the latest version 1.0.30
fails with the error:
ReadExact: Socket error while reading
For convenience, an unofficial, working version is provided here:
https://github.com/jlesage/docker-baseimage-gui/raw/master/tools/ssvnc_windows_only-1.0.30-r1.zip
This version upgrades the bundled stunnel
to version 5.49
, resolving the
connection issues.
The following certificate files are required by the container. If missing, self-signed certificates are generated and used. All files are PEM-encoded x509 certificates.
Container Path | Purpose | Content |
---|---|---|
/config/certs/vnc-server.pem |
VNC connection encryption. | VNC server's private key and certificate, bundled with any root and intermediate certificates. |
/config/certs/web-privkey.pem |
HTTPS connection encryption. | Web server's private key. |
/config/certs/web-fullchain.pem |
HTTPS connection encryption. | Web server's certificate, bundled with any root and intermediate certificates. |
Tip
To avoid certificate validity warnings or errors in browsers or VNC clients, provide your own valid certificates.
Note
Certificate files are monitored, and relevant services are restarted when changes are detected.
To restrict access to your application, set a password using one of two methods:
- Via the
VNC_PASSWORD
environment variable. - Via a
.vncpass_clear
file at the root of the/config
volume, containing the password in clear text. During container startup, the content is obfuscated and moved to.vncpass
.
The security of the VNC password depends on:
- The communication channel (encrypted or unencrypted).
- The security of host access.
When using a VNC password, enable a secure connection to prevent sending the password in clear text over an unencrypted channel.
Unauthorized users with sufficient host privileges can retrieve the password by:
- Viewing the
VNC_PASSWORD
environment variable viadocker inspect
. By default, thedocker
command requires root access, but it can be configured to allow users in a specific group. - Decrypting the
/config/.vncpass
file, which requires root orUSER_ID
permissions.
Caution
VNC password is limited to 8 characters. This limitation comes from the Remote Framebuffer Protocol RFC (see section 7.2.2).
Access to the application's GUI via a web browser can be protected with a login page. When enabled, users must provide valid credentials to gain access.
Enable web authentication by setting the WEB_AUTHENTICATION
environment
variable to 1
. See the Environment Variables section
for details on configuring environment variables.
Important
Web authentication requires a secure connection to be enabled. See Security for details.
User credentials can be configured in two ways:
- Via container environment variables.
- Via a password database.
Container environment variables provide a quick way to configure a single user. Set the username and password using:
WEB_AUTHENTICATION_USERNAME
WEB_AUTHENTICATION_PASSWORD
See the Environment Variables section for details on configuring environment variables.
For a more secure method or to configure multiple users, use a password database
at /config/webauth-htpasswd
within the container. This file uses the Apache
HTTP server's htpasswd format, storing bcrypt-hashed passwords.
Manage users with the webauth-user
tool:
- Add a user:
docker exec -ti <container name> webauth-user add <username>
- Update a user:
docker exec -ti <container name> webauth-user update <username>
- Remove a user:
docker exec <container name> webauth-user del <username>
- List users:
docker exec <container name> webauth-user list
The following sections provide NGINX configurations for setting up a reverse proxy to this container.
A reverse proxy server can route HTTP requests based on the hostname or URL path.
In this scenario, each hostname is routed to a different application or container.
For example, if the reverse proxy server runs on the same machine as this
container, it would proxy all HTTP requests for handbrake.domain.tld
to
the container at 127.0.0.1:5800
.
Here are the relevant configuration elements to add to the NGINX configuration:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
upstream docker-handbrake {
# If the reverse proxy server is not running on the same machine as the
# Docker container, use the IP of the Docker host here.
# Make sure to adjust the port according to how port 5800 of the
# container has been mapped on the host.
server 127.0.0.1:5800;
}
server {
[...]
server_name handbrake.domain.tld;
location / {
proxy_pass http://docker-handbrake;
}
location /websockify {
proxy_pass http://docker-handbrake;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 86400;
}
# Needed when audio support is enabled.
location /websockify-audio {
proxy_pass http://docker-handbrake;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 86400;
}
}
In this scenario, the same hostname is used, but different URL paths route to
different applications or containers. For example, if the reverse proxy server
runs on the same machine as this container, it would proxy all HTTP requests for
server.domain.tld/filebot
to the container at 127.0.0.1:5800
.
Here are the relevant configuration elements to add to the NGINX configuration:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
upstream docker-handbrake {
# If the reverse proxy server is not running on the same machine as the
# Docker container, use the IP of the Docker host here.
# Make sure to adjust the port according to how port 5800 of the
# container has been mapped on the host.
server 127.0.0.1:5800;
}
server {
[...]
location = /handbrake {return 301 $scheme://$http_host/handbrake/;}
location /handbrake/ {
proxy_pass http://docker-handbrake/;
# Uncomment the following line if your Nginx server runs on a port that
# differs from the one seen by external clients.
#port_in_redirect off;
location /handbrake/websockify {
proxy_pass http://docker-handbrake/websockify;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 86400;
}
# Needed when audio support is enabled.
location /handbrake/websockify-audio {
proxy_pass http://docker-handbrake/websockify-audio;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 86400;
}
}
}
The container supports streaming audio from the application, played through the user's web browser. Audio is not supported for VNC clients.
Audio is streamed with the following specification:
- Raw PCM format
- 2 channels
- 16-bit sample depth
- 44.1kHz sample rate
Enable web audio by setting WEB_AUDIO
to 1
. See the
Environment Variables section for details on
configuring environment variables.
The container includes a simple file manager for interacting with container files through a web browser, supporting operations like renaming, deleting, uploading, and downloading.
Enable the file manager by setting WEB_FILE_MANAGER
to 1
. See the
Environment Variables section for details on
configuring environment variables.
By default, the container's entire filesystem is not accessible. The
WEB_FILE_MANAGER_ALLOWED_PATHS
environment variable is a comma-separated list
that specifies which paths within the container are allowed to be accessed. When
set to AUTO
(the default), it automatically includes commonly used folders and
any folders mapped to the container.
The WEB_FILE_MANAGER_DENIED_PATHS
environment variable defines which paths are
explicitly denied access by the file manager. A denied path takes precedence
over an allowed one.
To access the shell of a running container, execute the following command:
docker exec -ti CONTAINER sh
Where CONTAINER
is the ID or the name of the container used during its
creation.
By default, a Docker container does not have access to host's devices. However,
access to one or more devices can be granted with the --device DEV
parameter
of the docker run
command.
In Linux, optical drives are represented by device files named /dev/srX
, where
X
is a number (e.g., /dev/sr0
for the first drive, /dev/sr1
for the
second, etc). To allow HandBrake to access the first drive, use
this parameter:
--device /dev/sr0
To identify the correct Linux devices to expose, check the container's log during startup. Look for messages like:
[cont-init ] 54-check-optical-drive.sh: looking for usable optical drives...
[cont-init ] 54-check-optical-drive.sh: found optical drive 'hp HLDS DVDRW GUD1N LD02' [/dev/sr0]
[cont-init ] 54-check-optical-drive.sh: [ OK ] associated SCSI CD-ROM (sr) device detected: /dev/sr0.
[cont-init ] 54-check-optical-drive.sh: [ ERR ] the host device /dev/sr0 is not exposed to the container.
[cont-init ] 54-check-optical-drive.sh: no usable optical drives found.
This indicates that /dev/sr0
needs to be exposed to the container.
Tip
View the container’s log by running docker logs <container_name>
.
Alternatively, identify Linux devices from the host by running:
lsscsi -k
The output's last column for an optical drive indicates the device to expose.
The following example shows that /dev/sr0
should be exposed:
[0:0:0:0] disk ATA SanDisk SSD PLUS 9100 /dev/sda
[1:0:0:0] disk ATA SanDisk SSD PLUS 9100 /dev/sdb
[2:0:0:0] disk ATA ST3500418AS HP34 /dev/sdc
[4:0:0:0] cd/dvd hp HLDS DVDRW GUD1N LD02 /dev/sr0
Since HandBrake can decrypt DVD video discs, conversions can be
performed directly from the optical device. In the GUI, click the Open Source
button and browse to the optical drive device in the file system
(e.g., /dev/sr0
).
This container includes a built-in automatic video converter for batch-converting videos without user interaction.
Files placed in the /watch
container folder are automatically converted by
HandBrake to a predefined video format using a specified preset.
All configuration parameters for the automatic video converter are set via
environment variables. See the Environment Variables
section for available variables, particularly those starting with
AUTOMATED_CONVERSION_
.
Note
Presets are identified by their category and name (e.g.,
General/Very Fast 1080p30
).
Note
All default and custom presets can be viewed and edited in the HandBrake GUI.
Note
By default, converted videos are stored in the /output
folder of the
container.
Note
The status and progress of conversions can be monitored via the GUI or the
container’s log. View the log with docker logs <container name>
, Full
conversion details are stored in /config/log/hb/conversion.log
within the
container.
Additional watch folders can be used, such as:
/watch2
/watch3
/watch4
/watch5
- etc.
This is useful for scenarios where videos require different presets (e.g., one folder for movies and another for TV shows with distinct encoding quality requirements).
By default, additional watch folders inherit the settings of the main /watch
folder. To override a setting for a specific watch folder, append its index to
the environment variable name. For example, to set the preset for /watch2
, use
AUTOMATED_CONVERSION_PRESET_2
. For /watch3
, use
AUTOMATED_CONVERSION_PRESET_3
, and so on.
All settings prefixed with AUTOMATED_CONVERSION_
can be overridden for each
additional watch folder.
The maximum number of watch folders is defined by the
AUTOMATED_CONVERSION_MAX_WATCH_FOLDERS
environment variable.
Note
Each additional watch folder must be mapped to a host folder via a volume mapping during container creation.
Note
Each output folder defined via AUTOMATED_CONVERSION_OUTPUT_DIR
must be
mapped to a host folder via a volume mapping during container creation.
The automatic video converter supports video discs in the following format:
- ISO image file
- DVD video disc folder containing the
VIDEO_TS
folder - Blu-ray video disc folder containing the
BDMV
folder
Folder names are case-sensitive. For example, video_ts
, Video_Ts
, or Bdmv
are not treated as discs but as regular directories.
For disc folders, the converted video file’s name matches the folder name.
For example, /watch/MyMovie/VIDEO_TS
produces MyMovie.mp4
.
Video discs may have multiple titles (e.g., main movie, previews, extras).
Each title is converted to a separate file with a .title-XX
suffix, where XX
is the title number. For example, if MyMovie.iso
has two titles, the output
files are:
MyMovie.title-1.mp4
MyMovie.title-2.mp4
Titles shorter than a specified duration can be ignored. By default, only titles
longer than 10 seconds are processed, adjustable via the
AUTOMATED_CONVERSION_SOURCE_MIN_DURATION
environment variable.
Custom actions can be performed using hooks, which are shell scripts executed by the automatic video converter.
Note
Hooks are always executed via /bin/sh
, ignoring any shebang in the script.
Hooks are optional and undefined by default. A hook is executed when a script is found at a specific location.
The following table describes available hooks:
Container Location | Description | Parameter(s) |
---|---|---|
/config/hooks/pre_conversion.sh |
Executed before a video conversion begins. | The first argument is the path of the converted video. The second argument is the path to the source file. The third argument is the name of the Handbrake preset used for conversion. |
/config/hooks/post_conversion.sh |
Executed when a video conversion completes. | The first parameter is the conversion status (0 for success, any other value for failure). The second argument is the path to the converted video. The third argument is the path to the source file. The fourth argument is the name of the Handbrake preset used for conversion. |
/config/hooks/post_watch_folder_processing.sh |
Executed after all videos in the watch folder are processed. | The path of the watch folder. |
/config/hooks/hb_custom_args.sh |
Executed to obtain custom HandBrake arguments for conversion. The script should print a space-separated list of arguments to its standard output. | The first argument is the path to the source file. The second argument is the name of the Handbrake preset used for conversion. |
Tip
Example hooks are installed in /config/hooks/
with a .example
suffix. They
can be used as a starting point.
Tip
Use the INSTALL_PACKAGES
environment variable to install additional
packages needed by features implemented via hooks.
Videos being converted are written to a hidden, temporary directory under the
root of the output directory (/output
by default). Once conversion completes
successfully, the video file is moved to its final location.
This feature is useful when the output folder is monitored by another application, ensuring it only sees the final converted file, not transient versions.
If the monitoring application ignores hidden directories, no special configuration is needed.
If the monitoring application processes hidden directories, set the
AUTOMATED_CONVERSION_OUTPUT_SUBDIR
environment variable to a subdirectory and
configure the monitoring application to watch this subdirectory. For example,
if AUTOMATED_CONVERSION_OUTPUT_SUBDIR
is set to TV Shows
and /output
is
mapped to /home/user/appvolumes/HandBrake
on the host, monitor
/home/user/appvolumes/HandBrake/TV Shows
.
Intel Quick Sync Video is Intel’s dedicated video encoding and decoding hardware core, offloading tasks to the integrated GPU to reduce CPU usage and improve power efficiency.
For HandBrake to use hardware-accelerated encoding, the following are required:
- A compatible Intel processor. Check if your CPU supports Quick Sync Video on
the Intel Ark website. The processor model is logged during container
startup, e.g.:
[cont-init.d] 54-check-qsv.sh: Processor: Intel(R) Core(TM) i7-2600 CPU @ 3.40GHz
- The Intel i915 graphics driver must be loaded on the host.
- The
/dev/dri
device must be exposed to the container using the--device /dev/dri
parameter in thedocker run
command.
When Intel Quick Sync Video is enabled, HandBrake offers the
H.264 (Intel QSV)
video encoder. If this encoder is not listed, check the
container’s log for details on the issue.
Note
In most cases, HandBrake can access /dev/dri
without host
modifications, as the container’s user is automatically added to the group
owning the device. If the device is owned by the root
group, use one of
these solutions:
- Change the group owning the
/dev/dri
device on the host. For example, to set it tovideo
:sudo chown root:video /dev/dri/*
- Grant read/write permissions to all for the
/dev/dri
device on the host:sudo chmod a+wr /dev/dri/*
- Run the container as root (
USER_ID=0
). Not recommended for security reason.
In recent unRAID versions, the Intel i915 driver is included and loaded automatically.
For older versions, add the following lines to /boot/config/go
to load the
driver during unRAID startup:
# Load the i915 driver.
modprobe i915
Nightly builds are based on the latest HandBrake development code and may contain bugs, crashes, or instabilities.
Nightly builds are available via Docker image tags in the format:
nightly-<COMMIT_DATE>-<COMMIT_HASH>
Where:
COMMIT_DATE
is the date (inYYMMDDHHMMSS
format) of the latest commit from the HandBrake Git repository.COMMIT_HASH
is the short hash of the latest commit.
The latest nightly build is available via the nightly-latest
tag. View all
tags on Docker Hub.
To use a nightly build, append the tag to the Docker image name during container creation, e.g.:
docker run [OPTIONS...] jlesage/handbrake:nightly-latest
Debug builds are used to investigate issues with HandBrake. They are compiled in debug mode with all symbols retained, primarily for debugging crashes.
To generate a core dump when HandBrake crashes, two requirements must be met:
-
Enable core dumps by setting the maximum core size using the
--ulimit core=-1
parameter in thedocker run
command (-1
means unlimited). -
Set the core dump location on the host with:
echo 'CORE_PATTERN' | sudo tee /proc/sys/kernel/core_pattern
Replace
CORE_PATTERN
with a template for naming core dump files. For example, to store core dumps in the container’s configuration volume (for easy host access), use/config/core.%e.%t
.
Note
Core dump files contain the application’s complete memory layout and are
created with restrictive permissions. To allow access by a user other than the
one running HandBrake, run chmod a+r CORE
, where CORE
is the
path to the core file.
Note
The core dump pattern is shared between the host and container. Revert to the
original pattern after debugging by checking the current pattern with
cat /proc/sys/kernel/core_pattern
.
Debug builds are available via Docker image tags with a debug
suffix. Check
available tags on Docker Hub.
To use a debug build, append the tag to the Docker image name, e.g.:
docker run [OPTIONS...] jlesage/handbrake:v1.14.3-debug
On unRAID systems, add the --ulimit core=-1
parameter to the
Extra Parameters
field in the container settings.
Having troubles with the container or have questions? Please create a new issue.
For other Dockerized applications, visit https://jlesage.github.io/docker-apps.