feat: add GPU and CPU variants

Author: hcastc00

.dockerignore

@@ -1,6 +1,7 @@
 *
 !Dockerfile
 !avatar.png
+!entrypoint.sh
 !manager.mjs
 !qvac.config.mjs
 !ui/

.github/workflows/auto_check.yml

@@ -11,4 +11,7 @@ on:
 jobs:
   bump-upstream:
     uses: dappnode/workflows/.github/workflows/bump-upstream.yml@master
+    with:
+      use_variants: true
+      variants_dir: package_variants
     secrets: inherit

.github/workflows/build.yml

@@ -11,4 +11,6 @@ on:
 jobs:
   build:
     uses: dappnode/workflows/.github/workflows/dappnode-build-hash.yml@master
+    with:
+      all_variants: true
     secrets: inherit

.github/workflows/main.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Log in to GitHub Container Registry
         run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
       - name: Publish
-        run: npx @dappnode/dappnodesdk publish patch --github_release --timeout 1h --content_provider=http://10.200.200.7:5001 --eth_provider=https://web3.dappnode.net
+        run: npx @dappnode/dappnodesdk publish patch --all-variants --github_release --timeout 1h --content_provider=http://10.200.200.7:5001 --eth_provider=https://web3.dappnode.net
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DEVELOPER_ADDRESS: "0xf35960302a07022aba880dffaec2fdd64d5bf1c1"

Dockerfile

@@ -1,11 +1,11 @@
-FROM node:22-bookworm-slim
+FROM node:22-trixie-slim
 
 ARG UPSTREAM_VERSION
 ARG TARGETARCH
 
 RUN apt-get update \
     && apt-get install -y --no-install-recommends \
-       ca-certificates ffmpeg libatomic1 libvulkan1 mesa-vulkan-drivers tini \
+       ca-certificates ffmpeg libatomic1 libvulkan1 mesa-vulkan-drivers tini vulkan-tools \
     && rm -rf /var/lib/apt/lists/* \
     && npm install --global --no-audit --no-fund "@qvac/cli@${UPSTREAM_VERSION}" \
     && chmod 0755 /usr/local/lib/node_modules/@qvac/cli/node_modules/bare-runtime-*/bin/bare \
@@ -26,18 +26,19 @@ WORKDIR /app
 
 COPY qvac.config.mjs /app/qvac.config.mjs
 COPY manager.mjs /app/manager.mjs
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 COPY ui /app/ui
 COPY avatar.png /app/ui/avatar.png
 
 RUN mkdir -p /data/config /data/models /data/runtime \
-    && chown -R node:node /app /data
+    && chown -R node:node /app /data \
+    && chmod 0755 /usr/local/bin/entrypoint.sh
 
 ENV HOME=/data \
     NODE_ENV=production \
     QVAC_VERSION=${UPSTREAM_VERSION}
 
-USER node
-
 EXPOSE 8080 11434
 
-ENTRYPOINT ["/usr/bin/tini", "--", "node", "/app/manager.mjs"]
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+CMD ["node", "/app/manager.mjs"]

README.md

