Docker for Node.js

Run the VIESUS Node.js module in a GPU-enabled Docker container. Dockerfile, build, and run instructions for Linux production deployments.

Linux Only

The VIESUS Node.js module is available on Linux only.

Containerizing the Node.js module follows the same foundation as the CLI Docker setup — the VIESUS .deb packages are installed inside the container, then the npm module is linked from the installed location.

---

Prerequisites

• Docker Engine installed on the host
• NVIDIA Container Toolkit installed (for GPU support)
• VIESUS .deb packages (.deb files must be in your build context)

If you do not already have the NVIDIA Container Toolkit:

# Add NVIDIA Container Toolkit repository
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

---

Build context

Prepare the directory you'll build from:

viesus-node-docker/
├── Dockerfile
├── viesus-redist_<VERSION>_amd64.deb
├── viesus_<VERSION>_amd64.deb
├── viesus-license_<VERSION>_amd64.deb
├── package.json
├── server.js            # or your application entry point
├── worker.js
└── viesusini.json

---

Dockerfile

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

ENV DEBIAN_FRONTEND=noninteractive

# System dependencies
RUN apt-get update && apt-get install -y \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Install VIESUS packages
COPY viesus-redist_<VERSION>_amd64.deb \
     viesus_<VERSION>_amd64.deb \
     viesus-license_<VERSION>_amd64.deb /tmp/
RUN dpkg -i /tmp/viesus-redist_<VERSION>_amd64.deb \
            /tmp/viesus_<VERSION>_amd64.deb \
            /tmp/viesus-license_<VERSION>_amd64.deb && \
    apt-get install -f -y && \
    rm /tmp/*.deb

# Install Node.js 18
RUN curl -sL https://deb.nodesource.com/setup_18.x | bash - && \
    apt-get install -y nodejs && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Install npm dependencies (including viesus native module)
COPY package.json ./
RUN npm install /usr/local/viesus/node-viesus && \
    npm install node-worker-threads-pool --save

# Copy application files
COPY worker.js server.js viesusini.json ./

EXPOSE 3000

ENV UV_THREADPOOL_SIZE=16

CMD ["node", "server.js"]

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.

---

Build the image

docker build -t viesus-node:latest .

---

Run the container

CPU mode

docker run -d \
  --name viesus-node \
  -p 3000:3000 \
  -e VIESUS_GUID="your-guid-here" \
  -e UV_THREADPOOL_SIZE=16 \
  viesus-node:latest

GPU mode

docker run -d \
  --name viesus-node \
  --gpus all \
  -p 3000:3000 \
  -e VIESUS_GUID="your-guid-here" \
  -e UV_THREADPOOL_SIZE=4 \
  viesus-node:latest

When using GPUs, set UV_THREADPOOL_SIZE to the number of GPUs, not the number of CPU cores. See GPU Scaling.

---

Passing the GUID securely

Never hardcode the GUID in the Dockerfile or application code. Pass it at runtime:

# Directly
docker run -e VIESUS_GUID="your-guid-here" ...

# From an env file
docker run --env-file .env ...

# Docker secret (Swarm/Compose)
docker secret create viesus_guid ./guid.txt

Read the GUID in your application:

const pool = new StaticPool({
  size: Number(process.env.UV_THREADPOOL_SIZE) || 4,
  task: './worker.js',
  workerData: process.env.VIESUS_GUID
});

---

Docker Compose example

version: '3.8'

services:
  viesus-node:
    build: .
    ports:
      - "3000:3000"
    environment:
      - VIESUS_GUID=${VIESUS_GUID}
      - UV_THREADPOOL_SIZE=16
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

Run with:

VIESUS_GUID="your-guid-here" docker-compose up -d

---

Production considerations

Topic	Recommendation
Image size	Use multi-stage builds to reduce final image size; the CUDA runtime base is large
GUID security	Pass via environment variable or secret manager — never bake into the image
Graceful shutdown	Handle SIGTERM to allow in-flight requests to complete before the pool closes
Health check	Add a lightweight GET /health endpoint that returns 200; use it for readiness probes
Logging	Stream stdout/stderr — Docker captures it; ship to your log aggregator
GPU reservation	Use --gpus all or specify by device ID if only some GPUs should be used