Deploying demos to public URLs

Every web demo in apps/ is deployed to Vercel as its own project, giving each demo a stable, shareable HTTPS URL on the free tier. This is the path for stakeholder reviews — no Docker, no registry, no DNS work.

Live URLs

Each demo is served on a demo-*.gecx.chat custom domain. The gecx-*.vercel.app URL still works too — it's the underlying Vercel deployment the custom domain points at.

The bare https://gecx.chat 308-redirects to the Showcase demo.

These URLs are stable across redeploys — safe to drop in a calendar invite, an email, or a deck.

proxy-reference is intentionally not here — it's a backend service, not a demo. It stays on Cloud Run (see apps/proxy-reference/).

Custom domain (gecx.chat)

The gecx.chat domain is registered through Vercel and lives in the same account as the projects, so DNS and SSL are fully automatic — there are no DNS records to manage by hand.

Each demo project has one custom subdomain attached:

To re-attach the domains (e.g. after recreating a project), run:

export VERCEL_TOKEN=...        # https://vercel.com/account/tokens
scripts/setup-vercel-domains.sh

That script is idempotent — it skips domains already attached.

TL;DR — redeploying after a code change

# Deploy every demo to its production URL:
pnpm deploy:demos

# Deploy just one:
bash scripts/deploy-demos.sh --prod --app showcase

# Deploy as throwaway preview URLs instead of production:
pnpm deploy:demos:preview

--app values: showcase, coolaid, applied, studio, dashboards, portal.

First-time setup

The demos are already set up on Vercel. You only need the steps below if you are deploying to a fresh Vercel account (the projects don't exist yet).

# 1. Log into Vercel (opens a browser, one time):
npx vercel login

# 2. Create + configure the six projects. This needs a Vercel API token
#    because a pnpm monorepo requires each project's "Root Directory" to be
#    set server-side — vercel.json alone can't do it.
#    Mint a token at https://vercel.com/account/tokens
export VERCEL_TOKEN=...
bash scripts/setup-vercel-projects.sh

# 3. Deploy everything:
pnpm deploy:demos

setup-vercel-projects.sh is idempotent — re-run it any time the build commands or root directories change.

How it works

A pnpm workspace is the wrinkle: each demo depends on the gecx-chat workspace package, so Vercel must upload the whole repo, not just the app folder — otherwise gecx-chat won't resolve.

The two-script design handles this:

• scripts/setup-vercel-projects.sh — via the Vercel REST API, creates each project and sets its Root Directory to apps/<demo>. This is the critical setting: Vercel uploads whatever directory you deploy from, then descends into the Root Directory to build. The build/install commands are set with a leading cd ../.. so they run from the workspace root.

• scripts/deploy-demos.sh — deploys each demo. It always runs vercel deploy from the repo root (uploading the full workspace), re-linking the repo-root .vercel/ to the target project before each deploy.

Each app also has an apps/<demo>/vercel.json that mirrors the same settings, so a manual vercel run from an app folder stays consistent.

sdk-portal is a special case: it's a pure static export (output: 'export'). Its Vercel project uses framework: null so Vercel serves the out/ directory as plain static files instead of expecting a .next/ build.

Why Vercel rather than Cloud Run

The repo has Cloud Run manifests for start-studio and proxy-reference, and output: 'standalone' is wired for the SSR apps — so they could ship as containers. For stakeholder-shareable demos, Vercel wins on:

• Zero infra setup — no Artifact Registry, no service account, no IAM.
• Stable named URLs — gecx-<demo>.vercel.app instead of *-uc.a.run.app hashes that change when a service is recreated.
• Preview URLs per deploy for design review without touching production.

If you ever need the demos on a custom domain, attach it in the Vercel dashboard — no code change.

Caveats

• Server-side env vars (API keys etc.) must be set per project via vercel env add or the dashboard. The demos run with mock transports by default and need none.
• start-studio runs pack-sdk during its build so generated repos can install the SDK offline — that adds ~30s to its build.
• Vercel's free tier rate-limits concurrent builds, so the deploy script runs serially.
• .vercel/ linkage directories are gitignored — they hold account-specific project IDs and must not be committed.