ADR 0037: one-click Vercel installation

• Status: proposed; private CLI installation verified, public Deploy Button and hosted Supabase paths pending
• Date: 2026-10-27

Acceptance

An installer can choose Neon or Supabase, choose default or EU compute, generate three independent secrets and a setup code without a terminal, let a production build migrate an empty database, complete /setup, and sign in. A wrong secret cannot invoke the worker. Preview builds cannot migrate the production database. Docker’s one-shot migration and resident worker continue to work. Upgrades stop on a migration failure or revision mismatch.

Decision

README links use the documented repository-url, root-directory, env, envDescription, envLink, envDefaults, project-name, repository-name and stores Deploy Button parameters. stores requests only the selected PostgreSQL integration. Blob is deferred until a GuestCraft feature actually uses it; provisioning an unused store would add an unnecessary resource. Buttons require a public source repository. GitHub Pages is the intended free static host for the browser-only generator once public. Until then, the HTML file works offline. No secret value is put in a button URL.

The browser uses Web Crypto to generate AUTH_SECRET, an independent versioned ENCRYPTION_KEYS, and CRON_SECRET. The 80-bit Crockford setup code is the first ten bytes of HMAC-SHA256(AUTH_SECRET, "guestcraft/setup-code/v2"); it no longer depends on an instance ID assigned later by Vercel. Docker still prints the code until setup finishes. Existing completed setup records are unchanged. Reusing an auth secret across instances would reuse the setup code, so every installation must generate fresh values.

The standalone HTML is bilingual documentation that must work from a local file: URL. It embeds its short instructions rather than loading application i18n catalogs, because a fetch or bundled app would break the offline property. Canonical variable names remain untranslated.

The Vercel project ID hashes to a twelve-character stable instance ID when no explicit ID exists; the production domain becomes the HTTPS base URL when no explicit origin exists. The build command compiles Next.js first, then migrates only when VERCEL_ENV=production, before deployment completes. It suppresses migration output (including the private setup code) and database error bodies. The existing session advisory lock, checksum journal and runtime revision check remain authoritative. Previews skip migration and need a separate, already migrated database. Vercel’s own CRON_SECRET authorizes the existing worker endpoint. A daily cron is selected so Hobby deployments remain valid; Docker keeps the resident worker. vercel.ts uses GUESTCRAFT_VERCEL_REGION=fra1 from the EU buttons, otherwise iad1. A database may advance before Vercel promotes a built deployment; migrations must be reviewed for compatibility with the currently serving version, and a failed promotion may require a forward fix.

Supabase’s transaction pooler uses role.<project-ref> usernames; role URL rewriting preserves that suffix. Session pooler or direct PostgreSQL is required for the migration lock. The owner needs CREATEROLE; the runtime roles retain least privilege and RLS. The app does not adopt Supabase Auth or its service-role key.

Evidence and limits

On 27 October 2026, a disposable Vercel project was deployed from a local checkout without a Git connection, using a free Neon Marketplace database in Frankfurt. The production build applied nine migrations. Browser and API checks completed setup, sign-in, property and room creation, a reservation, room assignment and check-in; reload preserved the checked-in state. Health and both documentation endpoints returned HTTP 200. Anonymous reservation access returned 401 and invalid creation returned 400. The temporary resources were removed after testing. This verifies the private CLI path only; the public Deploy Buttons and hosted Supabase path remain untested.

The URL parameters and store object follow Vercel’s Deploy Button source, build settings and environment variable rules. The app manifest pins the documented Node 24 major. Dynamic region and cron configuration follow programmatic project configuration, cron setup and Bearer secret behavior. Hobby’s daily cron and non-commercial use limit are documented for installers. The project ID and production URL are Vercel system variables. Supabase’s connection modes and custom-role usernames, Marketplace variables, and extension schema guidance inform the database paths. The local Supabase stack test is described in the developer guide.