Fix the first-run docs: Supabase Cloud steps, full-Docker order, and local setup gaps #483

Summary

A newcomer who follows the README and the app READMEs hits several gaps. The Supabase Cloud steps say to run every numbered SQL script, which includes a demo seed. The SQL Editor rejects that seed's \set line, so the run stops, and the reader misses the two schema scripts after it. A reader who removes \set and runs it again seeds demo users into a hosted project. The same steps miss one push key. The full-Docker steps call a workspace script before bun install. Common local failures have no help text. The webapp and admin READMEs and the Scaling section have smaller gaps.

• Severity: Medium. Each gap costs a newcomer time, and each has a short text fix.
• Area: README.md, CONTRIBUTING.md, apps/webapp/README.md, apps/admin-dashboard/README.md
• Source: docs and README review of 2026-10-14. Five review agents each covered one docs area. A separate agent then checked each finding against the code and tried to refute it. Every item below survived that check. "Checked" lists the evidence.

Items

1. Supabase Cloud Step 3 says to run every numbered script, which includes a demo seed that is not for production.

• Where: README.md:151
• Severity: medium
• Checked: README.md:151 names no file to skip. 30-seed-car-conversation.sql is numbered, and its header says "DEMO / TEST SEED — NOT FOR PRODUCTION". Line 30 is a psql \set line, which the SQL Editor rejects. The file sorts before 31-connected-app-token-gate.sql and 32-password-sign-in-hook.sql. A reader who stops at the error misses both. A reader who strips \set seeds fake users into a hosted project. docs/self-hosting/install.md:47 already says to skip idea.sql, cleanup-orphan-chat-media.sql and 30-seed-car-conversation.sql. The two unnumbered files may fall outside "numbered order", but naming them matches install.md.
• Fix: In README.md:151, after "...the later scripts depend on.", append: "Skip idea.sql, cleanup-orphan-chat-media.sql and 30-seed-car-conversation.sql. They are not schema. See Install step 2."

2. Supabase Cloud Step 4 lists the VAPID variables but leaves out NEXT_PUBLIC_VAPID_PUBLIC_KEY, so the browser cannot turn on push.

• Where: README.md:155
• Severity: medium
• Checked: README.md:155-159 lists only VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY and VAPID_SUBJECT. The webapp reads NEXT_PUBLIC_VAPID_PUBLIC_KEY at apps/webapp/src/utils/push-notifications.ts:5. Without it, the code throws NOT_CONFIGURED (line 150). The key is a build arg in apps/webapp/docker/Dockerfile.bun:140,163 and docker-compose.prod.yml:504,530. docs/self-hosting/configuration.md:70 and :346 say to set it to the same value as VAPID_PUBLIC_KEY. The bunx web-push generate-vapid-keys line works from the repo root, so it needs no change.
• Fix: In README.md Step 4, add NEXT_PUBLIC_VAPID_PUBLIC_KEY=your-vapid-public-key to the env block. Under the block, add one line: "Set NEXT_PUBLIC_VAPID_PUBLIC_KEY to the same value as VAPID_PUBLIC_KEY. It is a build value, so restart or rebuild the webapp after you set it." Leave the bunx web-push generate-vapid-keys line as it is. No directory note is needed. On the make up-dev path, push also needs Fix the full-Docker dev stack: no webapp source in the container, and no host.docker.internal on Linux #482 item 3, which passes the keys to the containers.

3. On a fresh clone, the full-Docker start commands call a workspace script before any bun install, so the third command fails.

• Where: README.md:96
• Severity: medium
• Checked: README.md:84 tells a reader on a fresh clone to "skip to the start commands", so they never run make dev-local. Nothing above the block says to run bun install. README.md:43 says the Supabase CLI is a workspace dependency, so there is no global supabase. The third command runs dotenv -e ../../.env.local -- supabase start (packages/supabase/package.json:7). dotenv-cli and supabase are workspace devDependencies. Only make dev-local installs them, through ensureInstall() (scripts/dev-local-preflight.ts:183-189, 308). make up-dev only builds and starts containers (Makefile:99-102, 135-166). Each dev service mounts an anonymous /app/node_modules, so the containers cannot fill the host's node_modules (docker-compose.dev.yml:118). So the third command fails because dotenv is not installed. The fallback block at README.md:108-113 has the same gap.
• Fix: Add bun install as the first line of the code block at README.md:98-102, before cp .env.example .env.development. That one line also covers the later Google block at README.md:108-113, because it runs after this block.

