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:148links toformbricks.com/docs/developer-docs/contributing/get-started#local-machine-setup.docs/docs.jsonredirects/docs/developer-docs/contributing/get-started→/docs/development/overview, anddocs/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:140says>=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.ymlor.gitpod.Dockerfileis 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.mdxcarries the same dead "Open in Gitpod" link. - Docker.
README.md:144says "to run PostgreSQL and MailHog".docker-compose.dev.ymlstarts 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 installthenpnpm go— rootpackage.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.envfrom.env.examplewith the six required secrets.
Done when
- The README's Development section contains the local setup steps inline (at minimum
pnpm install→pnpm go, and whatpnpm dev:setupgenerates), or links to a page that actually contains them — no link in the chain resolves back to the README. - The Node prerequisite matches
package.jsonengines.node, or points at.nvmrcinstead of restating a version that can drift. - The Gitpod section is removed from both
README.mdanddocs/development/overview.mdx, along with the three orphaned.gitpod/*.bashscripts — 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.
Source: formbricks/formbricks