@@ -4,21 +4,30 @@ This package runs the official [QVAC](https://qvac.tether.io/) CLI as a private,
 
 The image includes QVAC's upstream worker and native Linux addons. The built-in configuration UI provides a searchable model library and manages QVAC settings without shell or File Manager access.
 
-## Endpoints
+## Variants
 
-- Configuration UI: `http://qvac.dappnode:8080`
-- OpenAI-compatible API: `http://qvac.dappnode:11434/v1`
-- Interactive API documentation: `http://qvac.dappnode:11434/docs`
+The repository publishes two packages from the same image and configuration:
+
+| Variant | Package | Hostname | Hardware behavior |
+| --- | --- | --- | --- |
+| CPU | `qvac.dnp.dappnode.eth` | `qvac.dappnode` | Does not request a GPU and runs on every DAppNode |
+| GPU | `qvac-gpu.dnp.dappnode.eth` | `qvac-gpu.dappnode` | Reserves every GPU exposed by Docker's GPU/CDI runtime |
+
+On either hostname, the configuration UI uses port `8080`, the OpenAI-compatible API uses `/v1` on port `11434`, and the interactive API documentation is at `/docs` on port `11434`.
 
 ## Defaults
 
-- QVAC CLI: `0.11.0`
+- QVAC CLI: `0.12.0`
 - Model: `QWEN3_600M_INST_Q4`
 - API alias: `qwen3-600m`
 - Model cache: `/data/models`
 - Configuration: `/data/config/qvac.config.json`
 
-CPU inference is supported on Linux. The package does not request host GPU devices, so larger models and image generation can be slow. Model downloads, configuration, and backups persist in the `data` volume.
+Model downloads, configuration, and backups persist in the `data` volume.
+
+## CPU and GPU behavior
+
+Docker treats a Compose GPU reservation as a hard requirement and fails before starting the container when no GPU vendor is available. The CPU package therefore omits that reservation. The GPU package requests every GPU through Docker's vendor-neutral `gpu` capability and requires a working AMD or NVIDIA container toolkit/CDI configuration. Both variants use the same image, which includes the Vulkan loader, Mesa Vulkan drivers, and `vulkaninfo`.
 
 ## Configuration ownership
 
@@ -28,17 +37,27 @@ The installation wizard is limited to settings that must exist before the packag
 - Optional host mapping for the API port
 - Data-volume location
 
-After installation, use `http://qvac.dappnode:8080` for model selection, aliases, preload/default behavior, engine configuration, logging, download behavior, browser origins, JSON import/export, validation, and backup restore.
+After installation, open port `8080` on your variant's hostname for model selection, aliases, preload/default behavior, engine configuration, logging, download behavior, browser origins, JSON import/export, validation, and backup restore.
 
 ## Development
 
-Build and run locally without IPFS:
+Build and run the CPU variant locally without IPFS:
 
 ```bash
-docker compose build
-docker compose up -d
+docker compose -f docker-compose.yml -f package_variants/cpu/docker-compose.yml build
+docker compose -f docker-compose.yml -f package_variants/cpu/docker-compose.yml up -d
 ```
 
+Confirm that the CPU-safe service is running:
+
+```bash
+docker compose -f docker-compose.yml -f package_variants/cpu/docker-compose.yml ps
+API_PORT=$(docker compose -f docker-compose.yml -f package_variants/cpu/docker-compose.yml port qvac 11434 | sed 's/.*://')
+curl --fail "http://127.0.0.1:${API_PORT}/v1/models"
+```
+
+Use `package_variants/gpu/docker-compose.yml` instead to test the GPU variant on a host where `docker run --rm --gpus all ubuntu:24.04 true` succeeds. CI and the release workflow build and publish both variants with the SDK's `--all-variants` option.
+
 Use `make dev-tar` only when a Docker image tarball is needed for a DAppNode development upload.
 
 ## Upstream

dappnode_package.json

@@ -1,16 +1,15 @@
 {
-  "name": "qvac.dnp.dappnode.eth",
-  "version": "0.1.0",
   "upstream": [
     {
       "repo": "tetherto/qvac",
-      "version": "0.11.0",
+      "version": "0.12.0",
       "arg": "UPSTREAM_VERSION"
     }
   ],
   "shortDescription": "Private multimodal AI with OpenAI-compatible APIs",
-  "description": "Run the complete [QVAC](https://qvac.tether.io/) CLI locally on DAppNode as an OpenAI-compatible AI provider. QVAC keeps prompts and inference on your own hardware. Its HTTP server supports text generation, embeddings, RAG, image and video generation, transcription, text-to-speech, and audio translation when the corresponding models are configured.\n\nA built-in configuration UI includes a searchable model library, validates and backs up settings, and applies changes without shell access. The QVAC worker reloads independently, so the UI remains available while models download or start. The default configuration serves the compact `QWEN3_600M_INST_Q4` text-generation model as `qwen3-600m`. Downloaded models, custom configuration, and backups are stored in a persistent volume.\n\nThis image includes QVAC's upstream worker and all native Linux addons shipped by the CLI.\n\n- Configuration UI: `http://qvac.dappnode:8080`\n- API: `http://qvac.dappnode:11434/v1`\n- API documentation: `http://qvac.dappnode:11434/docs`\n- CPU inference works on Linux; 4 GB RAM and 5 GB free disk are the upstream minimum recommendations, while larger models require more resources.\n- Set an API key during installation if clients outside your trusted DAppNode network can reach the service.",
+  "description": "Run the complete [QVAC](https://qvac.tether.io/) CLI locally on DAppNode as an OpenAI-compatible AI provider. QVAC keeps prompts and inference on your own hardware. Its HTTP server supports text generation, embeddings, RAG, image and video generation, transcription, text-to-speech, and audio translation when the corresponding models are configured.\n\nA built-in configuration UI includes a searchable model library, validates and backs up settings, and applies changes without shell access. The QVAC worker reloads independently, so the UI remains available while models download or start. The default configuration serves the compact `QWEN3_600M_INST_Q4` text-generation model as `qwen3-600m`. Downloaded models, custom configuration, and backups are stored in a persistent volume.\n\nThis image includes QVAC's upstream worker and all native Linux addons shipped by the CLI. The default package does not reserve a GPU, so it installs and runs on CPU-only DAppNodes.\n\n- Configuration UI: `http://qvac.dappnode:8080`\n- API: `http://qvac.dappnode:11434/v1`\n- API documentation: `http://qvac.dappnode:11434/docs`\n- At least 4 GB RAM and 5 GB free disk are required for the default model; larger models require substantially more RAM and storage.\n- Set an API key during installation if clients outside your trusted DAppNode network can reach the service.",
   "type": "service",
+  "mainService": "qvac",
   "author": "DAppNode Association <admin@dappnode.io> (https://github.com/dappnode)",
   "license": "Apache-2.0",
   "categories": ["AI"],
@@ -40,6 +39,6 @@
     }
   ],
   "warnings": {
-    "onInstall": "Without an API key, QVAC is available without authentication to clients that can reach the DAppNode network. The configuration UI on port 8080 is administrative and should not be exposed publicly. The complete runtime image and configured model downloads can use many GB of storage. Large models may also require substantial RAM and take several minutes to load."
+    "onInstall": "This package runs on CPU-only DAppNodes. CPU inference can be slow, so start with the default compact model before selecting larger models. Without an API key, QVAC is available without authentication to clients that can reach the DAppNode network. The configuration UI on port 8080 is administrative and should not be exposed publicly. The complete runtime image and configured model downloads can use many GB of storage. Large models may also require substantial RAM and take several minutes to load."
   }
 }

