Prerequisites
- Node.js — a version supporting Next.js 16
- PostgreSQL — local or hosted
- Docker (optional) — only for the local MinIO bucket
1. Environment
DATABASE_URL. For GitHub sign-in, set AUTH_GITHUB_ID and AUTH_GITHUB_SECRET, and create a GitHub OAuth app with the callback:
2. Install and set up the database
npm install runs prisma generate via postinstall, so the client is ready afterwards.
3. Run
http://localhost:3000. predev runs prisma generate and copies the face-detection models, so a fresh clone works without extra steps.
Optional: local object storage
Identity documents need an S3-compatible bucket. For local development:S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY at it.
Without a bucket configured, uploads fall back to a local directory that is development-only. Never run a production deployment that way — identity documents would sit on the application server’s filesystem. The Verification screen reports which mode a deployment is in.
Scripts
Verifying it works
status is ok, degraded or down. A down result returns 503; degraded stays 200, because the site is still serving and marking everything red would state something untrue.
Common setup problems
no matching decryption secret
A session cookie in your browser was encrypted with a different AUTH_SECRET. The app already sends a header clearing the cookie, so one page load fixes it. If it persists, delete authjs.session-token for localhost:3000 in DevTools.
Invalid environment variables
lib/env.ts validates at boot and the error names the field. Related settings are checked together — for instance, NOWPAYMENTS_API_KEY without NOWPAYMENTS_IPN_SECRET fails, because that combination hands out deposit addresses while every crediting callback fails signature verification.