> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whilst.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> Deploy Whilst to production

Whilst runs as a hybrid architecture:

* **Web App**: Next.js on Vercel (`app.whilst.io`)
* **Bot Backend**: AWS Lambda (event-intake + job-worker)
* **Database**: Neon PostgreSQL (serverless, shared by web app and bot)
* **Secrets**: AWS Secrets Manager

## Web App (Vercel)

The Next.js web app auto-deploys on push to `main` via Vercel.

### Environment Variables

Set these in the Vercel dashboard under **Settings → Environment Variables**:

```bash theme={null}
# WorkOS
WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...
WORKOS_REDIRECT_URI=https://app.whilst.io/api/auth/workos/callback

# Session
SESSION_SECRET=your-production-secret

# Database (pooled Neon connection string)
POSTGRES_URL=postgresql://user:pass@ep-xxx-pooler.us-east-1.aws.neon.tech/whilst?sslmode=require

# OpenAI
OPENAI_API_KEY=sk-...

# Application
NEXT_PUBLIC_APP_URL=https://app.whilst.io
```

### Deploy

```bash theme={null}
git push origin main
# Vercel auto-deploys
```

## Database (Neon)

The database is hosted on [Neon](https://neon.tech) (serverless Postgres), not on AWS.

<Info>
  **Key differences from traditional Postgres hosting:**

  * No VPC, subnets, or security groups — Neon is accessed over the internet with SSL
  * Built-in connection pooler replaces RDS Proxy for Lambda connections
  * Use Neon branches (not snapshots) for dev/staging environments
  * Scale-to-zero billing — pay only for compute hours used
</Info>

### Setup

1. Create a project at [console.neon.tech](https://console.neon.tech) (region: `aws-us-east-1`)
2. Enable `vector` and `uuid-ossp` extensions
3. Note two connection strings from the Neon dashboard:
   * **Pooled** (for app runtime): `postgres://...@ep-xxx-pooler.neon.tech/whilst?sslmode=require`
   * **Direct** (for migrations): `postgres://...@ep-xxx.neon.tech/whilst?sslmode=require`

### Migrations

Always use the **direct** (non-pooled) connection string for migrations:

```bash theme={null}
export POSTGRES_URL="postgresql://user:pass@ep-xxx.us-east-1.aws.neon.tech/whilst?sslmode=require"
pnpm db:migrate
```

<Warning>
  Always run migrations in staging first (use a Neon branch) and verify before applying to production.
</Warning>

## Backend Services (AWS)

Lambda functions are deployed via the AWS SDK deploy script.

### Prerequisites

* AWS CLI configured with appropriate credentials
* Node.js 20+ and pnpm 9+

### Deploy

```bash theme={null}
# Build all packages
pnpm build

# Package Lambda functions
pnpm run package:lambdas

# Deploy infrastructure
pnpm run infra:deploy -- --env staging
```

### Staging vs Production

```bash theme={null}
# Deploy to staging
pnpm run infra:deploy -- --env staging

# Deploy to production
pnpm run infra:deploy -- --env production
```

<Note>
  The deploy script creates/updates Lambdas, SQS queues, and API Gateway. The database is managed separately on Neon.
</Note>

## CI/CD

The GitHub Actions workflow (`.github/workflows/ci.yml`) runs lint, tests, and build on all pushes and PRs against `main`.

## Monitoring

* **CloudWatch**: Lambda logs and metrics
* **X-Ray**: Distributed tracing across services
* **DLQ alerts**: SQS dead letter queue failures trigger Slack notifications via SNS
* **Neon Dashboard**: Database metrics, query performance, branch management