RAZIEL.docs

Deployment

Deploy Raziel to Vercel, with Docker Compose (e.g. Coolify), or self-host on your own server.

Prerequisites

All deployment targets require:

VariableDescription
DATABASE_URLPostgreSQL connection string
CLERK_SECRET_KEYClerk backend secret (sk_live_...)
CLERK_WEBHOOK_SECRETClerk webhook signing secret (whsec_...)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYClerk publishable key (pk_live_...)
NEXT_PUBLIC_CLERK_SIGN_IN_URL/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL/sign-up
E2B_API_KEYSandbox provider API key
ENCRYPTION_SECRETSecret for AES-256-GCM encryption of stored secrets (≥32 chars)
PTY_TOKEN_SECRETSigns the PTY/chat bridge tokens (≥32 chars)

Optional:

VariableDescription
E2B_TEMPLATESandbox template name (defaults to raziel-agents)
PTY_BRIDGE_URLPublic wss:// URL of the PTY/chat bridge service
PREVIEW_PROXY_URLPublic URL of the preview proxy service
OAUTH_STATE_SECRETSigns the GitHub OAuth/App install state (falls back to PTY_TOKEN_SECRET)
GITHUB_APP_IDGitHub App numeric ID
GITHUB_APP_PRIVATE_KEYGitHub App RSA private key PEM
NEXT_PUBLIC_APP_URLCanonical public URL (e.g. https://app.raziel.fun)

Deploy to Vercel

Vercel is the recommended deployment target. It handles build caching, edge CDN, and automatic preview deployments.

Deploy with Vercel

Manual setup

  1. Connect your repo — import the repository from the Vercel dashboard.

  2. Add a Postgres database — go to Storage → Create Database and choose a provider (Neon or Supabase are recommended). Copy the DATABASE_URL connection string.

  3. Configure Clerk — create a Clerk application at clerk.com and copy the keys to Vercel's environment variables.

  4. Set all required environment variables — in the Vercel project settings under Environment Variables, add every variable from the table above.

  5. Deploy — Vercel runs prisma generate && prisma migrate deploy && next build automatically (configured in vercel.json).

Clerk webhook

After deploying, register a Clerk webhook so user events sync to the database:

  1. In the Clerk dashboard go to Webhooks → Add Endpoint.
  2. Set the URL to https://<your-domain>/api/webhooks/clerk.
  3. Subscribe to user.created, user.updated, user.deleted.
  4. Copy the signing secret to CLERK_WEBHOOK_SECRET.

Deploy with Docker Compose (e.g. Coolify)

docker-compose.yml at the repo root runs the whole stack: Postgres, a one-shot migrate service (prisma migrate deploy), the app, the PTY bridge and the preview proxy. Coolify deploys it as a Docker Compose resource.

  1. Create a Docker Compose resource pointing at the repo; Coolify reads docker-compose.yml.
  2. Fill in the variables it lists under Environment Variables (Clerk keys, ENCRYPTION_SECRET, PTY_TOKEN_SECRET, NEXT_PUBLIC_APP_URL, …). NEXT_PUBLIC_* values are baked in at build time, so changing one needs a rebuild.
  3. Give each public service a domain, with its container port:
    • app → https://app.example.com:3000
    • pty-bridge → https://pty.example.com:8080, then set PTY_BRIDGE_URL=wss://pty.example.com
    • preview-proxy → https://preview.example.com:8080, then set PREVIEW_PROXY_URL=https://preview.example.com
  4. Deploy. Migrations run before the app starts on every deploy.

Locally, docker compose --env-file .env.local up --build runs the same stack; docker-compose.override.yml publishes the ports (3000, 5432, 8080, 8081).


Self-hosting requirements

Running Raziel on your own infrastructure requires:

System requirements

  • Node.js 22+ — the app targets node:22-slim in Docker.
  • PostgreSQL 14+ — any managed or self-hosted Postgres instance works.
  • Docker (optional) — the Dockerfile produces a standalone image.

Build and run

# Install dependencies
npm ci

# Generate Prisma client and apply migrations
npx prisma generate
npx prisma migrate deploy

# Build
npx next build

# Start
npx next start

Bridge services (optional)

The interactive terminal and live previews run on two small long-lived services (pty-bridge/ and preview-proxy/), included in docker-compose.yml. Give each a public domain, then point the app at them:

PTY_BRIDGE_URL=wss://pty.example.com
PREVIEW_PROXY_URL=https://preview.example.com

Use the same PTY_TOKEN_SECRET across the app and both services so token verification succeeds.

Health check

The app exposes /api/health — use this for load balancer or uptime checks.

Deployment · Raziel