4. The Supabase Cloud alternative says it replaces the local stack, but make dev-local still starts and checks local Supabase every time.

• Where: README.md:124
• Severity: low
• Checked: README.md:124 says "instead of the local stack" and names no start command. make dev-local always runs scripts/dev-local-preflight.ts (Makefile:212-213), and main() always calls ensureSupabase() (:311). That function starts local Supabase when :54321 is closed (:221-232). It then checks supabase_db_docsplus_supabase for a public.workspaces row, or it fails. No step checks for a cloud URL. README.md:104 says make up-dev starts no Supabase, so the sentence holds there. On that path the webapp does not serve until Fix the full-Docker dev stack: no webapp source in the container, and no host.docker.internal on Linux #482 lands. Nothing breaks for a make dev-local user; it costs a download and some confusion.
• Fix: Add one line after README.md:124: "With make up-dev, no local Supabase starts. make dev-local still starts and checks local Supabase, but the apps use the cloud values in .env.local."

5. The setup guide does not cover a common first-run failure: a host Postgres or Redis already holds port 5432 or 6379. The preflight hint then points the reader the wrong way.

• Where: CONTRIBUTING.md:41
• Severity: medium
• Checked: CONTRIBUTING.md:31-53 covers only make dev-local and bun run doctor. No public doc names a port conflict, DB_PORT or REDIS_PORT as a first-run fix. docker-compose.local.yml:27 binds 127.0.0.1:${DB_PORT:-5432}:5432 and :48 binds 127.0.0.1:${REDIS_PORT:-6379}:6379. So a host Postgres or Redis blocks the bind. ensureInfra (scripts/dev-local-preflight.ts:193-219) then fails with 'Infrastructure failed (Postgres/Redis)'. Its hint is 'Start Docker Desktop, then: make infra-up' (line 217). That hint misleads a reader whose Docker is running. When compose fails, sh() prints Docker's own output above that line (lines 77-80). So the port error is already on screen. localizeEnvForHost builds DATABASE_URL from DB_PORT only when it first creates .env.local (lines 136-155). ensureEnv never rewrites an existing file (lines 161-167). So a later DB_PORT change leaves DATABASE_URL on 5432. The backend reads REDIS_PORT directly (apps/hocuspocus.server/src/config/env.ts:51).
• Fix: Add one item under Development Setup in CONTRIBUTING.md. Suggested text: "If make dev-local stops at 'Infrastructure failed (Postgres/Redis)' while Docker is running, read the Docker error printed above it. If port 5432 or 6379 is already allocated or in use, stop the host Postgres or Redis. Or set DB_PORT in .env.local and change the port in DATABASE_URL to match. For Redis, set REDIS_PORT instead."

6. The webapp README runs E2E with no BASE_URL, so the default stack on port 3000 is missed. It also uses bun run test for two different runs.

• Where: apps/webapp/README.md:77
• Severity: medium
• Checked: The root test:e2e script runs scripts/run-tests.sh (package.json:77). That script defaults BASE_URL to http://localhost:3001 (run-tests.sh:22). make dev-local serves the webapp on port 3000 (CONTRIBUTING.md:281). So the README command hits Continue anyway? [y/N], or exits 1 without a TTY (run-tests.sh:96-110). CONTRIBUTING.md:242, 247 and 273 already give the BASE_URL override. Line 74 sits under # Unit tests (Jest), but bun run test is Jest only inside apps/webapp (apps/webapp/package.json:16). At the root, the same command runs the extension gates, Jest and E2E. CONTRIBUTING.md:245 budgets about 45 minutes for it.
• Fix: Line 74: change bun run test to bun run --filter @docs.plus/webapp test, as CONTRIBUTING.md:256 does, so it works from any directory. Line 77: change it to BASE_URL=http://localhost:3000 bun run test:e2e # 4 workers (default). Line 78: change it to BASE_URL=http://localhost:3000 CYPRESS_PARALLEL=2 bun run test:e2e. Line 84: change it to BASE_URL=http://localhost:3000 bun run test, and add (from monorepo root) to the comment above it.

