Skip to content

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.

ProjectRoot DirectoryWhat it is
obligraph-webfrontendNext.js site and app (marketing pages, dashboard, API proxy)
obligraph-apibackendFastAPI 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_SECRET isn'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:

  1. In the Vercel dashboard, go to Storage → Create → Neon (Postgres).
  2. Connect it to the obligraph-api project (step 2). This sets DATABASE_URL and DATABASE_URL_UNPOOLED for 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

  1. Select Add New → Project, then import the repository.
  2. Set Root Directory to backend. Vercel detects FastAPI from pyproject.toml.
  3. Add the environment variables below, then select Deploy.
VariableRequiredValue
DATABASE_URLYesSet by the Neon integration, or paste your connection string
DATABASE_URL_UNPOOLEDRecommendedDirect (non-pooled) URL, used for migrations. Neon sets this for you
ADMIN_EMAILRecommendedYour email. Only this address becomes platform admin. Without it, the first person to register does
ANTHROPIC_API_KEYOptionalTurns on Claude for extraction, gap analysis and the Copilot. Without it, the offline engine runs
CRON_SECRETOptionalA random string of 16 or more characters. Enables the daily cron (housekeeping, feed crawls, leftover jobs)
JWT_SECRETOptionalSet it to control the signing key yourself. Otherwise one is generated
PUBLIC_URLFor SSOYour web URL, for example https://obligraph.example.com
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETFor SSORegister the redirect URI <PUBLIC_URL>/api/auth/sso/callback with your provider
SEED_DEMOOptionaltrue 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

  1. Select Add New → Project, then import the same repository again.
  2. Set Root Directory to frontend. Vercel detects Next.js.
  3. Add one environment variable, then select Deploy.
VariableValue
OBLIGRAPH_API_URLThe 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.json schedules /api/internal/cron daily at 02:30 UTC (08:00 IST). Vercel Cron sends CRON_SECRET as a bearer token; without CRON_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_URL on the API project if you use SSO.
  • Turning Claude on later: add ANTHROPIC_API_KEY to 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 (maxDuration is 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.