# Vercel Deployment Guide

Ask QIEN is deployed on Vercel (Next.js app) with a separate managed Postgres database
(Neon or Supabase work well). Inngest Cloud handles the background job queue.

## Architecture

| Service | Provider | Notes |
|---|---|---|
| Next.js app | Vercel | Auto-deploys from GitHub |
| PostgreSQL | Neon / Supabase | External — Vercel Postgres also works |
| Background jobs | Inngest Cloud | Separate dev + production environments |
| Email (magic link) | Postmark / Resend / SendGrid | SMTP credentials set in Vercel env vars |
| AI | Anthropic | Key set in Vercel env vars |

## Environments

| Vercel environment | Git trigger | Purpose |
|---|---|---|
| Production | Push to `main` | Real users |
| Preview | PR / branch push | Ephemeral review deployments |
| Development | Local | Local dev server |

## Step 1: Connect the Repo

1. Create a Vercel project and import `jamesjlopez/qip-qien` from GitHub.
2. Vercel detects Next.js automatically — no Dockerfile needed (Vercel builds natively).
3. Enable automatic deploys from `main` for production.

## Step 2: Add a Database

The app uses Drizzle ORM and requires a PostgreSQL connection string as `DATABASE_URL`.

**Neon (recommended):**
1. Create a Neon project at [neon.tech](https://neon.tech).
2. Create separate branches or projects for production and dev.
3. Copy the connection string for each environment into Vercel.

**Vercel Postgres:**
1. In the Vercel dashboard, add a Postgres storage resource to the project.
2. Vercel automatically injects `POSTGRES_URL` — map it with `DATABASE_URL=$POSTGRES_URL`.

## Step 3: Set Environment Variables

In Vercel → Project → Settings → Environment Variables, set these for **Production**:

```dotenv
DATABASE_URL=<postgres-connection-string>
AUTH_SECRET=<generate: openssl rand -base64 32>
AUTH_TRUST_HOST=true

EMAIL_SERVER_HOST=<smtp-host>
EMAIL_SERVER_PORT=587
EMAIL_SERVER_USER=<smtp-user>
EMAIL_SERVER_PASSWORD=<smtp-password>
EMAIL_FROM=<from-address>

ANTHROPIC_API_KEY=<anthropic-key>

INNGEST_EVENT_KEY=<inngest-production-event-key>
INNGEST_SIGNING_KEY=<inngest-production-signing-key>

TENANT_CONFIG_PATH=./tenant.config.yaml
```

For **Preview** environments, use separate database and Inngest keys.

Do **not** set these in production:
```dotenv
AUTH_DEV_EMAIL_MODE=dev-link
INNGEST_DEV=1
```

## Step 4: Google OAuth

To enable Google sign-in, create OAuth credentials in Google Cloud Console:

1. Under "Authorized redirect URIs" add: `https://<your-domain>/api/auth/callback/google`
2. Set in Vercel (production environment):

```dotenv
GOOGLE_CLIENT_ID=<client-id>
GOOGLE_CLIENT_SECRET=<client-secret>
```

Note: each Vercel preview deployment has a different domain. For preview Google OAuth,
either add a wildcard redirect URI in Google Console or restrict Google sign-in to
production only.

## Step 5: Run Database Migrations

After the first deploy, run migrations once against the production database.

Using the Vercel CLI to pull production env vars locally:

```bash
npm install -g vercel
vercel login
vercel env pull .env.production.local   # pulls production vars into a local file
pnpm db:migrate
pnpm db:seed
```

Or set `DATABASE_URL` directly in your shell:

```bash
DATABASE_URL=<prod-connection-string> pnpm db:migrate
DATABASE_URL=<prod-connection-string> pnpm db:seed
```

`pnpm db:seed` is appropriate for customer-zero bootstrap data. Revisit before a
real production launch.

## Step 6: Configure Inngest

1. Create an Inngest account and a production environment.
2. Set the app sync URL in Inngest Cloud:
   ```
   https://<vercel-domain>/api/inngest
   ```
3. Copy the event key and signing key into Vercel's production env vars.
4. Trigger a Vercel redeploy after adding the keys.

Keep production and preview Inngest environments and keys separate.

## Step 7: Custom Domain

1. In Vercel → Project → Settings → Domains, add your production domain.
2. Update DNS records as instructed.
3. `AUTH_TRUST_HOST=true` means no `NEXTAUTH_URL` is required — Auth.js derives the
   URL from the request host automatically.
4. Update Google OAuth authorized redirect URIs if applicable.

## Step 8: Smoke Test

Run this after every deployment workflow change:

1. Visit `/login`.
2. Send a magic link to a test email — confirm it arrives and login succeeds.
3. If Google OAuth is configured, sign in with Google.
4. Visit `/submit` and submit a ticket.
5. Confirm the ticket appears in `/tickets`.
6. Sign in as an expert and visit `/inbox`.
7. Confirm AI processing runs via Inngest.
8. Open `/knowledge` and confirm entries load.
9. Sign out — confirm protected routes return to `/login`.

## Useful Vercel CLI Commands

```bash
npm install -g vercel
vercel login
vercel env pull           # pull env vars to .env.local
vercel deploy             # manual deploy (preview)
vercel --prod             # deploy to production
vercel logs               # tail production logs
vercel env ls             # list configured env vars
```

## Before Real Users

- Confirm database backups are configured on the provider.
- Confirm production does not include seed demo users (or decide explicitly).
- Configure a real sending domain for magic-link email (SPF/DKIM).
- Add a custom domain.
- Confirm Inngest production event/function visibility.
- Run the smoke test checklist after every deployment workflow change.