Deploy to Vercel
Deploy Obligraph to Vercel as two projects with a Neon Postgres database, the environment variables to set, and the limits to know.
Obligraph deploys to Vercel as two projects from the same repository, plus a Postgres database. You only need to set environment variables.
| Project | Root Directory | What it is |
|---|---|---|
obligraph-web | frontend | Next.js site and app (marketing pages, dashboard, API proxy) |
obligraph-api | backend | FastAPI on Vercel's Python runtime (backend/index.py) |
The browser only ever talks to obligraph-web. Its /api/* routes proxy to obligraph-api.
Serverless mode
On Vercel the API detects VERCEL=1 and switches itself into serverless mode:
- Database setup: migrations, LangGraph's tables and reference data are applied on cold start, so there's no manual migrate step.
- Signing secret: if
JWT_SECRETisn't set, one is generated once and stored in the database. - Evidence files are stored in Postgres, because Vercel has no persistent disk.
- Queued work (extraction, gap assessment) runs inside the request that queued it, for up to about 20 seconds. The app advances anything left over in the background while someone is signed in, and a daily cron catches the rest.
- Uploads are capped at 4 MB, because Vercel limits request bodies to 4.5 MB.
1. Create the database
Use any Postgres 15 or later with the pgvector extension. The simplest option is Neon from the Vercel Marketplace:
- In the Vercel dashboard, go to Storage → Create → Neon (Postgres).
- Connect it to the
obligraph-apiproject (step 2). This setsDATABASE_URLandDATABASE_URL_UNPOOLEDfor you.
Obligraph accepts the URLs exactly as Neon gives them (postgres://…?sslmode=require, including the pooled -pooler host). Supabase and other providers work too: paste their connection string as DATABASE_URL.
2. Create the API project
- Select Add New → Project, then import the repository.
- Set Root Directory to
backend. Vercel detects FastAPI frompyproject.toml. - Add the environment variables below, then select Deploy.
| Variable | Required | Value |
|---|---|---|
DATABASE_URL | Yes | Set by the Neon integration, or paste your connection string |
DATABASE_URL_UNPOOLED | Recommended | Direct (non-pooled) URL, used for migrations. Neon sets this for you |
ADMIN_EMAIL | Recommended | Your email. Only this address becomes platform admin. Without it, the first person to register does |
ANTHROPIC_API_KEY | Optional | Turns on Claude for extraction, gap analysis and the Copilot. Without it, the offline engine runs |
CRON_SECRET | Optional | A random string of 16 or more characters. Enables the daily cron (housekeeping, feed crawls, leftover jobs) |
JWT_SECRET | Optional | Set it to control the signing key yourself. Otherwise one is generated |
PUBLIC_URL | For SSO | Your web URL, for example https://obligraph.example.com |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | For SSO | Register the redirect URI <PUBLIC_URL>/api/auth/sso/callback with your provider |
SEED_DEMO | Optional | true loads the sample corpus and a demo organisation on first start, into an empty database only: once any organisation exists it is skipped, so set it before anyone registers. The demo account is a public platform admin, so set ADMIN_EMAIL too, and don't use this on a site real users rely on |
Note the deployment URL, for example https://obligraph-api.vercel.app, and check that <that URL>/ready responds.
3. Create the web project
- Select Add New → Project, then import the same repository again.
- Set Root Directory to
frontend. Vercel detects Next.js. - Add one environment variable, then select Deploy.
| Variable | Value |
|---|---|
OBLIGRAPH_API_URL | The API project's URL from step 2, for example https://obligraph-api.vercel.app |
Open the web URL and register with your ADMIN_EMAIL. That account is the platform admin.
4. After the first deploy
- Regulator feeds: go to Admin → Regulator sources, enable the RBI feeds, and select Run now. See Regulator feeds.
- Cron:
backend/vercel.jsonschedules/api/internal/crondaily at 02:30 UTC (08:00 IST). Vercel Cron sendsCRON_SECRETas a bearer token; withoutCRON_SECRET, the endpoint refuses every call. On the Hobby plan, Vercel only allows daily crons. On Pro you can run it more often (for example*/15 * * * *). - Custom domain: add it to the web project, and update
PUBLIC_URLon the API project if you use SSO. - Turning Claude on later: add
ANTHROPIC_API_KEYto the API project and redeploy. New documents use Claude from then on. Select Re-assess all on the Obligations page to refresh existing assessments.
Limits to know
- Function time: 300 seconds per request on Hobby (
maxDurationis set to 300). Long Claude runs are processed in steps. - Uploads: 4 MB per file. Larger documents need splitting, or a deployment outside Vercel; Docker has a 25 MB limit.
- Rate limits (login, demo form) are kept per instance. For strict limits across many instances, add one at the edge, such as Vercel Firewall rules.
- Housekeeping (approval escalation, overdue-task alerts and the daily coverage snapshot used by the board pack trend) runs with the cron. On a daily schedule, overdue approvals escalate at most once a day.
Other hosts
docker compose up --build runs the same app on any VM, with a long-running worker and local file storage. See Run with Docker.