Deployment: Vercel + Neon

Requirements

  • GitHub account

  • Vercel account

  • Neon account

  • Node.js 18+ for local checks

Deploy

  1. Create a Neon project and copy its Postgres connection string.

  2. Import this repo at vercel.com/new.

  3. Set these Vercel environment variables:

Name

Value

DATABASE_URL

Neon Postgres connection string

PCP_INSTANCE_SECRET

Random secret, 32+ chars

PCP_APP_URL

https://<your-app>.vercel.app

PCP_ADMIN_TOKEN

Optional 32+ character admin/reset token. Leave unset for zero-config first login.

Generate local secrets with:

openssl rand -hex 32

  1. Deploy or redeploy the Vercel project. The build connects to the empty Neon database, creates the schema, inserts the app instance, and creates the admin credential.

  2. Log in:

    • If PCP_ADMIN_TOKEN is configured, use that value.

    • If PCP_ADMIN_TOKEN is not configured, PCP generates a temporary first-login admin token for you during build. The token is printed once in Vercel build logs. Copy it, log in, then open Settings and change it immediately so the real credential is never visible in logs.

Zero-Config Admin Login

PCP_ADMIN_TOKEN is optional. When it is missing, deploy initialization creates the admin credential automatically and logs the generated token with a banner like:

personal-context-protocol v0.1.15 - generated deployment admin token
Admin token: <generated-token>
Log in with this token, then change it immediately in Settings.

Only PCP-generated first-login tokens are printed. User-supplied PCP_ADMIN_TOKEN values and Settings-rotated tokens are not printed.

Reset Admin Token With Env

If the database is already initialized and the browser token is lost:

  1. Add or update PCP_ADMIN_TOKEN in Vercel with a new 32+ character value.

  2. Redeploy the project.

  3. Log in with that value.

  4. To keep the credential inside the app database instead of Vercel env, remove PCP_ADMIN_TOKEN, redeploy, then open Settings and set a custom admin token.

Build and runtime logs report whether PCP_ADMIN_TOKEN is configured. If deploy initialization generates a first-login token because PCP_ADMIN_TOKEN is not configured, that generated token is printed once so the deployment can be used without pre-seeded credentials. Change it immediately after first login.

Admin token recovery

The admin (UI) credential comes from one of three sources. Precedence is environment > user > deploy:

Source

How it is set

Rotation

env

PCP_ADMIN_TOKEN is configured

Reconciled to the env value on every deploy; the env var owns the credential

user

You set a custom token in Settings after login

Never auto-rotated

deploy

Neither of the above — PCP generates one

A fresh token is generated on every deploy; the previous deploy token stops working

I entered the wrong password / lost the token

  1. Check your deploy logs. If you did not set PCP_ADMIN_TOKEN, the active token is the one PCP generated and printed once during build/start, under a banner containing Admin token:. Because a new token is generated on each deploy, use the token from the most recent deploy — do not reuse an older one.

  2. Set your own token via the environment. Add PCP_ADMIN_TOKEN (32+ characters) in Vercel (or Docker Compose) and redeploy. The environment variable then owns the credential and overrides any generated token, so it no longer rotates per deploy and is never printed in logs.

  3. Or set it in Settings. After logging in, open Settings and set a custom token. That marks the credential user-managed, so deploys stop rotating it. (Settings rotation is disabled while PCP_ADMIN_TOKEN is configured, because the env var owns the credential.)

How they relate: setting PCP_ADMIN_TOKEN always wins and freezes the credential to that value; clearing it and setting a token in Settings keeps a stable token inside the database; with neither, PCP keeps the deployment usable by minting a fresh token each deploy and printing it once.

Docker Compose Alternative

Docker Compose deployment is documented in deployment-docker-compose.md. It builds the app image with the versioned tag personal-context-protocol:0.1.15 by default, generates a local .env when needed, and runs Postgres locally.

Local Development

npm install
cp .env.example .env.local
npm run db:migrate
npm run dev

.env.local needs:

DATABASE_URL=postgresql://user:password@host:5432/db?sslmode=require
PCP_INSTANCE_SECRET=local-dev-secret-with-32-plus-chars
PCP_APP_URL=http://localhost:3000
# Optional admin/reset token:
# PCP_ADMIN_TOKEN=local-admin-token-with-32-plus-chars

Verify

npm run typecheck
npm run test:run
npm run build

Health check:

curl https://<your-app>.vercel.app/api/v1/health

Expected response:

{
  "status": "ok",
  "version": "0.1.15",
  "database": "pending"
}

Troubleshooting

  • Build does not print a generated token: verify DATABASE_URL is set for the Vercel environment and redeploy. If the database already has an admin credential, the existing credential is preserved and no new token is printed.

  • Login reports SETUP_REQUIRED: deploy initialization did not run. The login page will offer initialization as a fallback; prefer fixing DATABASE_URL and redeploying so the token appears in build logs.

  • Login reports ADMIN_CREDENTIAL_NOT_INITIALIZED: PCP_ADMIN_TOKEN is configured but the credential was not stored. Verify DATABASE_URL and redeploy.

  • Setup or login reports INVALID_ADMIN_TOKEN: update PCP_ADMIN_TOKEN to at least 32 characters, or remove it and let PCP generate the first-login token.

  • Build fails: run npm run typecheck and npm run build locally.

  • UI token is lost: set PCP_ADMIN_TOKEN in Vercel, redeploy, and log in with that value.