Setup Guide

This guide covers everything you need to self-host or deploy CloakMetric, from local development to production.

Prerequisites

Before you begin, make sure you have:

• Node.js 18+ and pnpm installed
• PostgreSQL 15+ (local or hosted via Neon)
• AWS Account with SES, S3, Lambda, and SNS access
• Resend Account for transactional emails
• GitHub Account for CI/CD
• Vercel Account for deployment (recommended)

Quick Start

1. Clone the repository

   git clone https://github.com/cloakmetric/cloakmetric.git
   cd cloakmetric

2. Install dependencies

   pnpm install

3. Set up environment variables

   cp .env.example .env

   Edit .env with your configuration (see Environment Variables below).

4. Set up the database

   pnpm db:push

5. Start the development server

   pnpm dev

   Open http://localhost:3000 in your browser.

Environment Variables

Create a .env file in the project root with the following variables:

Core

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@localhost:5432/cloakmetric
NEXTAUTH_URL	Your app URL	http://localhost:3000
NEXTAUTH_SECRET	Random secret for NextAuth	openssl rand -base64 32

AWS SES

Variable	Description	Example
AWS_ACCESS_KEY_ID	AWS IAM access key	AKIA...
AWS_SECRET_ACCESS_KEY	AWS IAM secret key	wJalr...
AWS_REGION	AWS region for SES	us-east-1
AWS_S3_BUCKET	S3 bucket for email storage	cloakmetric-emails
AWS_SNS_TOPIC_ARN	SNS topic for email events	arn:aws:sns:us-east-1:...

Resend

Variable	Description	Example
RESEND_API_KEY	Resend API key for transactional emails	re_...

Polar (Payments)

Variable	Description	Example
POLAR_ACCESS_TOKEN	Polar access token	polar_...
POLAR_WEBHOOK_SECRET	Polar webhook signing secret	whsec_...
POLAR_ORGANIZATION_ID	Your Polar organization ID	org_...

Upstash Redis

Variable	Description	Example
UPSTASH_REDIS_REST_URL	Upstash Redis REST URL	https://...upstash.io
UPSTASH_REDIS_REST_TOKEN	Upstash Redis REST token	AX...

Database Setup

Local PostgreSQL

1. Install PostgreSQL (if not already installed)

   macOS

   brew install postgresql@15
   brew services start postgresql@15

   Ubuntu

   sudo apt update
   sudo apt install postgresql-15
   sudo systemctl start postgresql

2. Create the database

   createdb cloakmetric

3. Set your DATABASE_URL

   DATABASE_URL="postgresql://your_user:your_password@localhost:5432/cloakmetric"

4. Run migrations

   pnpm db:push

Neon DB (Production)

Neon is the recommended hosted PostgreSQL for production deployments.

1. Create a Neon account and project at console.neon.tech

2. Copy the connection string from the dashboard

3. Set it as your DATABASE_URL

   DATABASE_URL="postgresql://user:pass@ep-cool-name-123456.us-east-1.aws.neon.tech/cloakmetric?sslmode=require"

4. Run migrations against the remote database

   pnpm db:push

Tip

Neon supports branching — create a branch for staging/preview environments so you don’t affect production data.

AWS SES Setup

CloakMetric uses AWS SES for sending and receiving emails. This section covers the full setup.

Domain Verification

1. Go to AWS Console → SES → Verified Identities
2. Click Create Identity and select Domain
3. Enter your domain (e.g., yourdomain.com)
4. AWS will provide DNS records to add

DNS Records

Add these records to your domain’s DNS:

Type	Name	Value	Purpose
TXT	_amazonses.yourdomain.com	(provided by AWS)	Domain verification
CNAME	selector1._domainkey.yourdomain.com	(provided by AWS)	DKIM signing
CNAME	selector2._domainkey.yourdomain.com	(provided by AWS)	DKIM signing
CNAME	selector3._domainkey.yourdomain.com	(provided by AWS)	DKIM signing
MX	yourdomain.com	10 inbound-smtp.us-east-1.amazonaws.com	Inbound email
TXT	yourdomain.com	v=spf1 include:amazonses.com ~all	SPF record

S3 Bucket for Email Storage

1. Create an S3 bucket (e.g., cloakmetric-emails)

2. Add a bucket policy to allow SES to write:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Service": "ses.amazonaws.com"
         },
         "Action": "s3:PutObject",
         "Resource": "arn:aws:s3:::cloakmetric-emails/*",
         "Condition": {
           "StringEquals": {
             "AWS:SourceAccount": "YOUR_AWS_ACCOUNT_ID"
           }
         }
       }
     ]
   }

3. Set AWS_S3_BUCKET in your .env

SES Receipt Rules

Receipt rules tell SES what to do with incoming emails.

1. Go to SES → Email Receiving → Rule Sets
2. Create a new rule set (or use the default)
3. Create a rule with these actions:
   • S3 action — Store email in your S3 bucket
   • Lambda action — Invoke your email processing Lambda
4. Set the recipient condition to your domain

Lambda Function

The Lambda function processes incoming emails stored in S3.

1. Create a new Lambda function (Node.js 18+ runtime)
2. Set the handler to process S3 events from SES
3. Add environment variables: DATABASE_URL, AWS_S3_BUCKET
4. Grant the Lambda role permissions to read from S3 and write to your database
5. Connect it to the SES receipt rule

Note

The Lambda function code is included in the repository under lambda/email-processor/. Deploy it using the provided deployment script.

SNS Topics

SNS topics handle email event notifications (bounces, complaints, deliveries).

1. Create an SNS topic (e.g., cloakmetric-email-events)

