Deploy to Render free tier with a preview per PR

root commented

2026-10-04 19:26:07 +00:00

(Migrated from gitlab.core-project.space)

Imported from GitHub amaurycoudr/chess-project#233, opened by @amaurycoudr on 2026-10-04 19:26 UTC.
Closed on GitHub on 2026-10-04 21:01 UTC as completed.

Problem Statement

The app has no deployment. Nobody can play it without cloning the repo, and a PR can't be tried in a browser before it merges.

Solution

Deploy to a single free Render web service, with automatic PR previews. The Node API serves the built front as well as /rpc, so both share one origin, as apps/front/src/room/api/client.ts assumes. Render is configured by a committed render.yaml blueprint. A one-off wizard script walks the owner through the dashboard setup.

Why Render free over the alternatives (benchmarked in the session that produced this spec):

Cost and setup: $0, no card, built-in single-service PR previews.
Accepted trade-off: the instance sleeps after 15 min idle and takes ~1 min to wake. Sleeping and redeploying both wipe in-memory Rooms, which fits the Rooms' existing 30-minute TTL.
Next step if that hurts: a Hetzner VM with Coolify, from the same artifact.

User Stories

As a player, I open the production URL and the SPA loads; deep links such as /room/ABC123 load the SPA too.
As a player, I create and play an online game on the production URL, and moves arrive over SSE.
As the owner, every PR gets its own preview URL, with an API that accepts that preview's origin.
As the owner, production deploys only after CI on main is green.
As the owner, I run scripts/setup-render.sh once and it walks me through the Render dashboard, then smoke-tests the deploy.

Seams

Static front serving: a new API module, e.g. serveFront(app, { root }), tested by calling app.fetch against a temporary directory fixture. It is wired in apps/api/src/index.ts only, so createApp stays I/O-free (ADR 0009).
Config: loadConfig (apps/api/src/config.ts) gains an optional front directory (e.g. FRONT_DIST_DIR). Unset means no static serving, so dev and e2e are unchanged.

Implementation Decisions

