From 6c96c22b33560193561bfd7ee11e0e86b8f38e4d Mon Sep 17 00:00:00 2001
From: dtoro <d.toro.v@pm.me>
Date: Thu, 21 May 2026 23:28:21 +0200
Subject: [PATCH] feat(compose): opt-in GPU overlay for VA-API ffmpeg accel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Layer docker-compose.gpu.yml to mount /dev/dri/{card0,renderD128}
into pp-app, add it to render (992) + video (44) groups, and set
PHOTOPRISM_FFMPEG_ENCODER=vaapi. Hosts without a VA-API device just
skip the overlay (`-f docker-compose.yml -f docker-compose.gpu.yml`
becomes opt-in per deploy).

Drops video transcode + thumbnail generation from CPU to the iGPU
where present — large win for HEVC libraries. README documents the
flag; default behavior on the base compose is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md              | 15 +++++++++++++++
 docker-compose.gpu.yml | 24 ++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 docker-compose.gpu.yml

diff --git a/README.md b/README.md
index ccff048..01aa999 100644
--- a/README.md
+++ b/README.md
@@ -115,6 +115,7 @@ Full instructions in [`sidecar/README.md`](sidecar/README.md#dev-iteration-loop-
 .
 ├── docker-compose.yml         base stack: mariadb + photoprism + sidecar
 ├── docker-compose.podman.yml  rootless-podman overlay (keep-id mapping)
+├── docker-compose.gpu.yml     opt-in VA-API GPU passthrough overlay
 ├── .env.example               required env vars (copy to .env)
 ├── mariadb/init/              first-boot SQL: creates mule_sidecar DB + user
 ├── pp/                        PhotoPrism bind-mounted state (storage, import)
@@ -122,4 +123,18 @@ Full instructions in [`sidecar/README.md`](sidecar/README.md#dev-iteration-loop-
 └── web/                       SvelteKit frontend
 ```
 
+## GPU video acceleration (optional)
+
+Hosts with a VA-API-capable GPU (Intel iGPU, AMD APU, etc.) can layer
+[`docker-compose.gpu.yml`](docker-compose.gpu.yml) to hand `/dev/dri/*`
+to PhotoPrism and switch ffmpeg to hardware encode/decode — a large
+perf win for video thumbnails and HEVC→H.264 transcodes:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
+```
+
+Set `PP_FFMPEG_ENCODER=vaapi` in `.env` (default for the overlay). Verify
+with `docker exec pp-app photoprism show config | grep -i ffmpeg`.
+
 [pp]: https://photoprism.app/
diff --git a/docker-compose.gpu.yml b/docker-compose.gpu.yml
new file mode 100644
index 0000000..58b86ed
--- /dev/null
+++ b/docker-compose.gpu.yml
@@ -0,0 +1,24 @@
+# Overlay for hosts with a VA-API-capable GPU passed through (Intel
+# QSV, AMD VCN/VCE, any VA-API driver). PhotoPrism's :latest image
+# ships VA-API-enabled ffmpeg; this file just wires the device + group
+# membership + encoder selection. Layered in by the deploy script on
+# hosts where /dev/dri/renderD128 exists.
+#
+# Usage:
+#   docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
+
+services:
+  photoprism:
+    devices:
+      - /dev/dri/renderD128:/dev/dri/renderD128
+      - /dev/dri/card0:/dev/dri/card0
+    # Match host GIDs (render=992, video=44 on Debian). PhotoPrism's
+    # container user (PP_UID:PP_GID, typically 33:10000) is not in
+    # these groups by default; group_add grants access to the device
+    # nodes without changing the primary user.
+    group_add:
+      - "992"
+      - "44"
+    environment:
+      PHOTOPRISM_FFMPEG_ENCODER: ${PP_FFMPEG_ENCODER:-vaapi}
+      PHOTOPRISM_FFMPEG_BITRATE: ${PP_FFMPEG_BITRATE:-32}