Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(renderer-service): image, RunPod templates, compose and docs (phase 8)

okanaslbae673350710
diff --git a/.github/workflows/renderer-image.yml b/.github/workflows/renderer-image.yml
new file mode 100644
index 00000000..c20952a7
--- /dev/null
+++ b/.github/workflows/renderer-image.yml
@@ -0,0 +1,83 @@
+# Builds and publishes the renderer worker image (apps/renderer-service).
+# ghcr.io/gatewai-dev/framefields-renderer:<version> (slim)
+# ghcr.io/gatewai-dev/framefields-renderer:<version>-full (with a C/C++ toolchain)
+# Runs on tags renderer-v*, or by hand (publish=false only builds).
+name: renderer-image
+
+on:
+ push:
+ tags: ["renderer-v*"]
+ pull_request:
+ paths:
+ - "apps/renderer-service/**"
+ - "packages/**"
+ - "nodes/**"
+ - "pnpm-lock.yaml"
+ workflow_dispatch:
+ inputs:
+ publish:
+ description: Push to GHCR
+ type: boolean
+ default: false
+
+permissions:
+ contents: read
+ packages: write
+
+env:
+ IMAGE: ghcr.io/${{ github.repository_owner }}/framefields-renderer
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ cache: pnpm
+ - run: sudo apt-get update && sudo apt-get install -y git-lfs ffmpeg
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm exec turbo run build --filter=@framefields/renderer-service...
+ - run: pnpm --filter @framefields/renderer-service typecheck
+ # GPU tests are skipped here (FF_GPU_TESTS unset); run them on a GPU host.
+ - run: pnpm --filter @framefields/renderer-service test
+ - run: apps/renderer-service/deploy/known-hosts.sh
+
+ image:
+ needs: test
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ variant: [slim, full]
+ steps:
+ - uses: actions/checkout@v4
+ - id: meta
+ run: |
+ version=$(jq -r .version apps/renderer-service/package.json)
+ suffix=$([ "${{ matrix.variant }}" = full ] && echo "-full" || echo "")
+ echo "tags=${IMAGE}:${version}${suffix},${IMAGE}:latest${suffix}" >> "$GITHUB_OUTPUT"
+ - uses: docker/setup-buildx-action@v3
+ - uses: docker/login-action@v3
+ if: github.event_name != 'pull_request'
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+ - uses: docker/build-push-action@v6
+ with:
+ context: .
+ file: apps/renderer-service/Dockerfile
+ platforms: linux/amd64
+ build-args: VARIANT=${{ matrix.variant }}
+ tags: ${{ steps.meta.outputs.tags }}
+ push: ${{ startsWith(github.ref, 'refs/tags/renderer-v') || inputs.publish == true }}
+ load: ${{ matrix.variant == 'slim' }}
+ cache-from: type=gha,scope=renderer-${{ matrix.variant }}
+ cache-to: type=gha,mode=max,scope=renderer-${{ matrix.variant }}
+ - name: Smoke test (no GPU; checks the image boots its config and tools)
+ if: matrix.variant == 'slim'
+ run: |
+ tag=$(echo "${{ steps.meta.outputs.tags }}" | cut -d, -f1)
+ docker run --rm --entrypoint bash "$tag" -c 'git --version && git lfs version && ffprobe -version | head -1 && test -s apps/renderer-service/deploy/known_hosts'
diff --git a/Dockerfile.renderer b/Dockerfile.renderer
deleted file mode 100644
index 7c1fa403..00000000
--- a/Dockerfile.renderer
+++ /dev/null
@@ -1,104 +0,0 @@
-# Stage 0: Base setup
-FROM node:24-bookworm-slim AS base
-WORKDIR /app
-ENV NODE_ENV=production
-
-# Install basic dynamic loading and SSL requirements
-RUN apt-get update && apt-get install -y openssl && rm -rf /var/lib/apt/lists/*
-ENV GRPC_POLL_STRATEGY=epoll1
-
-# Stage 1: Pruner
-FROM base AS pruner
-RUN npm install -g turbo
-COPY turbo.json package.json pnpm-workspace.yaml pnpm-lock.yaml ./
-COPY packages/ packages/
-COPY apps/ apps/
-COPY nodes/ nodes/
-# Prune `@framefields/renderer-service` and all dynamically discovered node packages
-RUN NODE_PACKAGES=$(node -e "const fs = require('fs'); const dirs = fs.readdirSync('nodes'); const names = dirs.filter(d => fs.statSync('nodes/'+d).isDirectory()).map(d => { try { return require('./nodes/'+d+'/package.json').name; } catch(e) { return null; } }).filter(Boolean); console.log(names.join(' '));") && \
- turbo prune @framefields/renderer-service $NODE_PACKAGES --docker
-
-# Stage 2: Builder
-FROM base AS builder
-
-# Install build dependencies for native Node modules (headless-gl, sharp, skia-canvas, webgpu)
-RUN apt-get update && apt-get install -y --no-install-recommends \
- build-essential git ca-certificates pkg-config python3 \
- libxi-dev libglu1-mesa-dev libglew-dev libgl1-mesa-dev \
- libvulkan-dev libfontconfig1-dev \
- && ln -s /usr/bin/python3 /usr/bin/python \
- && rm -rf /var/lib/apt/lists/*
-
-COPY --from=pruner /app/out/json/ .
-COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
-
-RUN corepack enable && \
- pnpm config set package-import-method copy && \
- pnpm install --frozen-lockfile
-
-COPY --from=pruner /app/out/full/ .
-
-ENV NODE_OPTIONS="--max-old-space-size=6144"
-
-# Build all packages, services and nodes
-RUN pnpm exec turbo run build
-
-# Prune development dependencies
-RUN pnpm config set package-import-method copy && \
- pnpm install --prod --frozen-lockfile
-
-# Install target-specific Linux native bindings for @napi-rs/webcodecs directly inside the container
-RUN pnpm --filter=@framefields/renderer add @napi-rs/webcodecs-linux-x64-gnu @napi-rs/webcodecs-linux-arm64-gnu
-
-# Native module rebuilds for target Linux architecture across all workspace packages
-RUN pnpm rebuild -r sharp skia-canvas webgpu gl @napi-rs/webcodecs mediabunny
-
-# Explicitly ensure skia.node prebuilt native binary is downloaded for skia-canvas
-RUN find /app/node_modules -name "prebuild.mjs" -path "*/skia-canvas/*" -exec sh -c 'cd "$(dirname {})/.." && node lib/prebuild.mjs download --or-compile' \;
-
-# Assert skia.node exists in node_modules to fail build early if missing
-RUN find /app/node_modules -name "skia.node" | grep skia.node || (echo "ERROR: skia.node missing!" && exit 1)
-
-# Clean up build caches and temporary files to minimize image layer size
-RUN find /app -type d \( -name ".turbo" -o -name ".cache" \) -exec rm -rf {} + 2>/dev/null || true && \
- find /app -name "*.tsbuildinfo" -delete 2>/dev/null || true && \
- rm -rf /root/.local /root/.cache /root/.npm /tmp/*
-
-# Stage 3: Runner
-FROM base AS runner
-
-# Install runtime dependencies for canvas/rendering, OpenGL/Vulkan, xvfb, ffmpeg, and Python
-RUN apt-get update && apt-get install -y --no-install-recommends \
- libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
- libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 \
- libgbm1 libpango-1.0-0 libcairo2 libasound2 \
- ffmpeg xvfb xauth \
- libgl1-mesa-dri libglapi-mesa libegl1 libvulkan1 libfontconfig1 \
- python3 python3-pip python3-venv \
- && mkdir -p /tmp/.X11-unix && chmod 1777 /tmp/.X11-unix \
- && rm -rf /var/lib/apt/lists/*
-
-# Install runpod Python SDK
-RUN pip3 install --no-cache-dir runpod --break-system-packages
-
-# Enable NVIDIA GPU container runtime features inside Docker for Vulkan / hardware acceleration
-ENV NVIDIA_VISIBLE_DEVICES=all
-ENV NVIDIA_DRIVER_CAPABILITIES=graphics,utility,video,compute
-
-RUN groupadd --system --gid 1001 nodejs && \
- useradd --system --uid 1001 -m -g nodejs gatewai
-
-ENV COREPACK_HOME=/home/gatewai/.cache/corepack
-
-WORKDIR /app
-COPY --from=builder --chown=gatewai:nodejs /app .
-COPY --chown=gatewai:nodejs renderer-entrypoint.sh ./
-
-RUN corepack enable && \
- mkdir -p /home/gatewai/.cache/corepack && \
- chown -R gatewai:nodejs /home/gatewai
-
-USER gatewai
-EXPOSE 8082
-
-ENTRYPOINT ["./renderer-entrypoint.sh"]
diff --git a/apps/renderer-service/Dockerfile b/apps/renderer-service/Dockerfile
new file mode 100644
index 00000000..8ac602c2
--- /dev/null
+++ b/apps/renderer-service/Dockerfile
@@ -0,0 +1,109 @@
+# framefields renderer worker (apps/renderer-service/PLAN.md §12).
+#
+# Build from the repo root:
+# docker build -f apps/renderer-service/Dockerfile -t framefields-renderer .
+# docker build -f apps/renderer-service/Dockerfile --build-arg VARIANT=full -t framefields-renderer:full .
+#
+# VARIANT=full adds a C/C++ toolchain for projects whose native dependencies
+# have no prebuilt binaries.
+
+ARG NODE_IMAGE=node:24-bookworm-slim
+
+# ─── Stage 0: base ────────────────────────────────────────────────────────────
+FROM ${NODE_IMAGE} AS base
+WORKDIR /app
+ENV NODE_ENV=production
+RUN apt-get update && apt-get install -y --no-install-recommends openssl \
+ && rm -rf /var/lib/apt/lists/*
+
+# ─── Stage 1: prune the monorepo to the service and its node packages ────────
+FROM base AS pruner
+RUN npm install -g turbo@2
+COPY turbo.json package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY packages/ packages/
+COPY apps/ apps/
+COPY nodes/ nodes/
+RUN NODE_PACKAGES=$(node -e "const fs=require('fs');console.log(fs.readdirSync('nodes').filter(d=>fs.statSync('nodes/'+d).isDirectory()).map(d=>{try{return require('./nodes/'+d+'/package.json').name}catch{return null}}).filter(Boolean).join(' '))") && \
+ turbo prune @framefields/renderer-service $NODE_PACKAGES --docker
+
+# ─── Stage 2: build ──────────────────────────────────────────────────────────
+FROM base AS builder
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ build-essential git ca-certificates pkg-config python3 \
+ libxi-dev libglu1-mesa-dev libglew-dev libgl1-mesa-dev \
+ libvulkan-dev libfontconfig1-dev \
+ && ln -s /usr/bin/python3 /usr/bin/python \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY --from=pruner /app/out/json/ .
+COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
+RUN corepack enable && \
+ pnpm config set package-import-method copy && \
+ pnpm install --frozen-lockfile
+
+COPY --from=pruner /app/out/full/ .
+ENV NODE_OPTIONS="--max-old-space-size=6144"
+# Everything pruned in: node packages are discovered at runtime, not imported.
+RUN pnpm exec turbo run build
+
+RUN pnpm install --prod --frozen-lockfile
+# Linux native bindings for webcodecs, then rebuild native modules for this arch.
+RUN pnpm --filter=@framefields/renderer add @napi-rs/webcodecs-linux-x64-gnu @napi-rs/webcodecs-linux-arm64-gnu
+RUN pnpm rebuild -r sharp skia-canvas webgpu gl @napi-rs/webcodecs mediabunny
+RUN find /app/node_modules -name "prebuild.mjs" -path "*/skia-canvas/*" -exec sh -c 'cd "$(dirname {})/.." && node lib/prebuild.mjs download --or-compile' \;
+RUN find /app/node_modules -name "skia.node" | grep -q skia.node || (echo "ERROR: skia.node missing!" && exit 1)
+
+# Pinned SSH host keys for github.com / gitlab.com / bitbucket.org (§6.5).
+RUN apt-get update && apt-get install -y --no-install-recommends openssh-client \
+ && apps/renderer-service/deploy/known-hosts.sh
+
+RUN find /app -type d \( -name ".turbo" -o -name ".cache" \) -exec rm -rf {} + 2>/dev/null || true && \
+ find /app -name "*.tsbuildinfo" -delete 2>/dev/null || true && \
+ rm -rf /root/.local /root/.cache /root/.npm /tmp/*
+
+# ─── Stage 3: runtime ────────────────────────────────────────────────────────
+FROM base AS runner
+ARG VARIANT=slim
+
+# Rendering (GL/Vulkan/fonts), ffmpeg/ffprobe (output checks), git + LFS +
+# ssh (checkouts), tini (PID 1: forwards signals, reaps git subprocesses),
+# python3 + runpod (serverless shim).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+ libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 \
+ libgbm1 libpango-1.0-0 libcairo2 libasound2 \
+ libgl1-mesa-dri libglapi-mesa libegl1 libvulkan1 libfontconfig1 \
+ ffmpeg xvfb xauth \
+ git git-lfs openssh-client ca-certificates tini \
+ python3 python3-pip \
+ && if [ "$VARIANT" = "full" ]; then \
+ apt-get install -y --no-install-recommends build-essential python3-dev pkg-config; \
+ fi \
+ && mkdir -p /tmp/.X11-unix && chmod 1777 /tmp/.X11-unix \
+ && rm -rf /var/lib/apt/lists/* \
+ && git lfs version
+
+RUN pip3 install --no-cache-dir "runpod>=1.7,<2" --break-system-packages
+
+ENV NVIDIA_VISIBLE_DEVICES=all \
+ NVIDIA_DRIVER_CAPABILITIES=graphics,utility,video,compute \
+ FF_WORK_DIR=/tmp/framefields \
+ RENDERER_PORT=8082
+
+RUN groupadd --system --gid 1001 framefields && \
+ useradd --system --uid 1001 -m -g framefields framefields && \
+ mkdir -p /var/cache/framefields /tmp/framefields && \
+ chown -R framefields:framefields /var/cache/framefields /tmp/framefields
+
+ENV COREPACK_HOME=/var/cache/framefields/corepack
+WORKDIR /app
+COPY --from=builder --chown=framefields:framefields /app .
+RUN corepack enable
+
+USER framefields
+EXPOSE 8082
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=120s --retries=3 \
+ CMD node -e "fetch('http://127.0.0.1:'+(process.env.RENDERER_PORT||8082)+'/health').then(r=>process.exit(r.status===200?0:1),()=>process.exit(1))"
+
+ENTRYPOINT ["/usr/bin/tini", "-g", "--", "apps/renderer-service/docker/entrypoint.sh"]
diff --git a/apps/renderer-service/PLAN.md b/apps/renderer-service/PLAN.md
index c0469773..82e89b3c 100644
--- a/apps/renderer-service/PLAN.md
+++ b/apps/renderer-service/PLAN.md
@@ -476,7 +476,7 @@ The service no longer uses `S3StorageService` from `@framefields/server-utils`,
## 12. Image, RunPod template, docs
-**Image** (`Dockerfile.renderer`, renamed to `apps/renderer-service/Dockerfile`, with the build context still at the repo root):
+**Image** (`apps/renderer-service/Dockerfile`, formerly `Dockerfile.renderer`; the build context is still the repo root):
- **Runtime packages added:** `git`, `git-lfs`, `openssh-client`, `ca-certificates`, `tini` (PID 1, reaps git and install subprocesses), `jq`. Corepack is pre-warmed for pnpm, yarn and npm, and `tsx` ships in the service's prod dependencies (its `tsImport` API is used in-process).
- **Two variants:**
@@ -538,10 +538,14 @@ Each phase is its own PR-sized step with tests.
- CLI `--job-file` / `--job -` with `--result-file`. Exit codes: 0 completed, 1 failed, 2 bad invocation or job.
- Server and CLI share `worker/boot.ts`.
- Also done here: cache eviction (§6.4, `worker/janitor.ts`). It runs between jobs (at most every 5 min), and on demand when the LFS disk preflight finds too little space.
-8. **Image + template + compose + docs.**
- - Release workflow.
- - GPU smoke test: render the fixture repo on a RunPod pod. Run it by hand first, then as a nightly job.
- - Nightly host smoke test against GitHub, GitLab, Bitbucket and a Gitea container (6.5).
+8. **Image + template + compose + docs.** Written, but the image has **not been built yet** (no Docker daemon on the dev machine):
+ - `apps/renderer-service/Dockerfile` (`VARIANT=slim|full`; tini, git, git-lfs, ssh, ffmpeg; user `framefields`; `HEALTHCHECK`) and `docker/entrypoint.sh` (`http` | `runpod-serverless` | `cli`).
+ - Pinned SSH host keys: `deploy/known_hosts`, verified against `deploy/known_hosts.fingerprints` by `deploy/known-hosts.sh`, which the image build runs. The live keys were checked against the published fingerprints on 2026-10-14.
+ - RunPod: `deploy/runpod/{serverless,pod}.template.json` and `create-template.sh` (GraphQL `saveTemplate`).
+ - `deploy/docker-compose.yml` with MinIO (validated with `docker compose config`) and `deploy/env.example`.
+ - `.github/workflows/renderer-image.yml`: tests, then builds both variants, a no-GPU smoke test, and a push to GHCR on `renderer-v*` tags.
+ - `README.md` is the self-hosting guide. A page on the docs website is still to do; the site isn't in this repo.
+ - Still to do: the first image build, a GPU smoke test on a RunPod pod and a serverless endpoint, and the nightly host smoke tests (6.5).
9. **(Later)**
- Chunked distributed rendering: split a frame range across N jobs and concat with a stream copy.
- Webhooks on completion (`output.webhook` with an HMAC signature).
diff --git a/apps/renderer-service/README.md b/apps/renderer-service/README.md
index 0de86484..4569d349 100644
--- a/apps/renderer-service/README.md
+++ b/apps/renderer-service/README.md
@@ -1 +1,262 @@
-# Gatewai Backend
+# framefields renderer worker
+
+A GPU worker that renders framefields projects straight from git. You send it a job naming a repo, a branch/tag/commit and an exported composition. It then does the following, and returns where the output went:
+
+1. Fetches the code and pulls the assets with git LFS.
+2. Installs dependencies.
+3. Renders the composition on its warm GPU.
+4. Checks the output.
+5. Uploads it.
+
+It runs as a **RunPod serverless endpoint**, a **RunPod pod**, or a **Docker container** on any NVIDIA host. The design, edge cases and error codes are in [PLAN.md](PLAN.md).
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Quick start (Docker + MinIO)](#quick-start-docker--minio)
+- [RunPod](#runpod)
+- [Jobs](#jobs)
+- [Configuration](#configuration)
+- [Errors](#errors)
+- [Security](#security)
+- [Development](#development)
+
+## How it works
+
+```
+job ─▶ resolve ref → fetch (mirror cache) → checkout → git LFS pull
+ → install (skipped when only framefields is needed, or the lockfile is unchanged)
+ → import your entry → render on the warm GPU → verify (ffprobe) → upload
+```
+
+- **Your code runs inside the worker process.** Imports of `framefields` and `@framefields/*` resolve to the worker's own copy, so every job shares one initialised GPU device. Each job loads your modules fresh.
+- **Everything is pinned to one commit.** A branch is resolved once per job, and the result reports the SHA it rendered.
+- **Caches survive between jobs:** git mirrors, LFS objects and package stores live on the cache volume, and checkouts and `node_modules` are reused. A warm job spends almost all its time rendering.
+- **The worker protects itself.** It recycles after N jobs, high memory, GPU device loss, or code that won't stop. If it crashes, the job is still reported after the restart.
+
+## Quick start (Docker + MinIO)
+
+You need an NVIDIA GPU with the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/).
+
+```bash
+cd apps/renderer-service/deploy
+cp env.example .env # set RENDERER_API_KEY, FF_REPO_ALLOWLIST, GIT_TOKEN, MINIO_ROOT_PASSWORD
+docker compose up -d
+curl localhost:8082/health
+```
+
+Submit a job and follow it:
+
+```bash
+curl -s localhost:8082/v2/jobs \
+ -H "authorization: Bearer $RENDERER_API_KEY" -H "content-type: application/json" \
+ -d '{
+ "version": 2,
+ "source": { "repo": "https://github.com/your-org/films.git", "ref": "main", "workdir": "videos/launch" },
+ "target": { "entry": "src/film.ts", "export": "buildFilm" },
+ "output": { "type": "s3", "key": "launch/{shortSha}/{name}.{ext}" }
+ }'
+# → {"id":"…","status":"IN_QUEUE"}
+
+curl -sN localhost:8082/v2/jobs/<id>/events -H "authorization: Bearer $RENDERER_API_KEY" # live progress (SSE)
+curl -s localhost:8082/v2/jobs/<id> -H "authorization: Bearer $RENDERER_API_KEY" # status + result
+curl -s -X POST localhost:8082/v2/jobs/<id>/cancel -H "authorization: Bearer $RENDERER_API_KEY"
+```
+
+Building the image yourself, from the repo root:
+
+```bash
+docker build -f apps/renderer-service/Dockerfile -t framefields-renderer .
+docker build -f apps/renderer-service/Dockerfile --build-arg VARIANT=full -t framefields-renderer:full .
+```
+
+The `full` variant adds a C/C++ toolchain, for projects whose native dependencies have no prebuilt binaries.
+
+## RunPod
+
+The templates are in [`deploy/runpod/`](deploy/runpod). Edit the env values (allowlist, storage), create the secrets they reference under **RunPod → Secrets**, then create the template:
+
+```bash
+RUNPOD_API_KEY=… deploy/runpod/create-template.sh deploy/runpod/serverless.template.json
+```
+
+| | Serverless (`serverless.template.json`) | Pod (`pod.template.json`) |
+|---|---|---|
+| API | RunPod's `/run`, `/status`, `/stream`, `/cancel` | This service's HTTP API on port 8082 |
+| Scaling | RunPod scales workers 0→N | One long-running worker |
+| Cache | Attach a **network volume** to the endpoint (mounted at `/runpod-volume`) | Pod volume at `/runpod-volume` |
+
+Checklist for serverless endpoints:
+
+- **Set the endpoint's execution timeout** above your longest render. RunPod's default is much shorter than a long video.
+- **Attach a network volume** in the same data centre as the GPUs. Without one, every worker starts cold: a full clone, LFS download and install.
+- **FlashBoot** keeps warm workers around between jobs, which is what makes the caches pay off.
+- Choose GPUs with Vulkan support (any recent NVIDIA card). VRAM needs grow with resolution and effects.
+
+A serverless job is the same JSON as above, wrapped as `{"input": …}`:
+
+```bash
+curl -s https://api.runpod.ai/v2/<endpoint-id>/run \
+ -H "authorization: Bearer $RUNPOD_API_KEY" -H "content-type: application/json" \
+ -d '{"input": {"version": 2, "source": {"ref": "main"}, "target": {"entry": "src/film.ts", "export": "buildFilm"}, "output": {"type": "s3", "key": "{jobId}.{ext}"}}}'
+```
+
+How results come back:
+
+- A failed job's `error` is the JSON of a [structured error](#errors), including `retryable`.
+- Progress events appear in `/status` and `/stream`.
+- The worker asks RunPod for a fresh worker (`refresh_worker`) when it recycles.
+
+## Jobs
+
+```jsonc
+{
+ "version": 2,
+ "source": {
+ "repo": "https://github.com/acme/films.git", // or git@host:owner/repo.git; default FF_DEFAULT_REPO
+ "ref": "main", // branch, tag, refs/…, or a commit SHA (≥ 7 chars)
+ "commit": "9f2c1e4", // optional: fail if the ref moved elsewhere
+ "workdir": "videos/launch", // package dir inside the repo
+ "lfs": { "include": ["videos/launch/assets/**"] }, // only pull what this render needs
+ "sparse": ["videos/launch", "shared/fonts"], // optional sparse checkout
+ "submodules": false
+ },
+ "target": {
+ "entry": "src/film.ts",
+ "export": "buildFilm", // a Composition, a function returning one, a record, or a plan
+ "args": { "locale": "tr" }, // passed to the export when it's a function
+ "select": ["teaser"] // pick named outputs from a record / plan
+ },
+ "render": { "kind": "video", "codec": "h264", "quality": "high", "qa": { "failOn": ["black_frames", "error"] } },
+ "output": { "type": "s3", "bucket": "renders", "key": "{ref}/{shortSha}/{name}.{ext}" },
+ "env": { "LOCALE": "tr" },
+ "timeoutSec": 1800,
+ "idempotencyKey": "launch-v12" // a retry of the same commit returns the earlier upload
+}
+```
+
+### What the export can return
+
+Your entry exports a builder, using the same `{ entry, export }` convention as `startPreview()`:
+
+```ts
+import { Composition } from "framefields";
+
+// One video:
+export function buildFilm(args?: { locale?: string }) {
+ const comp = new Composition({ width: 1920, height: 1080, fps: 30, durationFrames: 300 });
+ // …
+ return comp;
+}
+
+// Several named outputs:
+export const cuts = () => ({ main: buildFilm(), teaser: buildTeaser() });
+
+// Or a plan, with per-output render settings:
+export const deliverables = () => ({
+ outputs: [
+ { name: "film", composition: buildFilm() },
+ { name: "sheet", composition: buildFilm(), render: { kind: "frameGrid", grid: { step: 30 } } },
+ ],
+});
+```
+
+Don't render or call `process.exit()` at import time: the job fails with `EXPORT_SIDE_EFFECT`. Your repo files load as ES modules even without `"type": "module"`.
+
+### Render kinds
+
+`render.kind` is one of:
+
+- `video`, with codecs `h264` (default), `vp9`, `vp8` or `gif`;
+- `audio` (`aac`, `mp3`, `opus`);
+- `frames` (`frames: [0, 120]` → PNGs);
+- `frameGrid` (a contact sheet);
+- `lut`.
+
+### Output targets
+
+| `output.type` | Fields | Notes |
+|---|---|---|
+| `s3` | `key` (template), `bucket` | The bucket must be in `FF_OUTPUT_BUCKETS` (defaults to `STORAGE_BUCKET`). Any S3-compatible store works: R2, MinIO, AWS. |
+| `presigned` | `urls` (one per output), `headers` | The worker needs no storage credentials. Sign with an expiry longer than the job timeout. |
+| `local` | `path` (template) | Written under `FF_OUTPUT_DIR`. |
+| `inline` | — | Base64 in the result, up to `FF_INLINE_MAX_BYTES`. |
+
+Key and path templates can use `{jobId}`, `{sha}`, `{shortSha}`, `{ref}`, `{date}`, `{name}`, `{index}` and `{ext}`.
+
+### CLI
+
+To run one job without the HTTP server (for CI or debugging):
+
+```bash
+node apps/renderer-service/dist/src/cli.js --job-file job.json --result-file result.json
+docker run --gpus all -e FF_MODE=cli -v $PWD:/jobs … framefields-renderer --job-file /jobs/job.json
+```
+
+Exit codes: 0 completed, 1 failed, 2 bad invocation or job.
+
+## Configuration
+
+Everything is set by environment variables. The worker checks them all at startup and lists every problem at once. The full reference is [PLAN.md §11](PLAN.md#11-configuration-reference-env). The ones you'll set:
+
+| Variable | Purpose |
+|---|---|
+| `FF_REPO_ALLOWLIST` | **Required.** Repos this worker may render, e.g. `github.com/acme/*`. `*` matches one path segment, `**` any number. |
+| `FF_DEFAULT_REPO`, `FF_DEFAULT_REF` | Defaults for jobs that leave out `source.repo` / `source.ref`. |
+| `RENDERER_API_KEY` | Bearer token for the HTTP API. Required in `http` mode. |
+| `GIT_TOKEN`, `GIT_USERNAME` | HTTPS token for the job's repo host. The username defaults per host: GitHub `x-access-token`, GitLab `oauth2`, Bitbucket `x-token-auth`. |
+| `FF_GIT_CREDENTIALS` | Per-host tokens: `{"git.acme.dev": {"username": "bot", "token": "…"}}`. |
+| `FF_GIT_HOSTS` | Host kinds for self-hosted servers: `{"git.acme.dev": "gitea"}`. Values: `github`, `gitlab`, `bitbucket`, `gitea`, `generic`. |
+| `GIT_SSH_KEY`, `GIT_SSH_KNOWN_HOSTS` | For SSH remotes. Keys for github.com, gitlab.com and bitbucket.org are built in and verified at build time. |
+| `FF_GIT_CA_BUNDLE` | A PEM CA certificate for self-hosted servers with a private CA. |
+| `STORAGE_ENDPOINT`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY` | S3-compatible output storage. |
+| `STORAGE_PUBLIC_BASE_URL` | Turns output keys into public URLs in results. |
+| `FF_CACHE_DIR`, `FF_CACHE_MAX_GB`, `FF_WORK_MAX_GB` | Cache location and size limits. Eviction runs automatically. |
+| `FF_JOB_TIMEOUT_MAX_SEC`, `FF_STALL_TIMEOUT_SEC` | Time limits. |
+| `FF_MAX_JOBS_PER_WORKER` | Recycle after N jobs (default 25). |
+| `FF_ENGINE_POLICY` | `warn` (default) or `fail` when a project asks for a framefields version the worker doesn't have. |
+| `FF_NPMRC` | `.npmrc` contents, for private registries. |
+
+## Errors
+
+A failed job returns:
+
+```json
+{ "code": "LFS_POINTER_UNRESOLVED", "message": "…", "phase": "lfs", "retryable": false, "hint": "…", "details": { … } }
+```
+
+`retryable` tells you whether running the same job again can succeed (network errors, a recycled worker) or not (a bad ref, a missing export, an exhausted LFS quota). Every code is listed in [PLAN.md §10](PLAN.md#10-error-model). The common ones:
+
+| Code | Usual cause |
+|---|---|
+| `REPO_NOT_ALLOWED` | The repo isn't in `FF_REPO_ALLOWLIST`. |
+| `GIT_AUTH_FAILED` / `REPO_NOT_FOUND` | The token can't read the repo. Private repos also report "not found". |
+| `REF_NOT_FOUND` / `REF_AMBIGUOUS` | Typo, deleted branch, or a name that's both a branch and a tag. |
+| `LFS_POINTER_UNRESOLVED` | An asset wasn't downloaded. Widen `source.lfs.include`. |
+| `LFS_QUOTA_EXCEEDED` | The host's LFS bandwidth or storage is used up. |
+| `LOCKFILE_MISSING` / `INSTALL_FAILED` | Commit a lockfile that matches `package.json`. |
+| `EXPORT_NOT_FOUND` / `EXPORT_INVALID` / `EXPORT_SIDE_EFFECT` | The entry doesn't export a builder the worker can use. |
+| `ASSET_NOT_FOUND` | A file the composition references is missing; often an LFS include that's too narrow. |
+| `RENDER_TIMEOUT` / `RENDER_STALLED` | The render took too long, or stopped making progress. |
+| `GPU_DEVICE_LOST` / `RENDER_OOM` | Retry. The worker replaces itself. |
+| `QA_FAILED` | `render.qa.failOn` matched. The outputs are still uploaded and listed. |
+
+## Security
+
+The worker **runs code from the repos you allow**. That code runs in the same process as the worker's credentials. Secrets are removed from the environment before your code runs, but in-process code could still reach them in memory. Therefore:
+
+- Only allowlist repos you trust as much as the worker image itself.
+- Give the worker a **read-only** git token scoped to those repos, and storage credentials scoped to the output bucket.
+- Better still, use `presigned` outputs, so the worker has no storage credentials at all.
+- Credentials are only sent to allowlisted hosts (never to an LFS CDN). They are never written into URLs or `.git/config`, and they are redacted from logs and results.
+
+## Development
+
+```bash
+pnpm --filter @framefields/renderer-service dev # watch mode (set FF_HTTP_INSECURE=true, FF_REPO_ALLOWLIST)
+pnpm --filter @framefields/renderer-service test # unit + integration tests (no GPU needed)
+FF_GPU_TESTS=1 pnpm --filter @framefields/renderer-service test # also the GPU render tests
+apps/renderer-service/deploy/known-hosts.sh --refresh # re-pin SSH host keys (review the diff!)
+```
+
+Integration tests use local bare git repos, an in-memory S3, and subprocess harnesses (`test/*.ts`). The harnesses exist because vitest's sandbox bypasses Node's loader hooks.
diff --git a/apps/renderer-service/deploy/docker-compose.yml b/apps/renderer-service/deploy/docker-compose.yml
new file mode 100644
index 00000000..9de2eb35
--- /dev/null
+++ b/apps/renderer-service/deploy/docker-compose.yml
@@ -0,0 +1,67 @@
+# Self-hosted renderer with local S3 (MinIO) on any NVIDIA host:
+# cd apps/renderer-service/deploy
+# cp env.example .env # set RENDERER_API_KEY, FF_REPO_ALLOWLIST, GIT_TOKEN
+# docker compose up -d
+# Needs the NVIDIA Container Toolkit. API on :8082, MinIO console on :9001.
+services:
+ renderer:
+ image: ${FF_IMAGE:-ghcr.io/gatewai-dev/framefields-renderer:latest}
+ restart: unless-stopped # recycling exits the process on purpose
+ env_file: .env
+ environment:
+ FF_MODE: http
+ FF_CACHE_DIR: /var/cache/framefields
+ STORAGE_ENDPOINT: http://minio:9000
+ STORAGE_FORCE_PATH_STYLE: "true"
+ STORAGE_BUCKET: renders
+ STORAGE_ACCESS_KEY_ID: ${MINIO_ROOT_USER:-framefields}
+ STORAGE_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD:?set MINIO_ROOT_PASSWORD in .env}
+ STORAGE_PUBLIC_BASE_URL: http://localhost:9000/renders
+ ports:
+ - "8082:8082"
+ volumes:
+ - cache:/var/cache/framefields
+ deploy:
+ resources:
+ reservations:
+ devices:
+ - driver: nvidia
+ count: 1
+ capabilities: [gpu, graphics, video, compute, utility]
+ depends_on:
+ minio-init:
+ condition: service_completed_successfully
+
+ minio:
+ image: minio/minio:RELEASE.2025-04-22T22-12-26Z
+ command: server /data --console-address :9001
+ restart: unless-stopped
+ environment:
+ MINIO_ROOT_USER: ${MINIO_ROOT_USER:-framefields}
+ MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?set MINIO_ROOT_PASSWORD in .env}
+ ports:
+ - "9000:9000"
+ - "9001:9001"
+ volumes:
+ - minio:/data
+ healthcheck:
+ test: ["CMD", "mc", "ready", "local"]
+ interval: 5s
+ retries: 20
+
+ minio-init:
+ image: minio/mc:RELEASE.2025-04-16T18-13-26Z
+ depends_on:
+ minio:
+ condition: service_healthy
+ entrypoint: >
+ sh -c "mc alias set local http://minio:9000 $${MINIO_ROOT_USER:-framefields} $${MINIO_ROOT_PASSWORD}
+ && mc mb --ignore-existing local/renders
+ && mc anonymous set download local/renders"
+ environment:
+ MINIO_ROOT_USER: ${MINIO_ROOT_USER:-framefields}
+ MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?set MINIO_ROOT_PASSWORD in .env}
+
+volumes:
+ cache:
+ minio:
diff --git a/apps/renderer-service/deploy/env.example b/apps/renderer-service/deploy/env.example
new file mode 100644
index 00000000..8fd170e2
--- /dev/null
+++ b/apps/renderer-service/deploy/env.example
@@ -0,0 +1,7 @@
+# Copy to .env next to docker-compose.yml. Never commit the real file.
+RENDERER_API_KEY=change-me-to-a-long-random-string
+FF_REPO_ALLOWLIST=github.com/your-org/*
+GIT_TOKEN=
+MINIO_ROOT_USER=framefields
+MINIO_ROOT_PASSWORD=change-me-too
+FF_CACHE_MAX_GB=50
diff --git a/apps/renderer-service/deploy/known-hosts.sh b/apps/renderer-service/deploy/known-hosts.sh
new file mode 100755
index 00000000..8a727d3c
--- /dev/null
+++ b/apps/renderer-service/deploy/known-hosts.sh
@@ -0,0 +1,23 @@
+#!/bin/bash
+# Verifies deploy/known_hosts against the pinned fingerprints (default), or
+# refreshes it from the live hosts first (--refresh). Fails on any key whose
+# fingerprint isn't pinned, or any pinned fingerprint that's missing.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+if [ "${1:-}" = "--refresh" ]; then
+ : > known_hosts.new
+ for host in $(grep -v '^#' known_hosts.fingerprints | awk '{print $1}' | sort -u); do
+ ssh-keyscan -T 15 -t ed25519,ecdsa,rsa "$host" 2>/dev/null | grep -v "^#" >> known_hosts.new
+ done
+ mv known_hosts.new known_hosts
+fi
+
+actual=$(ssh-keygen -lf known_hosts | awk '{print $3, $2}' | sort)
+expected=$(grep -v '^#' known_hosts.fingerprints | sed '/^$/d' | sort)
+if [ "$actual" != "$expected" ]; then
+ echo "known_hosts does not match known_hosts.fingerprints:" >&2
+ diff <(echo "$expected") <(echo "$actual") >&2 || true
+ exit 1
+fi
+echo "known_hosts verified ($(echo "$actual" | wc -l | tr -d ' ') keys)"
diff --git a/apps/renderer-service/deploy/known_hosts b/apps/renderer-service/deploy/known_hosts
new file mode 100644
index 00000000..835c449a
--- /dev/null
+++ b/apps/renderer-service/deploy/known_hosts
@@ -0,0 +1,9 @@
+bitbucket.org ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPIQmuzMBuKdWeF4+a2sjSSpBK0iqitSQ+5BM9KhpexuGt20JpTVM7u5BDZngncgrqDMbWdxMWWOGtZ9UgbqgZE=
+bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDQeJzhupRu0u0cdegZIa8e86EG2qOCsIsD1Xw0xSeiPDlCr7kq97NLmMbpKTX6Esc30NuoqEEHCuc7yWtwp8dI76EEEB1VqY9QJq6vk+aySyboD5QF61I/1WeTwu+deCbgKMGbUijeXhtfbxSxm6JwGrXrhBdofTsbKRUsrN1WoNgUa8uqN1Vx6WAJw1JHPhglEGGHea6QICwJOAr/6mrui/oB7pkaWKHj3z7d1IC4KWLtY47elvjbaTlkN04Kc/5LFEirorGYVbt15kAUlqGM65pk6ZBxtaO3+30LVlORZkxOh+LKL/BvbZ/iRNhItLqNyieoQj/uh/7Iv4uyH/cV/0b4WDSd3DptigWq84lJubb9t/DnZlrJazxyDCulTmKdOR7vs9gMTo+uoIrPSb8ScTtvw65+odKAlBj59dhnVp9zd7QUojOpXlL62Aw56U4oO+FALuevvMjiWeavKhJqlR7i5n9srYcrNV7ttmDw7kf/97P5zauIhxcjX+xHv4M=
+bitbucket.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
+github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
+github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
+github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
+gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9
+gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY=
+gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
diff --git a/apps/renderer-service/deploy/known_hosts.fingerprints b/apps/renderer-service/deploy/known_hosts.fingerprints
new file mode 100644
index 00000000..19a3e925
--- /dev/null
+++ b/apps/renderer-service/deploy/known_hosts.fingerprints
@@ -0,0 +1,14 @@
+# SHA256 host key fingerprints published by each host (checked 2026-10-14):
+# https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints
+# https://docs.gitlab.com/ee/user/gitlab_com/#ssh-host-keys-fingerprints
+# https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/
+# known_hosts may only contain keys listed here (see known-hosts.sh).
+github.com SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU
+github.com SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM
+github.com SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s
+gitlab.com SHA256:eUXGGm1YGsMAS7vkcx6JOJdOGHPem5gQp4taiCfCLB8
+gitlab.com SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw
+gitlab.com SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ
+bitbucket.org SHA256:ybgmFkzwOSotHTHLJgHO0QN8L0xErw6vd0VhFA9m3SM
+bitbucket.org SHA256:FC73VB6C4OQLSCrjEayhMp9UMxS97caD/Yyi2bhW/J0
+bitbucket.org SHA256:46OSHA1Rmj8E8ERTC6xkNcmGOw9oFxYr0WF6zWW8l1E
diff --git a/apps/renderer-service/deploy/runpod/create-template.sh b/apps/renderer-service/deploy/runpod/create-template.sh
new file mode 100755
index 00000000..37bb62ad
--- /dev/null
+++ b/apps/renderer-service/deploy/runpod/create-template.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+# Creates (or updates, with TEMPLATE_ID set) a RunPod template from one of the
+# JSON files here, via RunPod's GraphQL API (`saveTemplate`).
+# RUNPOD_API_KEY=... ./create-template.sh serverless.template.json [image]
+# Edit the env values first (allowlist, storage endpoint). Secrets stay as
+# {{ RUNPOD_SECRET_* }} references; create them under RunPod → Secrets.
+set -euo pipefail
+cd "$(dirname "$0")"
+file="${1:?usage: create-template.sh <template.json> [image]}"
+: "${RUNPOD_API_KEY:?set RUNPOD_API_KEY}"
+
+input=$(jq --arg image "${2:-}" --arg id "${TEMPLATE_ID:-}" '
+ (if $image != "" then .imageName = $image else . end)
+ | (if $id != "" then .id = $id else . end)
+ | .readme = (.readme // "See apps/renderer-service/README.md in gatewai-dev/framefields.")
+ | .volumeMountPath = (.volumeMountPath // "/runpod-volume")
+' "$file")
+
+payload=$(jq -n --argjson input "$input" '{
+ query: "mutation SaveTemplate($input: SaveTemplateInput) { saveTemplate(input: $input) { id name imageName isServerless } }",
+ variables: { input: $input }
+}')
+
+curl -sS https://api.runpod.io/graphql \
+ -H "content-type: application/json" \
+ -H "authorization: Bearer ${RUNPOD_API_KEY}" \
+ -d "$payload" | jq .
diff --git a/apps/renderer-service/deploy/runpod/pod.template.json b/apps/renderer-service/deploy/runpod/pod.template.json
new file mode 100644
index 00000000..8fda4fc4
--- /dev/null
+++ b/apps/renderer-service/deploy/runpod/pod.template.json
@@ -0,0 +1,31 @@
+{
+ "name": "framefields-renderer (pod, HTTP API)",
+ "imageName": "ghcr.io/gatewai-dev/framefields-renderer:latest",
+ "isServerless": false,
+ "containerDiskInGb": 40,
+ "volumeInGb": 100,
+ "volumeMountPath": "/runpod-volume",
+ "dockerArgs": "",
+ "ports": "8082/http",
+ "env": [
+ { "key": "FF_MODE", "value": "http" },
+ { "key": "RENDERER_API_KEY", "value": "{{ RUNPOD_SECRET_ff_api_key }}" },
+ { "key": "FF_REPO_ALLOWLIST", "value": "github.com/your-org/*" },
+ { "key": "GIT_TOKEN", "value": "{{ RUNPOD_SECRET_ff_git_token }}" },
+ {
+ "key": "STORAGE_ENDPOINT",
+ "value": "https://<account>.r2.cloudflarestorage.com"
+ },
+ { "key": "STORAGE_BUCKET", "value": "renders" },
+ {
+ "key": "STORAGE_ACCESS_KEY_ID",
+ "value": "{{ RUNPOD_SECRET_ff_storage_key_id }}"
+ },
+ {
+ "key": "STORAGE_SECRET_ACCESS_KEY",
+ "value": "{{ RUNPOD_SECRET_ff_storage_secret }}"
+ },
+ { "key": "FF_CACHE_MAX_GB", "value": "80" },
+ { "key": "LOG_LEVEL", "value": "info" }
+ ]
+}
diff --git a/apps/renderer-service/deploy/runpod/serverless.template.json b/apps/renderer-service/deploy/runpod/serverless.template.json
new file mode 100644
index 00000000..bb2c1c98
--- /dev/null
+++ b/apps/renderer-service/deploy/runpod/serverless.template.json
@@ -0,0 +1,33 @@
+{
+ "name": "framefields-renderer (serverless)",
+ "imageName": "ghcr.io/gatewai-dev/framefields-renderer:latest",
+ "isServerless": true,
+ "containerDiskInGb": 40,
+ "volumeInGb": 0,
+ "dockerArgs": "",
+ "ports": "",
+ "env": [
+ { "key": "FF_MODE", "value": "runpod-serverless" },
+ { "key": "FF_REPO_ALLOWLIST", "value": "github.com/your-org/*" },
+ { "key": "FF_DEFAULT_REF", "value": "main" },
+ { "key": "GIT_TOKEN", "value": "{{ RUNPOD_SECRET_ff_git_token }}" },
+ {
+ "key": "STORAGE_ENDPOINT",
+ "value": "https://<account>.r2.cloudflarestorage.com"
+ },
+ { "key": "STORAGE_BUCKET", "value": "renders" },
+ {
+ "key": "STORAGE_ACCESS_KEY_ID",
+ "value": "{{ RUNPOD_SECRET_ff_storage_key_id }}"
+ },
+ {
+ "key": "STORAGE_SECRET_ACCESS_KEY",
+ "value": "{{ RUNPOD_SECRET_ff_storage_secret }}"
+ },
+ { "key": "STORAGE_PUBLIC_BASE_URL", "value": "" },
+ { "key": "FF_CACHE_MAX_GB", "value": "80" },
+ { "key": "FF_WORK_MAX_GB", "value": "30" },
+ { "key": "FF_JOB_TIMEOUT_MAX_SEC", "value": "3600" },
+ { "key": "LOG_LEVEL", "value": "info" }
+ ]
+}
diff --git a/apps/renderer-service/docker/entrypoint.sh b/apps/renderer-service/docker/entrypoint.sh
new file mode 100755
index 00000000..660cafb6
--- /dev/null
+++ b/apps/renderer-service/docker/entrypoint.sh
@@ -0,0 +1,44 @@
+#!/bin/bash
+# Starts the renderer per FF_MODE (PLAN.md §5):
+# runpod-serverless (default when RUNPOD_POD_ID is set): the Node server on
+# localhost plus the Python shim in front of it.
+# http: the Node server alone.
+# cli: one job; pass the CLI's arguments, e.g. --job-file /jobs/job.json
+set -euo pipefail
+
+SERVICE_DIR=apps/renderer-service
+MODE="${FF_MODE:-}"
+if [ -z "$MODE" ]; then
+ if [ -n "${RUNPOD_POD_ID:-}" ]; then MODE=runpod-serverless; else MODE=http; fi
+fi
+export FF_MODE="$MODE"
+
+# Headless Vulkan/EGL needs no X server; FF_XVFB=1 forces one for GL fallbacks.
+wrap=()
+if [ "${FF_XVFB:-0}" = "1" ] && command -v xvfb-run >/dev/null 2>&1; then
+ wrap=(xvfb-run -a -e /dev/stderr --server-args="-screen 0 4096x2160x24")
+fi
+
+if command -v nvidia-smi >/dev/null 2>&1; then
+ nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv,noheader || true
+else
+ echo "warning: nvidia-smi not found; rendering needs a Vulkan-capable GPU" >&2
+fi
+
+case "$MODE" in
+ runpod-serverless)
+ "${wrap[@]}" node "$SERVICE_DIR/dist/src/index.js" &
+ NODE_PID=$!
+ # If either process exits, stop the other so RunPod replaces the worker.
+ trap 'kill -TERM "$NODE_PID" 2>/dev/null || true' EXIT TERM INT
+ python3 "$SERVICE_DIR/runpod_worker.py" &
+ SHIM_PID=$!
+ wait -n "$NODE_PID" "$SHIM_PID"
+ ;;
+ cli)
+ exec "${wrap[@]}" node "$SERVICE_DIR/dist/src/cli.js" "$@"
+ ;;
+ *)
+ exec "${wrap[@]}" node "$SERVICE_DIR/dist/src/index.js"
+ ;;
+esac
diff --git a/apps/renderer-service/src/config/schema.ts b/apps/renderer-service/src/config/schema.ts
index c76e5e65..67b2ed81 100644
--- a/apps/renderer-service/src/config/schema.ts
+++ b/apps/renderer-service/src/config/schema.ts
@@ -262,11 +262,14 @@ export function buildConfig(
if (problems.length > 0) return { ok: false as const, problems };
+ // RunPod network volume, then the image's cache dir, then the user's.
const cacheDir =
e.FF_CACHE_DIR ??
(probe.exists("/runpod-volume")
? "/runpod-volume/framefields"
- : path.join(probe.homedir(), ".cache", "framefields-renderer"));
+ : probe.exists("/var/cache/framefields")
+ ? "/var/cache/framefields"
+ : path.join(probe.homedir(), ".cache", "framefields-renderer"));
const workDir = e.FF_WORK_DIR ?? path.join(probe.tmpdir(), "framefields");
const outputBuckets = e.FF_OUTPUT_BUCKETS.length
? e.FF_OUTPUT_BUCKETS
diff --git a/renderer-entrypoint.sh b/renderer-entrypoint.sh
deleted file mode 100755
index 7b58145c..00000000
--- a/renderer-entrypoint.sh
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/bin/bash
-# Starts the renderer per FF_MODE (PLAN.md §5):
-# runpod-serverless (default when RUNPOD_POD_ID is set): Node server on
-# localhost + the Python shim in front of it.
-# http: the Node server alone.
-set -euo pipefail
-
-SERVICE_DIR=apps/renderer-service
-MODE="${FF_MODE:-}"
-if [ -z "$MODE" ]; then
- if [ -n "${RUNPOD_POD_ID:-}" ]; then MODE=runpod-serverless; else MODE=http; fi
-fi
-export FF_MODE="$MODE"
-
-# Headless Vulkan/EGL normally needs no X server; FF_XVFB=1 forces one.
-NODE_CMD=(node "$SERVICE_DIR/dist/src/index.js")
-if [ "${FF_XVFB:-0}" = "1" ] && command -v xvfb-run >/dev/null 2>&1; then
- NODE_CMD=(xvfb-run -a -e /dev/stderr --server-args="-screen 0 4096x2160x24" "${NODE_CMD[@]}")
-fi
-
-git lfs install --skip-repo >/dev/null
-
-if [ "$MODE" = "runpod-serverless" ]; then
- "${NODE_CMD[@]}" &
- NODE_PID=$!
- # If either process exits, stop the other so RunPod replaces the worker.
- trap 'kill -TERM "$NODE_PID" 2>/dev/null || true' EXIT TERM INT
- python3 "$SERVICE_DIR/runpod_worker.py"
-else
- exec "${NODE_CMD[@]}"
-fi