diff --git a/README.md b/README.md index f27656f..fcc2672 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ docker run -p 8080:8080 using-cash-web | Variable | Required | Description | |---|---|---| -| `NEXT_PUBLIC_LOOPS_FORM_ID` | Yes (for waitlist) | Loops publishable form ID. Baked into the static build at `npm run build` time. Without it the waitlist form falls back to a stub endpoint. | +| `NEXT_PUBLIC_LOOPS_FORM_ID` | **Required** | Loops publishable form ID. Baked into the static HTML at `npm run build` time. Without it the waitlist form submit will 404 — the build succeeds but the deployed form is broken. Always set this before building for production. | ## Pages diff --git a/docs/deploy.md b/docs/deploy.md index 4e8a896..ab0b158 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -166,6 +166,25 @@ If the cutover causes issues, revert the A record to its previous value: --- +## Local Build Notes (NFS environments) + +The Next.js build pipeline writes and immediately re-reads webpack manifest files. On NFS-backed workspaces (e.g. Paperclip agent workspaces), write-visibility lag causes the first cold build to fail at the "Collecting page data" step with an ENOENT on a manifest file. + +**The fix is already in `next.config.mjs`:** + +```js +webpack(config) { + config.cache = false // disables webpack persistent cache to avoid NFS race + ... +} +``` + +This adds ~15 seconds to each build (no cache warm-up) but makes the build reliable on NFS. In Docker/CI the build runs on local ephemeral storage so this penalty does not apply there. + +If you see `ENOENT: .next/server/pages-manifest.json` or similar on a fresh build, run `npm run build` a second time — the second run will succeed as the cache is already warm. + +--- + ## Ongoing Deploys (CI) CI runs automatically on push to `main` via `.gitea/workflows/deploy.yml`.