> For the complete documentation index, see [llms.txt](https://docs.viesus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viesus.com/reference/docker/cli.md).

# Docker for CLI

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](https://transfer.viesus.com)

***

{% stepper %}
{% step %}

## Install Docker

```bash
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:

```bash
docker -v
```

{% endstep %}

{% step %}

## Install NVIDIA Container Toolkit

Follow the [official NVIDIA guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).

Verify GPU access in Docker:

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

{% hint style="info" %}
Use the `runtime` image variant, not `base`. The base image does not include all required CUDA runtime libraries.
{% endhint %}
{% endstep %}

{% step %}

## Prepare the build context

```bash
mkdir viesusdocker
cd viesusdocker

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

{% endstep %}

{% step %}

## Create the Dockerfile

```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
```

{% hint style="info" %}
`libnuma-dev` is required for the VIESUS library on Ubuntu 22.04.
{% endhint %}

{% hint style="info" %}
The `nvidia/cuda` base image tag (`12.6.0-runtime-ubuntu22.04`) must match your host NVIDIA driver. Check the [NVIDIA Container Registry](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/cuda) for available tags and replace `12.6.0` as needed.
{% endhint %}
{% endstep %}

{% step %}

## Build the image

```bash
docker build -t viesusdocker .
```

{% endstep %}

{% step %}

## Prepare images and configuration

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

```bash
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:

```json
{
  "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
  }
}
```

{% endstep %}

{% step %}

## Run the CLI

**Process a list of images:**

```bash
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:**

```bash
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:**

```bash
docker run -it --gpus all viesusdocker bash
```

{% endstep %}
{% endstepper %}

***

## Production considerations

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.viesus.com/reference/docker/cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.