Deployment
Deploy Raziel to Vercel, with Docker Compose (e.g. Coolify), or self-host on your own server.
Prerequisites
All deployment targets require:
| Variable | Description |
|---|---|
DATABASE_URL | PostgreSQL connection string |
CLERK_SECRET_KEY | Clerk backend secret (sk_live_...) |
CLERK_WEBHOOK_SECRET | Clerk webhook signing secret (whsec_...) |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Clerk publishable key (pk_live_...) |
NEXT_PUBLIC_CLERK_SIGN_IN_URL | /sign-in |
NEXT_PUBLIC_CLERK_SIGN_UP_URL | /sign-up |
E2B_API_KEY | Sandbox provider API key |
ENCRYPTION_SECRET | Secret for AES-256-GCM encryption of stored secrets (≥32 chars) |
PTY_TOKEN_SECRET | Signs the PTY/chat bridge tokens (≥32 chars) |
Optional:
| Variable | Description |
|---|---|
E2B_TEMPLATE | Sandbox template name (defaults to raziel-agents) |
PTY_BRIDGE_URL | Public wss:// URL of the PTY/chat bridge service |
PREVIEW_PROXY_URL | Public URL of the preview proxy service |
OAUTH_STATE_SECRET | Signs the GitHub OAuth/App install state (falls back to PTY_TOKEN_SECRET) |
GITHUB_APP_ID | GitHub App numeric ID |
GITHUB_APP_PRIVATE_KEY | GitHub App RSA private key PEM |
NEXT_PUBLIC_APP_URL | Canonical 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.
Manual setup
-
Connect your repo — import the repository from the Vercel dashboard.
-
Add a Postgres database — go to Storage → Create Database and choose a provider (Neon or Supabase are recommended). Copy the
DATABASE_URLconnection string. -
Configure Clerk — create a Clerk application at clerk.com and copy the keys to Vercel's environment variables.
-
Set all required environment variables — in the Vercel project settings under Environment Variables, add every variable from the table above.
-
Deploy — Vercel runs
prisma generate && prisma migrate deploy && next buildautomatically (configured invercel.json).
Clerk webhook
After deploying, register a Clerk webhook so user events sync to the database:
- In the Clerk dashboard go to Webhooks → Add Endpoint.
- Set the URL to
https://<your-domain>/api/webhooks/clerk. - Subscribe to
user.created,user.updated,user.deleted. - 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.
- Create a Docker Compose resource pointing at the repo; Coolify reads
docker-compose.yml. - 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. - Give each public service a domain, with its container port:
app→https://app.example.com:3000pty-bridge→https://pty.example.com:8080, then setPTY_BRIDGE_URL=wss://pty.example.compreview-proxy→https://preview.example.com:8080, then setPREVIEW_PROXY_URL=https://preview.example.com
- 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-slimin Docker. - PostgreSQL 14+ — any managed or self-hosted Postgres instance works.
- Docker (optional) — the
Dockerfileproduces 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 startBridge 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.comUse 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.