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.ymlnew file mode 100644index 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.rendererdeleted file mode 100644index 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/Dockerfilenew file mode 100644index 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.mdindex 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.mdindex 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.ymlnew file mode 100644index 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.examplenew file mode 100644index 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=50diff --git a/apps/renderer-service/deploy/known-hosts.sh b/apps/renderer-service/deploy/known-hosts.shnew file mode 100755index 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_hostsnew file mode 100644index 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/nOeHHE5UOzRdfdiff --git a/apps/renderer-service/deploy/known_hosts.fingerprints b/apps/renderer-service/deploy/known_hosts.fingerprintsnew file mode 100644index 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:46OSHA1Rmj8E8ERTC6xkNcmGOw9oFxYr0WF6zWW8l1Ediff --git a/apps/renderer-service/deploy/runpod/create-template.sh b/apps/renderer-service/deploy/runpod/create-template.shnew file mode 100755index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.shnew file mode 100755index 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"+ ;;+esacdiff --git a/apps/renderer-service/src/config/schema.ts b/apps/renderer-service/src/config/schema.tsindex 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_BUCKETSdiff --git a/renderer-entrypoint.sh b/renderer-entrypoint.shdeleted file mode 100755index 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