Skip to content

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

fix(renderer-service): boot on root-owned volumes; keep compile caches

okanasl1e8756d55f75
diff --git a/.changeset/renderer-volume-owner.md b/.changeset/renderer-volume-owner.md
new file mode 100644
index 00000000..1a5dede4
--- /dev/null
+++ b/.changeset/renderer-volume-owner.md
@@ -0,0 +1,5 @@
+---
+"@framefields/renderer-service": patch
+---
+
+The worker image starts on a pod with a mounted volume. RunPod mounts a pod volume owned by root, and the worker (uid 1001) crash-looped with `EACCES` creating its cache dir, so `pod.template.json` with its volume never booted. The entrypoint now starts as root, creates the cache, work and output dirs and hands them to `framefields`, then drops to that user with `gosu`. A dir that is still not writable stops the worker with a `CONFIG_INVALID` line naming the setting instead of a stack trace. The after-job temp cleanup now keeps tsx's and Node's compile caches, so jobs don't recompile the project.
diff --git a/.github/workflows/renderer-image.yml b/.github/workflows/renderer-image.yml
index 63d6120c..61953aa3 100644
--- a/.github/workflows/renderer-image.yml
+++ b/.github/workflows/renderer-image.yml
@@ -128,6 +128,20 @@ jobs:
curl -fsS localhost:8082/health | jq -e '.status == "ok" and .components.gpu.renderer == "cpu"' \
|| { docker logs smoke; exit 1; }
docker rm -f smoke
+ # A root-owned volume at /runpod-volume, as RunPod mounts a pod volume:
+ # the entrypoint hands the cache dir to framefields, then drops root.
+ docker run -d --name smoke-vol -p 8083:8082 -e FF_MODE=http \
+ -e RENDERER_API_KEY=ci-smoke-key-0123456789 -e FF_REPO_ALLOWLIST='github.com/example/*' \
+ -v ff-smoke-vol:/runpod-volume framefields-renderer:ci
+ for i in $(seq 1 30); do
+ if curl -fsS localhost:8083/health >/dev/null; then break; fi
+ sleep 1
+ done
+ curl -fsS localhost:8083/health | jq -e '.status == "ok" and .disks.cache.path == "/runpod-volume/framefields"' \
+ || { docker logs smoke-vol; exit 1; }
+ test "$(docker top smoke-vol -eo uid,args | awk '/dist\/src\/index.js/ {print $1}')" = 1001 \
+ || { docker top smoke-vol -eo uid,args; exit 1; }
+ docker rm -f smoke-vol && docker volume rm ff-smoke-vol
- uses: docker/login-action@v3
if: env.PUBLISH == 'true'
with:
diff --git a/apps/renderer-service/Dockerfile b/apps/renderer-service/Dockerfile
index dcf53fd7..e6ea40cb 100644
--- a/apps/renderer-service/Dockerfile
+++ b/apps/renderer-service/Dockerfile
@@ -47,7 +47,8 @@ ARG VARIANT=slim
# Rendering (Vulkan/GL/fonts/media libs for framefields' native modules),
# ffmpeg/ffprobe (output checks), git + LFS + ssh (checkouts), tini (PID 1:
-# forwards signals, reaps git/install subprocesses), python3 + runpod (shim).
+# forwards signals, reaps git/install subprocesses), python3 + runpod (shim),
+# gosu (the entrypoint drops from root to framefields).
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates openssl \
libnss3 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libdrm2 \
@@ -55,7 +56,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
libgbm1 libpango-1.0-0 libcairo2 libasound2t64 \
libgl1-mesa-dri libglapi-mesa libegl1 libvulkan1 mesa-vulkan-drivers libfontconfig1 \
ffmpeg xvfb xauth \
- git git-lfs openssh-client tini \
+ git git-lfs openssh-client tini gosu \
python3 python3-pip \
&& if [ "$VARIANT" = "full" ]; then \
apt-get install -y --no-install-recommends build-essential python3-dev pkg-config; \
@@ -82,7 +83,9 @@ RUN groupadd --system --gid 1001 framefields && \
WORKDIR /app
COPY --from=builder --chown=framefields:framefields /out .
-USER framefields
+# No USER: the entrypoint starts as root only to hand the cache and work dirs
+# to framefields (a RunPod pod volume is mounted root-owned), then runs
+# everything as framefields (uid 1001). `docker run --user` skips that step.
EXPOSE 8082
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
diff --git a/apps/renderer-service/PLAN.md b/apps/renderer-service/PLAN.md
index ef0b47b1..c6185e9c 100644
--- a/apps/renderer-service/PLAN.md
+++ b/apps/renderer-service/PLAN.md
@@ -480,7 +480,7 @@ The worker **executes code from the repo**. Anyone who can submit a job and poin
- `FF_REPO_ALLOWLIST` is **required** in git mode (e.g. `github.com/acme/*`). With `FF_DEFAULT_REPO` set and no allowlist, only that repo is allowed.
- HTTP mode requires `RENDERER_API_KEY`. RunPod endpoints already require the RunPod API key.
- **Repo code runs in the same process as the worker's credentials.** Secrets are removed from `process.env` before any repo code runs (8.2), and they are never written to disk in the workspace. Even so, code running in-process can in principle reach anything in memory. **The repos on the allowlist must be trusted to the same degree as the worker image.** Use a storage key scoped to the output bucket, and a read-only git token scoped to the allowed repos. With a `presigned` output the worker needs no storage credentials at all.
-- The process runs as non-root user `framefields`. The workspace and cache are owned by it, and nothing outside them is writable.
+- The worker runs as non-root user `framefields` (uid 1001). The container starts as root only so the entrypoint can create the cache, work and output dirs and hand them to `framefields` (a RunPod pod volume is mounted root-owned); it then drops to `framefields` with `gosu` before anything else runs. `docker run --user` skips that step. The workspace and cache are owned by `framefields`, and nothing outside them is writable.
- Logs and results go through a **redactor**. It strips tokens, URL userinfo, presigned query strings, and the `job.env` values the config marks secret.
- Documented risk: install scripts and repo code have network access. Self-hosters who need more can run with egress firewalling; that is out of scope here.
diff --git a/apps/renderer-service/docker/entrypoint.sh b/apps/renderer-service/docker/entrypoint.sh
index ae144104..f5f81b58 100755
--- a/apps/renderer-service/docker/entrypoint.sh
+++ b/apps/renderer-service/docker/entrypoint.sh
@@ -7,6 +7,22 @@
set -euo pipefail
SERVICE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+# As root: give framefields its cache, work and output dirs (volumes such as a
+# RunPod pod volume are mounted root-owned), then rerun this script as
+# framefields. The cache default matches the worker's (config/schema.ts).
+if [ "$(id -u)" = 0 ]; then
+ cache="${FF_CACHE_DIR:-}"
+ if [ -z "$cache" ]; then
+ if [ -e /runpod-volume ]; then cache=/runpod-volume/framefields; else cache=/var/cache/framefields; fi
+ fi
+ for dir in "$cache" "${FF_WORK_DIR:-/tmp/framefields}" ${FF_OUTPUT_DIR:+"$FF_OUTPUT_DIR"}; do
+ mkdir -p "$dir" && chown framefields:framefields "$dir" \
+ || echo "cannot hand $dir to the framefields user; the worker may not be able to write there" >&2
+ done
+ exec gosu framefields "$0" "$@"
+fi
+
MODE="${FF_MODE:-}"
if [ -z "$MODE" ]; then
if [ -n "${RUNPOD_POD_ID:-}" ]; then MODE=runpod-serverless; else MODE=http; fi
diff --git a/apps/renderer-service/src/worker/boot.ts b/apps/renderer-service/src/worker/boot.ts
index 8f2ef90f..1cf2f4bd 100644
--- a/apps/renderer-service/src/worker/boot.ts
+++ b/apps/renderer-service/src/worker/boot.ts
@@ -1,4 +1,11 @@
-import { mkdirSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import {
+ accessSync,
+ constants,
+ mkdirSync,
+ readdirSync,
+ realpathSync,
+ rmSync,
+} from "node:fs";
import path from "node:path";
import {
describeConfig,
@@ -75,6 +82,8 @@ export function bootWorker(
// janitor sees their disk use and a crash's leftovers get cleared.
// os.tmpdir() reads TMPDIR on every call.
const tmpDir = path.join(config.paths.workDir, "tmp");
+ writableDir(config.paths.workDir, "FF_WORK_DIR");
+ writableDir(config.paths.cacheDir, "FF_CACHE_DIR");
rmSync(tmpDir, { recursive: true, force: true });
mkdirSync(tmpDir, { recursive: true });
process.env.TMPDIR = tmpDir;
@@ -227,17 +236,42 @@ export function bootWorker(
}
/**
- * Engine versions up to 2.2.0-beta.3 cache downloaded fonts by URL for the
- * life of the process, in `gatewai-fonts`; deleting them would break the next
- * job that uses the same URL.
+ * Kept between jobs: compile caches (tsx's `tsx-<uid>`, Node's
+ * `node-compile-cache`), keyed by content, so the next job doesn't recompile
+ * the project; and `gatewai-fonts`, where engine versions up to
+ * 2.2.0-beta.3 cache downloaded fonts by URL for the life of the process.
+ */
+function keepInTmp(name: string): boolean {
+ return (
+ name === "gatewai-fonts" ||
+ name === "node-compile-cache" ||
+ name.startsWith("tsx-")
+ );
+}
+
+/**
+ * Creates `dir` and checks this process can write to it, so a volume mounted
+ * read-only or owned by another user fails with the setting to fix instead of
+ * a bare EACCES stack trace.
*/
-const KEEP_IN_TMP = new Set(["gatewai-fonts"]);
+function writableDir(dir: string, setting: string): void {
+ try {
+ mkdirSync(dir, { recursive: true });
+ accessSync(dir, constants.W_OK);
+ } catch (err) {
+ const uid = process.getuid?.();
+ console.error(
+ `❌ CONFIG_INVALID\n - ${setting}: ${dir} is not writable${uid === undefined ? "" : ` by uid ${uid}`} (${(err as NodeJS.ErrnoException).code}). Point it at a writable path, or start the image as root so its entrypoint can hand the dir to the framefields user.`,
+ );
+ exit(1);
+ }
+}
/** Removes what the job left in the temp dir (jobs run one at a time). */
function emptyTmp(dir: string): void {
try {
for (const name of readdirSync(dir)) {
- if (KEEP_IN_TMP.has(name)) continue;
+ if (keepInTmp(name)) continue;
rmSync(path.join(dir, name), { recursive: true, force: true });
}
} catch (err) {