2. In SES, go to Configuration Sets

3. Create a configuration set and add an SNS event destination

4. Subscribe your API endpoint to the SNS topic:

   https://yourdomain.com/api/webhooks/ses

5. Set AWS_SNS_TOPIC_ARN in your .env

Configuration Set

1. Go to SES → Configuration Sets
2. Create a new configuration set (e.g., cloakmetric)
3. Add event destinations:
   • Bounce → SNS topic
   • Complaint → SNS topic
   • Delivery → SNS topic
4. The application will use this configuration set when sending emails

Production Access

Caution

By default, new SES accounts are in sandbox mode — you can only send to verified email addresses. Request production access to send to anyone.

1. Go to SES → Account Dashboard
2. Click Request Production Access
3. Fill out the form with your use case, expected volume, and bounce/complaint handling procedures
4. AWS typically reviews within 24 hours

Resend Setup

Resend handles transactional emails (account verification, password resets, notifications).

1. Create a Resend account at resend.com
2. Go to API Keys and create a new key
3. Set RESEND_API_KEY in your .env

Domain Verification (Resend)

1. Go to Domains in the Resend dashboard
2. Add your domain
3. Add the DNS records Resend provides (DKIM, SPF)
4. Wait for verification (usually a few minutes)

Tip

If you’re already using AWS SES for your domain, make sure the SPF record includes both: v=spf1 include:amazonses.com include:resend.com ~all

Polar Setup

Polar handles payments and subscription management.

1. Create a Polar organization at polar.sh

2. Create subscription products matching your plans:

   • Free — $0/month
   • Pro — $29/month
   • Business — $79/month

3. Go to Settings → Developers and create an access token

4. Set up a webhook endpoint:

   https://yourdomain.com/api/webhooks/polar

5. Add to your .env:

   POLAR_ACCESS_TOKEN=polar_...
   POLAR_WEBHOOK_SECRET=whsec_...
   POLAR_ORGANIZATION_ID=org_...

Upstash Redis

Upstash provides serverless Redis for rate limiting and caching.

1. Create an Upstash account at upstash.com

2. Create a new Redis database

3. Copy the REST URL and token from the dashboard

4. Add to your .env:

   UPSTASH_REDIS_REST_URL=https://...upstash.io
   UPSTASH_REDIS_REST_TOKEN=AX...

Production Deployment

Vercel + Neon Stack (Recommended)

1. Connect your repository to Vercel

   Import your GitHub repository at vercel.com/new.

2. Set environment variables

   Add all environment variables from your .env to the Vercel project settings under Settings → Environment Variables.

3. Configure the build

   Vercel auto-detects Next.js. The default settings should work:

   • Build Command: pnpm build
   • Output Directory: .next

4. Set up the production database

   Use your Neon production connection string as DATABASE_URL.

5. Deploy

   Push to main to trigger automatic deployment.

Custom Domains

For Pro+ plans, users can connect custom domains for their aliases.

1. In Vercel, go to Settings → Domains
2. Add your custom domain (e.g., docs.cloakmetric.com)
3. Update DNS records as instructed by Vercel
4. SSL is provisioned automatically

CI/CD Pipeline

GitHub Actions

The repository includes two GitHub Actions workflows:

PR Checks (.github/workflows/ci.yml)

Runs on every pull request:

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check
      - run: pnpm test

Deploy Workflow (.github/workflows/deploy.yml)

Runs on push to main:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      # Run database migrations
      - name: Run migrations
        run: pnpm db:push
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

      # Vercel handles the actual deployment via its GitHub integration
      # This step runs migrations before the deploy completes

Note

If you’re using the Vercel GitHub integration, deployments are triggered automatically. The deploy workflow above is primarily for running database migrations.

Troubleshooting

Common Issues

Emails not being received

• Check MX records point to SES inbound SMTP
• Verify the SES receipt rule is active
• Check Lambda function logs in CloudWatch
• Ensure the S3 bucket policy allows SES writes

Bounces increasing suddenly

• Check SES sending quotas
• Verify domain DNS records haven’t changed
• Review SES reputation dashboard
• Check if your domain was added to any blocklists

Authentication errors

• Verify NEXTAUTH_SECRET is set
• Check NEXTAUTH_URL matches your deployment URL
• Ensure database is accessible and migrations are current

Rate limiting issues

• Check Upstash Redis connection
• Verify UPSTASH_REDIS_REST_URL and token are correct
• Monitor rate limit usage in the Upstash dashboard

Payment webhook failures

• Verify POLAR_WEBHOOK_SECRET matches your Polar config
• Check that the webhook URL is publicly accessible
• Review webhook delivery logs in the Polar dashboard

Database connection errors

• For Neon: ensure ?sslmode=require is in your connection string
• Check that your IP is allowed (if using IP allowlists)
• Verify credentials haven’t expired

Production Checklist

Before going live, verify everything on this list:

Infrastructure

• PostgreSQL database provisioned (Neon recommended)
• AWS SES domain verified and out of sandbox
• S3 bucket created with correct policy
• Lambda function deployed and connected
• SNS topics created and subscribed
• SES configuration set active
• Upstash Redis database created

DNS

• MX records pointing to SES
• SPF record includes amazonses.com
• DKIM records configured
• Domain verified in SES
• Domain verified in Resend
• Custom domain configured in Vercel

Services

• Resend API key configured
• Polar products and webhooks set up
• All environment variables set in Vercel
• GitHub Actions secrets configured

Testing

• Send a test email through an alias
• Receive an inbound email and verify forwarding
• Test bounce and complaint handling
• Complete a subscription flow
• Verify rate limiting works
• Run the full test suite