Public Site Deployment

The public marketing and docs site is a static Astro site in packages/site. It is separate from the Randal runtime, dashboard, Railway deployments, and self-hosted randal serve process.

Use this guide when you want a hosted marketing/docs preview or production site. Do not use it to deploy an agent runtime.

What Gets Deployed

Source package: packages/site
Build command: bun run site:build
Output directory: packages/site/dist
Output mode: static HTML, CSS, and client assets generated by Astro
Docs content source: README.md and allowlisted docs/*.md files read at build time

The site does not run a Bun/Hono server in production. Vercel serves the generated static output from its CDN.

Separation From Runtime Deployments

The public site is only the marketing/docs surface:

It does not start randal serve.
It does not host the dashboard or gateway runtime.
It does not require RANDAL_API_TOKEN, model provider keys, Meilisearch, Discord secrets, LiveKit, Twilio, or Railway variables.
It does not change self-host or Railway runtime deploy behavior.
PostHog, when enabled, is included only in packages/site static pages.

Use docs/deployment-guide.md for local, Railway, Docker, and imported-service runtime deployments.

Recommended Vercel Setup

Use the Vercel GitHub integration for PR previews and production deploys. This keeps site deploys in Vercel and avoids a duplicate GitHub Actions deploy path.

Create or log in to a Vercel account, ideally under the Hassion Studio team or org.
Import the GitHub repository drewbietron/randal.
Configure the Vercel project with these settings:

Setting	Value
Framework preset	Astro
Install command	`bun install`
Build command	`bun run site:build`
Output directory	`packages/site/dist`

The repo includes vercel.json with the same settings. Normal self-host users can ignore this file; it is inert unless the repo is connected to Vercel or a deploy command is run.

Environment Variables

Copy packages/site/.env.example for local site development or set the same variables in Vercel.

Variable	Required	Description
`PUBLIC_SITE_URL`	Recommended	Canonical site origin, for example `https://randal.dev` or a Vercel preview URL.
`PUBLIC_POSTHOG_ENABLED`	Optional	Set to `true` to enable PostHog on the public site. Any other value disables it.
`PUBLIC_POSTHOG_KEY`	Optional	Public PostHog project key. Analytics stay disabled if this is missing.
`PUBLIC_POSTHOG_HOST`	Optional	PostHog ingest host. Defaults to `https://us.i.posthog.com`; use the EU host if needed.

Do not set runtime secrets such as OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, RANDAL_API_TOKEN, or MEILI_MASTER_KEY on the public site project unless a future site feature explicitly needs them. The current static site does not need those secrets.

PostHog Setup

PostHog is opt-in and public-site-only.

Create a PostHog project.
Copy the public project key.
In Vercel, set PUBLIC_POSTHOG_ENABLED=true.
Set PUBLIC_POSTHOG_KEY=phc_....
Set PUBLIC_POSTHOG_HOST=https://us.i.posthog.com or the EU ingest host.
Redeploy the site.

If PUBLIC_POSTHOG_ENABLED is absent, not true, or PUBLIC_POSTHOG_KEY is empty, the built site does not include the PostHog snippet.

Domain Setup

In Vercel, open the site project settings.
Add the production domain, for example randal.dev.
Follow Vercel's DNS instructions for your registrar.
Set PUBLIC_SITE_URL to the final production origin.
Trigger a production redeploy so canonical URLs use the production domain.

Preview deployments can use Vercel's generated preview URLs. If you need exact canonical preview URLs, set PUBLIC_SITE_URL in the Vercel preview environment.

GitHub Actions Deployment

Do not configure a GitHub Actions Vercel deploy workflow by default. The current deployment path is the Vercel GitHub app, which owns PR previews and production deploys without repo-managed Vercel tokens.

A GitHub Actions deploy could be added later for a specific need, but it should remain an explicit alternative to the Vercel integration, not a second active deploy path for the same site.

Local Verification

Before pushing deployment changes, run:

bun run site:build
bun run test:site
bun run lint

To verify PostHog is disabled by default, build without public PostHog env vars and confirm the generated HTML has no PostHog snippet. To verify opt-in behavior, run a build with PUBLIC_POSTHOG_ENABLED=true and PUBLIC_POSTHOG_KEY=phc_test and confirm the static pages include the public-site snippet.

Public site deployment