Currently, Docker/Docker Compose are the only officially supported methods of installing HandBrake Web.

You will need a host machine capable of running the Docker Engine:

• Linux (Recommended) - A native & bare-metal installation of a Linux distribution is the project's recommendation.
• Windows - Ensure you have WSL2 and/or Docker Desktop installed.
• MacOS - Ensure you have Docker Desktop installed.

You may face additional hurdles on Windows and MacOS.

You will need to have the following installed/available on your host system:

• Docker
• Docker Compose

Docker has fantastic installation docs that cover a wide variety of OS/Distribution options, check it out here. You can also install Docker Desktop, which you can read about here.

If you have a GPU you wish to use for hardware accelerated encoding, please ensure you have the necessary drivers/tools installed on the host system. For additional information, please see the wiki page for Hardware Acceleration.

HandBrake Web has three Docker Compose configuration file templates available:

You can either copy/paste the contents of these files into a file called compose.yaml, or run the following commands to download the templates directly to your current directory. All of these templates will guide you to deploy a single server instance, and a single worker instance - both running on the same machine.

wget -O compose.yaml https://raw.githubusercontent.com/TheNickOfTime/handbrake-web/refs/heads/main/compose/compose.base.yaml

wget -O compose.yaml https://raw.githubusercontent.com/TheNickOfTime/handbrake-web/refs/heads/main/compose/compose.intel.yaml

wget -O compose.yaml https://raw.githubusercontent.com/TheNickOfTime/handbrake-web/refs/heads/main/compose/compose.nvidia.yaml

You will want to modify/configure the following options in your compose.yaml:

user: 1000:1000

The container will run as UID 1000 and GID 1000 by default. Depending on your host system/user configuration, you may need to change this in order to avoid permissions issues. You can run the command id on your host system to get the UID/GID of your current user or another user.

You may opt to run the container as root 0:0 to almost certainly bypass any permissions issues, but this is not recommended.

ports:
  - 9999:9999

The server will be accessible on port 9999 by default. You may change the left-hand side of this statement if you have a conflicting service already using this port.

volumes:
  - /path/to/your/data:/data
  - /path/to/your/media:/video

HandBrake Web expects paths to be mapped to /data and /video on the server, and /video on workers. Please update the left-hand side of these mappings to reflect where you wish to have application data stored. It is not recommended to store this data relative to your compose file.

The same media must be mapped to /video across the server and all worker instances. See here for more information.

environment:
  - WORKER_ID=handbrake-worker
  - SERVER_URL=handbrake-server
  - SERVER_PORT=9999

In your worker configuration, ensure the following environment variables are properly configured:

• WORKER_ID - This must be unique and not used by any other worker connected to your server.
• SERVER_URL & SERVER_PORT - If your worker is not on the same host device as your server, you will need to change these to reflect external access. Prefix with https:// if using TLS/SSL.

At this point, you should be good to go. Run the following command:

docker compose pull && docker compose up -d

This will first pull the images (based on the tag latest), then start the containers with the configuration you provided via compose.yaml. You should be able to access the HandBrake Web web interface in the browser of your choice at http://<your-server-ip>:9999 if you did not change the port mapping!

Please see the wiki page on Hardware Acceleration for more information.

In order to access HandBrake Web via URL, rather than IP, it is recommended to get setup with a reverse proxy. Some projects that I have used to accomplish this are:

• NGINX Proxy Manager - Simple, straight-forward setup and configuration.
• Traefik - Integrates well with Docker, but has a more complicated initial setup.

I've seen others recommend Caddy, SWAG, and plain ol' NGINX - but I have not used these methods.

To run additional workers, simply launch additional worker container instances on different machines by omitting the handbrake-server service from the example compose file. Reminder - It is recommended to run only one worker instance per machine, as a single worker will very likely push most CPUs to 100% utilization during encoding.

Because of this, your server instance must be reachable outside of the machine it is running on. In most cases the port mapping should make this work, but if you are running an additional firewall, ets. please configure accordingly.