7. The admin README does not say that local sign-in is Google only and needs an admin_users row. A newcomer at :3100 hits a Google button that cannot work.

• Where: apps/admin-dashboard/README.md:66
• Severity: low
• Checked: apps/admin-dashboard/README.md:66 says only "Requires admin role in Supabase". The real gate is a row in admin_users. apps/admin-dashboard/src/pages/login.tsx:23 offers only Google sign-in. packages/supabase/config.toml:325-327 reads GOOGLE_CLIENT_ID and GOOGLE_SECRET, and .env.example:342-343 leaves both empty. So local sign-in fails until the developer adds keys. CONTRIBUTING.md:55-60 already has both steps, so severity is low. Line 66 does not link to them. Line 17 needs no "run make dev-local first" note: line 20 says it uses ../../.env.local, and README.md:195 says make dev-local creates that file.
• Fix: In apps/admin-dashboard/README.md, replace line 66 ("- Requires admin role in Supabase") with: "- Google sign-in only. Your user needs an admin_users row. See Sign in to the admin dashboard locally." Leave line 17 as it is.

8. The Scaling section offers make scale-hocuspocus with no warning, but the backend docs say scaling all three processes together wastes Postgres connections.

• Where: README.md:310
• Severity: medium
• Checked: README.md:312-315 offers both scale targets with no warning. scale-hocuspocus raises all three backend processes in one up -d --scale command, with no --no-recreate (Makefile:256-258). apps/hocuspocus.server/Readme.md:23 says to scale them independently, because Postgres connections are the shared limit. docs/self-hosting/configuration.md:131 says to check max_connections first. The docker-compose.prod.yml header (lines 13-18) says a plain up --scale without --no-recreate takes the fleet to zero. That needs a config or DEPLOY_TAG change first, so severity stays medium.
• Fix: After the code block in README.md, before "For any other count" (line 317), add: "Check your Postgres max_connections first. scale-hocuspocus raises all three backend processes at once, and the backend docs advise scaling them independently. Both targets run up -d --scale without --no-recreate, so a changed config or DEPLOY_TAG recreates the serving replicas. Read Scaling past the defaults before you scale."

Acceptance criteria

• Item 1 is fixed as its Fix says, or a comment here says why not.
• Item 2 is fixed as its Fix says, or a comment here says why not.
• Item 3 is fixed as its Fix says, or a comment here says why not.
• Item 4 is fixed as its Fix says, or a comment here says why not.
• Item 5 is fixed as its Fix says, or a comment here says why not.
• Item 6 is fixed as its Fix says, or a comment here says why not.
• Item 7 is fixed as its Fix says, or a comment here says why not.
• Item 8 is fixed as its Fix says, or a comment here says why not.

Verify

1. Every new or changed link in the diff resolves.
2. On a fresh clone, run the README Quick Start. Then run the full-Docker start commands up to bun --filter @docs.plus/supabase_back start, and confirm it starts. The webapp on that path needs Fix the full-Docker dev stack: no webapp source in the container, and no host.docker.internal on Linux #482 first.

Related

• Fix the full-Docker dev stack: no webapp source in the container, and no host.docker.internal on Linux #482 full-Docker compose bugs. It changes no README line, so this issue owns the README full-Docker text.
• Run the local setup from a clean clone and report every point of friction #149 clean-clone setup report. Items 3 and 5 are the kind of first-run finding it collects. It is related, not a duplicate.

Generated by Claude Code