Docker for CLI

Step-by-step guide to running the VIESUS CLI in a GPU-enabled Ubuntu Docker container with NVIDIA GPU support.

This guide walks through building a minimal Ubuntu-based Docker image with the VIESUS CLI and NVIDIA GPU support. Use it as a starting point — not a complete production setup.

Prerequisites:

• Ubuntu 22.04 host
• NVIDIA driver with CUDA 12.6 support or newer (nvidia-smi must work)
• Docker installed
• VIESUS .deb package downloaded from transfer.viesus.com

---

1

Install Docker

sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce

# Allow running Docker without sudo
sudo usermod -aG docker $USER
su - $USER

Verify:

docker -v

2

Install NVIDIA Container Toolkit

Follow the official NVIDIA guide.

Verify GPU access in Docker:

docker run -it --gpus all nvidia/cuda:12.6.0-runtime-ubuntu22.04 nvidia-smi

Use the runtime image variant, not base. The base image does not include all required CUDA runtime libraries.

3

Prepare the build context

mkdir viesusdocker
cd viesusdocker

# Copy the VIESUS deb package into the build context
cp ~/viesus_<VERSION>_amd64.deb .

4

Create the Dockerfile

FROM nvidia/cuda:12.6.0-runtime-ubuntu22.04

COPY ./viesus_<VERSION>_amd64.deb /

ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=Etc/UTC

RUN apt-get update && apt-get install -y --no-install-recommends wget
RUN dpkg -i /viesus_<VERSION>_amd64.deb
RUN apt-get install -y libnuma-dev

libnuma-dev is required for the VIESUS library on Ubuntu 22.04.

The nvidia/cuda base image tag (12.6.0-runtime-ubuntu22.04) must match your host NVIDIA driver. Check the NVIDIA Container Registry for available tags and replace 12.6.0 as needed.

5

Build the image

docker build -t viesusdocker .

6

Prepare images and configuration

Create a shared folder on the host that will be mounted into the container:

mkdir -p ~/testimages

# Create an image list using container-side paths
cat > ~/testimages/images.lst << 'EOF'
/mnt/mydata/image1.jpg
/mnt/mydata/image2.jpg
/mnt/mydata/image3.jpg
EOF

Create ~/testimages/viesusini.json with your enhancement configuration. Example for 4× AI upscaling with Face Reconstruction:

{
  "Config": {
    "Enhancemode": 1,
    "NoiseRedMode": 1,
    "FDmode": 1,
    "FRmode": 1,
    "ARmode": 1,
    "SHPmode": 1
  },
  "Resize": {
    "ResizeOn": 1,
    "ResizeMode": 5,
    "ResizeFactor": 4.0,
    "SupResThresh": 1.0,
    "ResizeFacDetMode": 0
  },
  "Other": {
    "JpegComprQuality": 95
  }
}

7

Run the CLI

Process a list of images:

docker run \
  --mount "type=bind,source=$HOME/testimages,target=/mnt/mydata" \
  --rm --gpus all viesusdocker \
  /usr/local/viesus/viesus \
  -g "YOUR-GUID-HERE" \
  -p /mnt/mydata/viesusini.json \
  -s \
  -l /mnt/mydata/images.lst

Process a single image:

docker run \
  --mount "type=bind,source=$HOME/testimages,target=/mnt/mydata" \
  --rm --gpus all viesusdocker \
  /usr/local/viesus/viesus \
  -g "YOUR-GUID-HERE" \
  -p /mnt/mydata/viesusini.json \
  -s \
  -f /mnt/mydata/image1.jpg

Open a shell for debugging:

docker run -it --gpus all viesusdocker bash

---

Production considerations

Concern	Recommendation
GUID security	Pass the GUID via an environment variable or Docker secret rather than hardcoding it in scripts
Output volume	Mount a dedicated output volume; don't write to the same path as input
Parallelism	Scale by running multiple containers (or instances) rather than more threads per instance
Image list generation	Generate the image list outside the container and mount it in; avoid running find inside the container
Restart policy	Use --restart unless-stopped for long-running hotfolder containers
Log collection	Pipe stdout/stderr to your log aggregator; the CLI writes processing results to .res files