Static serving uses serveStatic from @hono/node-server/serve-static for files under the front dir.
SPA fallback: any other GET that is not under /rpc returns index.html. /rpc/* behaviour is untouched, including the origin guard and the 404 for unmatched procedures.
render.yaml at the repo root, one web service:
- name: chess-project, runtime: node, plan: free, region: frankfurt.
- buildCommand: corepack enable && pnpm install --frozen-lockfile && pnpm build. Node comes from .nvmrc (24).
- startCommand runs node apps/api/dist/index.js directly, not pnpm start. That way the apps/api/.env.local written by postinstall (env:sync) cannot apply.
- ORIGIN_ALLOWLIST defaults to Render's per-service RENDER_EXTERNAL_URL, which previews also get, with the preview's own URL. For example: ORIGIN_ALLOWLIST=${ORIGIN_ALLOWLIST:-$RENDER_EXTERNAL_URL} node apps/api/dist/index.js.
- FRONT_DIST_DIR=apps/front/dist.
- PORT is injected by Render.
- previews.generation: automatic, autoDeployTrigger: checksPass, healthCheckPath: /.
scripts/setup-render.sh is built from .claude/skills/wizard/template.sh, with the library above the STAGES marker untouched. Its 7 stages:
1. Preflight: render.yaml is on origin/main.
2. Render account sign-up with GitHub.
3. Give Render's GitHub app access to this repo only.
4. Dashboard → New → Blueprint → Apply.
5. First deploy: capture the production URL, and optionally run gh repo edit --homepage (behind confirm).
6. curl smoke test: /, a client route, and /rpc with an allowed origin vs a foreign one (403).
7. Open a throwaway draft PR, check that Render posts a preview, then close it (behind confirm).
README gets a short Deploy section linking the wizard and the production URL.

Testing Decisions

Unit or integration tests through the serveFront seam:
- an asset file is served with its content type;
- an unknown non-/rpc path returns index.html;
- /rpc/* is never shadowed (a foreign origin still gets 403, an unknown procedure still 404).
loadConfig tests cover the new optional key.
The wizard and render.yaml are checked with bash -n/shellcheck and a static trace. They are not run in CI.
The gate is the five commands in CONTRIBUTING.md.

Out of Scope

A custom domain.
Keeping the instance awake (cron pings).
Persisting Rooms.
SSE heartbeat tuning.
Moving off Render (Hetzner/Coolify, Cloudflare Durable Objects).

Further Notes

Unverified until the first deploy:

that corepack works in Render's native Node build;
that startCommand runs through a shell, which the ${...:-...} expansion needs.

The wizard's smoke test (stage 6) is what proves both. Render's docs say PR previews are "billed at the same rate as your base service", which is free for a free service. They count against the 750 free instance-hours per month.

> _Imported from GitHub [amaurycoudr/chess-project#233](https://github.com/amaurycoudr/chess-project/issues/233), opened by [@amaurycoudr](https://github.com/amaurycoudr) on 2026-10-04 19:26 UTC._ > _Closed on GitHub on 2026-10-04 21:01 UTC as completed._  --- ## Problem Statement The app has no deployment. Nobody can play it without cloning the repo, and a PR can't be tried in a browser before it merges. ## Solution Deploy to a single **free Render web service**, with **automatic PR previews**. The Node API serves the built front as well as `/rpc`, so both share one origin, as `apps/front/src/room/api/client.ts` assumes. Render is configured by a committed `render.yaml` blueprint. A one-off wizard script walks the owner through the dashboard setup. Why Render free over the alternatives (benchmarked in the session that produced this spec): - **Cost and setup:** $0, no card, built-in single-service PR previews. - **Accepted trade-off:** the instance sleeps after 15 min idle and takes ~1 min to wake. Sleeping and redeploying both wipe in-memory Rooms, which fits the Rooms' existing 30-minute TTL. - **Next step if that hurts:** a Hetzner VM with Coolify, from the same artifact. ## User Stories 1. As a player, I open the production URL and the SPA loads; deep links such as `/room/ABC123` load the SPA too. 2. As a player, I create and play an online game on the production URL, and moves arrive over SSE. 3. As the owner, every PR gets its own preview URL, with an API that accepts that preview's origin. 4. As the owner, production deploys only after CI on `main` is green. 5. As the owner, I run `scripts/setup-render.sh` once and it walks me through the Render dashboard, then smoke-tests the deploy. ## Seams - **Static front serving:** a new API module, e.g. `serveFront(app, { root })`, tested by calling `app.fetch` against a temporary directory fixture. It is wired in `apps/api/src/index.ts` only, so `createApp` stays I/O-free (ADR 0009). - **Config:** `loadConfig` (`apps/api/src/config.ts`) gains an optional front directory (e.g. `FRONT_DIST_DIR`). Unset means no static serving, so dev and e2e are unchanged. ## Implementation Decisions - **Static serving** uses `serveStatic` from `@hono/node-server/serve-static` for files under the front dir. - **SPA fallback:** any other `GET` that is not under `/rpc` returns `index.html`. `/rpc/*` behaviour is untouched, including the origin guard and the 404 for unmatched procedures. - **`render.yaml`** at the repo root, one web service: - `name: chess-project`, `runtime: node`, `plan: free`, `region: frankfurt`. - `buildCommand: corepack enable && pnpm install --frozen-lockfile && pnpm build`. Node comes from `.nvmrc` (24). - `startCommand` runs `node apps/api/dist/index.js` directly, not `pnpm start`. That way the `apps/api/.env.local` written by `postinstall` (`env:sync`) cannot apply. - `ORIGIN_ALLOWLIST` defaults to Render's per-service `RENDER_EXTERNAL_URL`, which previews also get, with the preview's own URL. For example: `ORIGIN_ALLOWLIST=${ORIGIN_ALLOWLIST:-$RENDER_EXTERNAL_URL} node apps/api/dist/index.js`. - `FRONT_DIST_DIR=apps/front/dist`. - `PORT` is injected by Render. - `previews.generation: automatic`, `autoDeployTrigger: checksPass`, `healthCheckPath: /`. - **`scripts/setup-render.sh`** is built from `.claude/skills/wizard/template.sh`, with the library above the STAGES marker untouched. Its 7 stages: 1. Preflight: `render.yaml` is on `origin/main`. 2. Render account sign-up with GitHub. 3. Give Render's GitHub app access to this repo only. 4. Dashboard → New → Blueprint → Apply. 5. First deploy: capture the production URL, and optionally run `gh repo edit --homepage` (behind `confirm`). 6. curl smoke test: `/`, a client route, and `/rpc` with an allowed origin vs a foreign one (403). 7. Open a throwaway draft PR, check that Render posts a preview, then close it (behind `confirm`). - **README** gets a short Deploy section linking the wizard and the production URL. ## Testing Decisions - Unit or integration tests through the `serveFront` seam: - an asset file is served with its content type; - an unknown non-`/rpc` path returns `index.html`; - `/rpc/*` is never shadowed (a foreign origin still gets 403, an unknown procedure still 404). - `loadConfig` tests cover the new optional key. - The wizard and `render.yaml` are checked with `bash -n`/shellcheck and a static trace. They are not run in CI. - The gate is the five commands in `CONTRIBUTING.md`. ## Out of Scope - A custom domain. - Keeping the instance awake (cron pings). - Persisting Rooms. - SSE heartbeat tuning. - Moving off Render (Hetzner/Coolify, Cloudflare Durable Objects). ## Further Notes Unverified until the first deploy: - that corepack works in Render's native Node build; - that `startCommand` runs through a shell, which the `${...:-...}` expansion needs. The wizard's smoke test (stage 6) is what proves both. Render's docs say PR previews are "billed at the same rate as your base service", which is free for a free service. They count against the 750 free instance-hours per month.

root (Migrated from gitlab.core-project.space) closed this issue

2026-10-04 21:01:59 +00:00

root commented

2026-10-13 08:39:13 +00:00

(Migrated from gitlab.core-project.space)

mentioned in issue #240