Docker Setup

This file covers how to set up vertd using Docker.

• For NVIDIA users
• Building an image
• Manually
  • Intel and AMD GPUs
  • NVIDIA GPUs
• With Compose (recommended)
  • Intel and AMD GPUs
  • NVIDIA GPUs
• Manual GPU selection
• CPU-only mode
  • Automatic CPU fallback
• VA-API device path configuration

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

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

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]

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

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

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