#9244·formbricks

README: Local Setup link loops back to the README, and Node/Gitpod prerequisites are out of date

Author: sidgaikwadCreated Sep 11, 2026Updated Sep 12, 2026
Labelsdocumentationagent-ready

Context

Reported via GitHub #9244, checked at 1c947ca. The README's Development section is the entry point for new contributors — docs/development/overview.mdx explicitly defers to it ("Setup instructions live with the code, where they stay in step with it") — but it links to a redirect that lands back on that same docs page, so there is no reachable set of setup steps anywhere. Two of its prerequisites are also stale. This link has broken before (#2855).

Problem

README "Local Setup" links into a loop that contains no setup steps. The Node prerequisite says >=18.x while package.json engines requires >=20.19. The Gitpod section advertises a configured workspace whose config files no longer exist.

Root cause / where to look

  • The loop. README.md:148 links to formbricks.com/docs/developer-docs/contributing/get-started#local-machine-setup. docs/docs.json redirects /docs/developer-docs/contributing/get-started/docs/development/overview, and docs/development/overview.mdx ("Running Formbricks locally") links straight back to the README. Verified in the repo — no page in that chain has setup steps.
  • Node. README.md:140 says >=18.x. Actual: engines.node = >=20.19.0 <21 || >=22.12.0 <23 || >=24.0.0 <25; .nvmrc = 24.14.0.
  • Gitpod. README.md:150-156. No .gitpod.yml or .gitpod.Dockerfile is tracked; three orphaned scripts remain (.gitpod/init.bash, .gitpod/setup-demo.bash, .gitpod/setup-web.bash) and nothing in the repo references them. Gitpod Classic has shut down, so the button now redirects to Ona. docs/development/overview.mdx carries the same dead "Open in Gitpod" link.
  • Docker. README.md:144 says "to run PostgreSQL and MailHog". docker-compose.dev.yml starts postgres, spicedb (+ authzed-db-bootstrap, spicedb-migrate), mailhog, valkey, rustfs (+ perms/init), hub (+ db-create/migrate/worker) and cube by default; taxonomy, qwen/vllm and the authzed tools are profile-gated.
  • The steps that do work are pnpm install then pnpm go — root package.json: go = pnpm db:up && turbo run go --concurrency 20, db:up = pnpm dev:setup && docker compose -f docker-compose.dev.yml up -d, dev:setup = bash scripts/setup-dev-env.sh, which generates .env from .env.example with the six required secrets.

Done when

  • The README's Development section contains the local setup steps inline (at minimum pnpm installpnpm go, and what pnpm dev:setup generates), or links to a page that actually contains them — no link in the chain resolves back to the README.
  • The Node prerequisite matches package.json engines.node, or points at .nvmrc instead of restating a version that can drift.
  • The Gitpod section is removed from both README.md and docs/development/overview.mdx, along with the three orphaned .gitpod/*.bash scripts — or a working Gitpod/Ona config is restored and the button points at it.
  • The Docker prerequisite names what the dev stack actually starts, not just PostgreSQL and MailHog.
  • Verified from a clean clone on a supported Node version: following only the README gets a contributor to a running instance on localhost:3000.