From c5c12376fc96ba130319dc5cbbe60e5bb84bf7bd Mon Sep 17 00:00:00 2001
From: stroblme <stroblme@posteo.de>
Date: Thu, 15 Oct 2026 15:55:02 +0200
Subject: [PATCH] Opt-in WITH_FFMPEG build arg installs Debian's ffmpeg in the
 backend image

Off by default, since it adds about 400 MB. Documented with the clip recipe
and in the configuration reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WgBfkm4rCmtd1T4vHWjEPx
---
 backend/Dockerfile              | 10 ++++++++++
 docker/compose.yml              |  3 +++
 docs/code/nodes.md              |  7 ++++---
 docs/reference/configuration.md |  6 ++++++
 4 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/backend/Dockerfile b/backend/Dockerfile
index 93f978e..290b454 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -26,6 +26,16 @@ ENV PATH="/app/.venv/bin:$PATH"
 # environment somebody already works in is the case that adopts instead.
 ENV NODE_VENV=managed
 
+# ffmpeg for node code that transcodes, such as the clip recipe in
+# docs/code/nodes.md. Off by default: Debian's package and what it pulls in add
+# about 400 MB. Set WITH_FFMPEG=true in .env and rebuild to include it.
+ARG WITH_FFMPEG=false
+RUN if [ "$WITH_FFMPEG" = true ]; then \
+      apt-get update \
+      && apt-get install -y --no-install-recommends ffmpeg \
+      && rm -rf /var/lib/apt/lists/*; \
+    fi
+
 # Install dependencies
 # Ref: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
 RUN --mount=type=cache,target=/root/.cache/uv \
diff --git a/docker/compose.yml b/docker/compose.yml
index f78ed61..93eabfc 100644
--- a/docker/compose.yml
+++ b/docker/compose.yml
@@ -163,6 +163,9 @@ services:
     build:
       context: ..
       dockerfile: backend/Dockerfile
+      args:
+        # Opt-in: ffmpeg costs the image about 400 MB (backend/Dockerfile).
+        - WITH_FFMPEG=${WITH_FFMPEG:-false}
     labels:
       - autoheal=true
       - traefik.enable=true
diff --git a/docs/code/nodes.md b/docs/code/nodes.md
index 498a70e..cc86c81 100644
--- a/docs/code/nodes.md
+++ b/docs/code/nodes.md
@@ -150,9 +150,10 @@ def process(clip):
 ```
 
 Use it only for clips headed for such a panel. Browsers play the originals,
-and the result plays there too, just smaller. The Docker image does not ship
-`ffmpeg` yet, so the node runs only where `ffmpeg` is on the `PATH`, such as a
-[remote worker](workers.md).
+and the result plays there too, just smaller. The node needs `ffmpeg` on the
+`PATH`. The Docker image includes it only when built with
+[`WITH_FFMPEG=true`](../reference/configuration.md#image-options) in `.env`.
+Otherwise run the node on a [remote worker](workers.md) that has it.
 
 ## Printing
 
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index f135896..1f44773 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -100,6 +100,12 @@ to the backend. An empty value needs that proxy when the frontend and backend
 are served separately. See [facility automation](../getting-started/facility-automation.md#run-it-long-term)
 for deployment settings.
 
+## Image options
+
+`WITH_FFMPEG=true` in `.env` installs `ffmpeg` into the backend image on the
+next build, for node code that transcodes video. It is off by default because
+it adds about 400 MB.
+
 ## Environment
 
 | Variable | Default | Purpose |