docker-compose.yml

@@ -1,12 +1,11 @@
 version: "3.5"
 
 services:
-  qvac.dnp.dappnode.eth:
-    image: "qvac.dnp.dappnode.eth:0.1.0"
+  qvac:
     build:
       context: .
       args:
-        UPSTREAM_VERSION: "0.11.0"
+        UPSTREAM_VERSION: "0.12.0"
     restart: unless-stopped
     volumes:
       - "data:/data"

entrypoint.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+set -eu
+
+node_uid=$(id -u node)
+node_gid=$(id -g node)
+gpu_group_ids=""
+
+for gpu_device in /dev/dri/card* /dev/dri/renderD*; do
+  [ -e "${gpu_device}" ] || continue
+
+  gpu_gid=$(stat -c '%g' "${gpu_device}")
+  [ "${gpu_gid}" != "0" ] || continue
+
+  case ",${gpu_group_ids}," in
+    *,"${gpu_gid}",*) ;;
+    *) gpu_group_ids="${gpu_group_ids:+${gpu_group_ids},}${gpu_gid}" ;;
+  esac
+done
+
+set -- /usr/bin/tini -- "$@"
+
+if [ -n "${gpu_group_ids}" ]; then
+  echo "[entrypoint] Granting QVAC access to GPU group IDs: ${gpu_group_ids}"
+  exec setpriv \
+    --reuid "${node_uid}" \
+    --regid "${node_gid}" \
+    --groups "${gpu_group_ids}" \
+    -- "$@"
+fi
+
+exec setpriv \
+  --reuid "${node_uid}" \
+  --regid "${node_gid}" \
+  --clear-groups \
+  -- "$@"

getting-started.md

@@ -2,12 +2,19 @@
 
 Open the configuration UI after installation:
 
-- Configuration UI: `http://qvac.dappnode:8080`
-- OpenAI-compatible API: `http://qvac.dappnode:11434/v1`
-- Interactive API documentation: `http://qvac.dappnode:11434/docs`
+- CPU package: `qvac.dappnode`
+- GPU package: `qvac-gpu.dappnode`
+
+On the hostname for your installed package, the configuration UI uses port `8080`, the OpenAI-compatible API uses `/v1` on port `11434`, and the interactive API documentation is at `/docs` on port `11434`.
 
 QVAC starts with the compact `qwen3-600m` model. Its first download can take several minutes; later starts reuse the persistent model cache.
 
+## CPU and GPU variants
+
+The `qvac.dnp.dappnode.eth` package does not reserve a GPU and therefore starts on CPU-only DAppNodes. CPU inference is slower and needs enough system RAM for the selected model; begin with `qwen3-600m` before loading larger models.
+
+The `qvac-gpu.dnp.dappnode.eth` package reserves every GPU exposed by Docker. Before installing it, confirm that `docker run --rm --gpus all ubuntu:24.04 true` succeeds on the DAppNode host. Use the CPU package if that check fails.
+
 ## Choose models
 
 1. Open **Models** in the configuration UI.
@@ -23,7 +30,8 @@ Models that do not preload are loaded when first requested. This helps avoid fil
 Use the API key chosen during installation as a Bearer token. Omit the `Authorization` header if no key was configured.
 
 ```bash
-curl http://qvac.dappnode:11434/v1/chat/completions \
+QVAC_HOST=qvac.dappnode # Use qvac-gpu.dappnode for the GPU package
+curl "http://${QVAC_HOST}:11434/v1/chat/completions" \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer YOUR_API_KEY' \
   -d '{