clerk-deploy-integration

# Clerk Deploy Integration

## Overview
Deploy Clerk-authenticated applications to Vercel, Netlify, Railway, and other hosting platforms. Covers environment variable configuration, domain setup, and webhook endpoint configuration.

## Prerequisites
- Clerk production instance with `pk_live_` / `sk_live_` keys
- Production domain configured
- Hosting platform account

## Instructions

### Step 1: Vercel Deployment
```bash
# Add Clerk env vars to Vercel
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production
# Paste: pk_live_...
vercel env add CLERK_SECRET_KEY production
# Paste: sk_live_...
vercel env add CLERK_WEBHOOK_SECRET production
# Paste: whsec_...

# Add for preview deployments too
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY preview
vercel env add CLERK_SECRET_KEY preview
```

Configure Clerk Dashboard for Vercel:
1. Go to **Dashboard > Domains** and add your production domain
2. Set **Home URL**: `https://myapp.com`
3. Set **Sign-in URL**: `https://myapp.com/sign-in`
4. Set **Sign-up URL**: `https://myapp.com/sign-up`
5. Set **After sign-in URL**: `https://myapp.com/dashboard`

### Step 2: Netlify Deployment
```bash
# Add env vars via Netlify CLI
netlify env:set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY pk_live_...
netlify env:set CLERK_SECRET_KEY sk_live_...
```

For Netlify Functions (serverless API routes):
```typescript
// netlify/functions/clerk-auth.ts
import { createClerkClient } from '@clerk/backend'

const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY! })

export async function handler(event: any) {
  const token = event.headers.authorization?.replace('Bearer ', '')
  if (!token) {
    return { statusCode: 401, body: JSON.stringify({ error: 'No token' }) }
  }

  try {
    const session = await clerk.sessions.verifySession(token, token)
    return {
      statusCode: 200,
      body: JSON.stringify({ userId: session.userId }),
    }
  } catch {
    return { statusCode: 401, body: JSON.stringify({ error: 'Invalid token' }) }
  }
}
```

### Step 3: Railway Deployment
```bash
# Set env vars via Railway CLI
railway variables set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
railway variables set CLERK_SECRET_KEY=sk_live_...
railway variables set CLERK_WEBHOOK_SECRET=whsec_...
```

### Step 4: Docker Deployment
```dockerfile
# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# Build-time env vars (public key only)
ARG NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
ENV NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=$NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
# Runtime env vars (secret key injected at runtime, not baked into image)
# CLERK_SECRET_KEY set via docker run -e or docker-compose
EXPOSE 3000
CMD ["node", "server.js"]
```

```yaml
# docker-compose.yml
services:
  app:
    build:
      context: .
      args:
        NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: pk_live_...
    environment:
      - CLERK_SECRET_KEY=sk_live_...
      - CLERK_WEBHOOK_SECRET=whsec_...
    ports:
      - "3000:3000"
```

### Step 5: Post-Deployment Verification
```bash
#!/bin/bash
# scripts/verify-deployment.sh
set -euo pipefail

DOMAIN="${1:-https://myapp.com}"

echo "Checking deployment at $DOMAIN..."

# 1. Homepage loads
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$DOMAIN")
echo "Homepage: HTTP $STATUS"

# 2. Sign-in page accessible
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$DOMAIN/sign-in")
echo "Sign-in: HTTP $STATUS"

# 3. Health check (if implemented)
curl -s "$DOMAIN/api/clerk-health" | python3 -m json.tool 2>/dev/null || echo "No health endpoint"

# 4. Webhook endpoint reachable
STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$DOMAIN/api/webhooks/clerk")
echo "Webhook endpoint: HTTP $STATUS (400/405 expected without valid payload)"
```

## Output
- Platform-specific environment variables configured
- Clerk Dashboard domains and URLs set for production
- Docker multi-stage build with proper secret handling
- Post-deployment verification script
- Webhook endpoint accessible at production URL

## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| 500 on sign-in page | Missing `CLERK_SECRET_KEY` | Add secret key to platform env vars |
| Webhook signature fails | Wrong endpoint URL | Update URL in Clerk Dashboard > Webhooks |
| CORS error | Domain not in allowed origins | Add production domain in Clerk Dashboard > Domains |
| Redirect loop after deploy | Sign-in URL misconfigured | Check `NEXT_PUBLIC_CLERK_SIGN_IN_URL` matches route |
| Docker build missing PK | Not passed as build arg | Add `--build-arg NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=...` |

## Examples

### Vercel Preview Deployment with Clerk
```bash
# Configure Clerk for Vercel preview deployments
# Use test keys for preview, live keys for production
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY preview  # pk_test_...
vercel env add CLERK_SECRET_KEY preview                    # sk_test_...
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production  # pk_live_...
vercel env add CLERK_SECRET_KEY production                   # sk_live_...
```

## Resources
- [Deploy to Vercel](https://clerk.com/docs/deployments/deploy-to-vercel)
- [Deploy to Netlify](https://clerk.com/docs/deployments/deploy-to-netlify)
- [Clerk Domain Configuration](https://clerk.com/docs/deployments/set-up-your-domain)

## Next Steps
Proceed to `clerk-webhooks-events` for webhook configuration.