Skip to content

DOCKER_SETUP.md

Latest commit

 

History

History
284 lines (217 loc) · 7.75 KB

DOCKER_SETUP.md

File metadata and controls

284 lines (217 loc) · 7.75 KB

Docker Setup

This file covers how to set up vertd using Docker.

Caution

Hardware acceleration under Docker Desktop on Windows and macOS is unsupported. It might work by manually selecting the GPU vendor, but you're on your own. Good luck.

For NVIDIA users

You'll need to install the NVIDIA Container Toolkit and configure Docker to use the NVIDIA Container Runtime by running:

$ sudo nvidia-ctk runtime configure --runtime=docker
$ sudo systemctl restart docker

Note

The commands above assume you're not running Docker in rootless mode. If you are, check the NVIDIA documentation for more details.

Building an image

Clone the repository:

$ git clone https://github.com/VERT-sh/vertd
$ cd vertd/

Then, run the following command to build a Docker image for vertd with the ghcr.io/vert-sh/vertd:latest tag:

$ docker build -t ghcr.io/vert-sh/vertd:latest .

Manually

In any case, your docker run command should at least have the following parameters:

$ docker run -d \
    --name vertd \
    --restart=unless-stopped \
    -p 24153:24153 \
    ghcr.io/vert-sh/vertd:latest

Intel and AMD GPUs

If you have an Intel or AMD GPU, you'll need to add the --device=/dev/dri:/dev/dri parameter to your docker run command. It should end up looking something like this:

$ docker run -d \
    --name vertd \
    --restart=unless-stopped \
+   --device=/dev/dri:/dev/dri \
    -p 24153:24153 \
    ghcr.io/vert-sh/vertd:latest

Tip

If your GPU device is not at /dev/dri/renderD128 (the default), you can specify a custom VA-API device path using the VERTD_VAAPI_DEVICE_PATH environment variable or the --vaapi-device CLI argument. See VA-API device path configuration for more details.

NVIDIA GPUs

If you have a NVIDIA GPU, you'll need to add the --runtime=nvidia and --gpus all parameters to your docker run command. It should end up looking something like this:

$ docker run -d \
    --name vertd \
    --restart=unless-stopped \
+   --runtime=nvidia \
+   --gpus all \
    -p 24153:24153 \
    ghcr.io/vert-sh/vertd:latest

With Compose (recommended)

There's a docker-compose.yml file in this repository which you can use to easily get started.

Intel and AMD GPUs

If you're using an Intel or AMD GPU, add the following to the vertd service in your Docker Compose file:

devices:
  - /dev/dri

Assuming you're using the docker-compose.yml file from this repository, you should also remove the following NVIDIA specific settings from it:

- runtime: nvidia
- deploy:
-   resources:
-     reservations:
-       devices:
-         - driver: nvidia
-           count: all
-           capabilities: [gpu]
Full docker-compose.yml example for Intel/AMD GPUs 
services:
  vertd:
    image: ghcr.io/vert-sh/vertd:latest
    container_name: vertd
    restart: unless-stopped
    ports:
      - "24153:24153"
    devices:
      - /dev/dri

Finally, run the following command to bring the stack up:

docker compose up

If you see a detected an Intel GPU or detected an AMD GPU message, you should be ready to go.

NVIDIA GPUs

If you're using the docker-compose.yml file we provide in this repository, you shouldn't need to do any changes. Otherwise, add the following settings to the vertd service:

+ runtime: nvidia
+ deploy:
+   resources:
+     reservations:
+       devices:
+         - driver: nvidia
+           count: all
+           capabilities: [gpu]

Finally, bring the stack up by using:

docker compose up
Full docker-compose.yml example for NVIDIA GPUs 
services:
  vertd:
    image: ghcr.io/vert-sh/vertd:latest
    container_name: vertd
    restart: unless-stopped
    ports:
      - "24153:24153"
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

If you see a detected a NVIDIA GPU message without any warnings, you should be ready to go.

Manual GPU selection

If the automatic GPU detection doesn't work correctly, you can manually force vertd to use a specific GPU vendor by setting the VERTD_FORCE_GPU environment variable.

Valid values for VERTD_FORCE_GPU are: nvidia, amd, intel, apple, or cpu.

For Docker Compose configurations, add:

environment:
  - VERTD_FORCE_GPU=nvidia

For docker run commands, use:

$ docker run -d \
    --name vertd \
    --restart=unless-stopped \
+   -e VERTD_FORCE_GPU=nvidia \
    -p 24153:24153 \
    ghcr.io/vert-sh/vertd:latest

CPU-only mode

If you don't have a GPU or want to use CPU rendering (software encoding), you can set VERTD_FORCE_GPU=cpu:

environment:
  - VERTD_FORCE_GPU=cpu

Or with docker run:

$ docker run -d \
    --name vertd \
    --restart=unless-stopped \
+   -e VERTD_FORCE_GPU=cpu \
    -p 24153:24153 \
    ghcr.io/vert-sh/vertd:latest

Note

CPU rendering uses software encoders (like libx264) which are significantly slower than GPU-accelerated encoding. This mode is useful for systems without GPU support or for testing purposes.

Automatic CPU fallback

If GPU detection fails for any reason, vertd will automatically fall back to CPU rendering. For Docker users, you'll see a warning message in the logs similar to:

[WARN] *******
[WARN] you're running vertd on a docker container, but no GPU was detected.
[WARN] this usually is because you're running Docker under WSL or because
[WARN] you are not passing the GPU device correctly.
[WARN]
[WARN] if this doesn't seem right, make sure to provide the following info when
[WARN] asking for help:
[WARN] - adapter name: <adapter name>
[WARN] - adapter vendor: 0x<VENDOR_ID>
[WARN] - backend: <backend>
[WARN] - device ID: <device id>
[WARN] - device type: <device type>
[WARN] - driver: <driver>
[WARN] - driver info: <driver info>
[WARN]
[WARN] vertd will fall back to CPU rendering to ensure conversions can still proceed.
[WARN] *******

This ensures that vertd continues to work even on systems without GPU support, albeit slower than with GPU acceleration.

VA-API device path configuration

By default, vertd uses /dev/dri/renderD128 as the VA-API device path for Intel and AMD GPUs on Linux. If your system uses a different device path (e.g., /dev/dri/renderD129), you can configure it by setting VERTD_VAAPI_DEVICE_PATH to your device path:

environment:
  - VERTD_VAAPI_DEVICE_PATH=/dev/dri/renderD129

Or with docker run:

$ docker run -d \
    --name vertd \
    --restart=unless-stopped \
    --device=/dev/dri:/dev/dri \
+   -e VERTD_VAAPI_DEVICE_PATH=/dev/dri/renderD129 \
    -p 24153:24153 \
    ghcr.io/vert-sh/vertd:latest

Important

This setting only affects Intel and AMD GPUs on Linux, which use VA-API for hardware acceleration. It has no effect on NVIDIA GPUs, Apple GPUs, or other platforms.