Clerk Deploy Integration

Overview

Deploy Clerk-authenticated applications to various hosting platforms.

Prerequisites

•Clerk production instance configured
•Production API keys ready
•Hosting platform account

Instructions

Platform 1: Vercel Deployment

Step 1: Configure Environment Variables

bash

# Using Vercel CLI
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production
vercel env add CLERK_SECRET_KEY production
vercel env add CLERK_WEBHOOK_SECRET production

# Or in vercel.json

json

// vercel.json
{
  "env": {
    "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY": "@clerk-publishable-key",
    "CLERK_SECRET_KEY": "@clerk-secret-key"
  },
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

Step 2: Configure Clerk Dashboard

•Add Vercel domain to allowed origins
•Set production URLs in Clerk Dashboard
•Configure webhook endpoint

Step 3: Deploy

bash

# Deploy to production
vercel --prod

# Or link to Git for auto-deploy
vercel link

Platform 2: Netlify Deployment

Step 1: Configure Environment Variables

bash

# netlify.toml
[build]
  command = "npm run build"
  publish = ".next"

[build.environment]
  NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY = "pk_live_..."

# Add secret in Netlify Dashboard
# Site settings > Environment variables > CLERK_SECRET_KEY

Step 2: Create Netlify Functions for API

typescript

// netlify/functions/clerk-webhook.ts
import { Handler } from '@netlify/functions'
import { Webhook } from 'svix'

export const handler: Handler = async (event) => {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET!

  const svix_id = event.headers['svix-id']
  const svix_timestamp = event.headers['svix-timestamp']
  const svix_signature = event.headers['svix-signature']

  const wh = new Webhook(WEBHOOK_SECRET)

  try {
    const evt = wh.verify(event.body!, {
      'svix-id': svix_id!,
      'svix-timestamp': svix_timestamp!,
      'svix-signature': svix_signature!
    })

    // Process event
    return { statusCode: 200, body: JSON.stringify({ success: true }) }
  } catch (err) {
    return { statusCode: 400, body: 'Invalid signature' }
  }
}

Platform 3: Railway Deployment

Step 1: Configure Railway

bash

# railway.json
{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/api/health"
  }
}

Step 2: Set Environment Variables

bash

# Using 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_...

Platform 4: Docker Deployment

Dockerfile

dockerfile

FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

# Build-time args for NEXT_PUBLIC_ vars
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

ENV NODE_ENV=production

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

# Runtime env vars
ENV CLERK_SECRET_KEY=""
ENV PORT=3000

EXPOSE 3000

CMD ["node", "server.js"]

bash

# Build and run
docker build \
  --build-arg NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_... \
  -t myapp .

docker run -p 3000:3000 \
  -e CLERK_SECRET_KEY=sk_live_... \
  myapp

Platform 5: AWS Amplify

yaml

# amplify.yml
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

Clerk Dashboard Configuration

Production Domain Setup

•Go to Clerk Dashboard > Configure > Domains
•Add your production domain
•Configure SSL (automatic with most platforms)

Webhook Configuration

•Go to Clerk Dashboard > Webhooks
•Add endpoint: https://yourdomain.com/api/webhooks/clerk
•Select events to subscribe
•Copy webhook secret to environment

OAuth Redirect URLs

•Update OAuth providers with production URLs
•Add https://yourdomain.com/sso-callback
•Remove development URLs for security

Output

•Platform-specific deployment configuration
•Environment variables configured
•Webhook endpoints ready
•Production domain configured

Deployment Checklist

• Production Clerk keys configured
• Domain added to Clerk Dashboard
• Webhook endpoint configured
• OAuth redirect URLs updated
• SSL/HTTPS enabled
• Security headers configured
• Health check endpoint working

Error Handling

Error	Cause	Solution
500 on sign-in	Missing secret key	Add CLERK_SECRET_KEY to platform
Webhook fails	Wrong endpoint URL	Update URL in Clerk Dashboard
CORS error	Domain not allowed	Add domain to Clerk allowed origins
Redirect loop	Wrong sign-in URL	Check CLERK_SIGN_IN_URL config

Resources

Next Steps

Proceed to clerk-webhooks-events for webhook configuration.