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

@@ -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 \

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

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
 

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 |