Self-Hosting Sigma Auth

Deploy your own Sigma Auth instance on Vercel for complete control and full customization. Sigma Auth is built with Next.js 15, Better Auth, Supabase PostgreSQL, and Upstash Redis.

Quick Deploy Options

Choose your preferred hosting platform:

⭐ Deploy to Vercel (Recommended)

Best for: Production deployments, zero-config experience, automatic HTTPS

The one-click deploy automatically sets up:

• PostgreSQL database via Vercel Postgres
• Redis/KV storage via Vercel KV
• Environment variables with guided setup
• HTTPS with custom domain support
• Edge runtime for global low latency

🐳 Deploy to Dokploy (Self-Hosted)

Best for: Privacy-conscious deployments, full control, VPS hosting

Deploy to Dokploy

What is Dokploy?

• Free, open-source alternative to Vercel/Railway
• Self-hosted on your own VPS (DigitalOcean, Hetzner, AWS, etc.)
• Includes PostgreSQL and Redis built-in
• Docker-based with automatic SSL certificates
• One-click app deployment from Git

Setup Steps:

1. Install Dokploy on your VPS (5-minute setup)
2. Connect your GitHub repository
3. Dokploy automatically detects Next.js and sets up:
   • PostgreSQL database
   • Redis instance
   • SSL certificates
   • Environment variables
4. Deploy with one click

See Dokploy Self-Hosting Guide below for detailed instructions.

🚂 Deploy to Railway

Best for: Quick staging environments, affordable pricing

Railway provides:

• Automatic PostgreSQL and Redis provisioning
• Built-in CI/CD from GitHub
• Free $5/month credits
• Predictable pricing

🌊 Deploy to Coolify

Alternative self-hosted option similar to Dokploy:

Deploy to Coolify

Coolify offers:

• Self-hosted PaaS on your VPS
• Docker Compose support
• Automatic SSL with Let's Encrypt
• Built-in monitoring

🎨 Deploy to Render

Best for: Free tier testing, simple pricing

Deploy to Render

Render features:

• Free tier available (with limitations)
• Automatic PostgreSQL and Redis
• Global CDN
• Auto-deploy from Git

Architecture Overview

Stack:

• Framework: Next.js 15 with App Router (Edge Runtime)
• Authentication: Better Auth with custom sigma plugin
• Database: Supabase PostgreSQL (pooled connections)
• Session Storage: Upstash Redis / Vercel KV
• Bitcoin Libraries: bitcoin-auth, bitcoin-backup, @bsv/sdk
• Wallet Support: Yours Wallet (BSV), RainbowKit (EVM)

Manual Setup

Prerequisites

• Vercel account (required for deployment)
• Supabase account (for PostgreSQL database)
• Upstash account (for Redis/KV storage) OR Vercel KV
• Bun (recommended) or Node.js 18+
• Git

1. Clone the Repository

git clone https://github.com/b-open-io/sigma-auth.git
cd sigma-auth

2. Install Dependencies

# Using Bun (recommended)
bun install

# Or using npm
npm install

3. Set Up Supabase PostgreSQL

1. Create a new Supabase project at supabase.com
2. Get your pooled connection string from Project Settings → Database
3. Copy the connection string (starts with postgresql://...)

Note: Better Auth will automatically create the required tables on first run.

4. Set Up Redis/KV Storage

Option A: Vercel KV (Recommended for Vercel deployments)

1. Create a KV store in your Vercel dashboard
2. Link it to your project
3. Copy the KV_REST_API_URL and KV_REST_API_TOKEN

Option B: Upstash Redis (Works anywhere)

1. Create a Redis database at upstash.com
2. Copy the REST API URL and token

5. Configure Environment Variables

Create .env.local for local development:

# Database (Required)
POSTGRES_URL=postgresql://user:pass@host:5432/db

# Better Auth (Required)
BETTER_AUTH_SECRET=<generate-with-openssl-rand-base64-32>
BETTER_AUTH_URL=http://localhost:1911  # Dev
# BETTER_AUTH_URL=https://auth.yourdomain.com  # Production

# Redis/KV Storage (Required)
KV_REST_API_URL=https://your-redis.upstash.io
KV_REST_API_TOKEN=your-token-here

# Owner Access (Optional)
OWNER_PUBKEYS=<comma-separated-bitcoin-pubkeys-for-admin-access>

# OAuth Providers (Optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

Generate the auth secret:

openssl rand -base64 32

6. Run Locally

# Development server on port 1911
bun run dev

# Production build
bun run build
bun run start

Vercel Deployment

Link to Vercel

# Install Vercel CLI
bun add -g vercel

# Link to your Vercel project
vercel link

# Pull environment variables (if already set)
vercel env pull

Set Environment Variables

# Set production environment variables
vercel env add POSTGRES_URL production
vercel env add BETTER_AUTH_SECRET production
vercel env add BETTER_AUTH_URL production
vercel env add KV_REST_API_URL production
vercel env add KV_REST_API_TOKEN production

# Optional OAuth providers
vercel env add GOOGLE_CLIENT_ID production
vercel env add GOOGLE_CLIENT_SECRET production
vercel env add GITHUB_CLIENT_ID production
vercel env add GITHUB_CLIENT_SECRET production

Deploy

# Preview deployment
vercel

# Production deployment
vercel --prod

Custom Domain Setup

1. Configure Domain in Vercel

1. Go to your Vercel project settings
2. Navigate to "Domains"
3. Add your custom domain (e.g., auth.yourdomain.com)
4. Follow DNS configuration instructions

2. Update Environment Variables

# Update BETTER_AUTH_URL for production
vercel env add BETTER_AUTH_URL production
# Enter: https://auth.yourdomain.com

3. Update OAuth Redirect URIs

Update your OAuth provider settings with new redirect URIs:

• Google: https://auth.yourdomain.com/api/auth/callback/google
• GitHub: https://auth.yourdomain.com/api/auth/callback/github

Environment Configuration

Required Variables

Optional Variables

OAuth Provider Setup

Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI: https://auth.yourdomain.com/api/auth/callback/google
6. Copy client ID and secret to environment variables

GitHub OAuth

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set Authorization callback URL: https://auth.yourdomain.com/api/auth/callback/github
4. Copy client ID and secret to environment variables

Monitoring & Debugging

View Logs

# Vercel CLI logs
vercel logs --follow

# Or view in Vercel dashboard

Common Issues

"Failed to initialize database adapter"

• Ensure POSTGRES_URL is set correctly
• Verify Supabase connection string uses pooled connection
• Check database is accessible from Vercel's network

NODE_ENV Issues

• Never set NODE_ENV manually in your shell/zshrc
• Next.js manages this automatically
• If issues persist, unset: unset NODE_ENV

OAuth Redirect Errors

• Verify BETTER_AUTH_URL matches your domain exactly
• Check OAuth provider redirect URIs are configured correctly
• Ensure no trailing slashes in URLs

Health Check

Test your deployment:

# Check server is responding
curl https://auth.yourdomain.com/api/health

# Test OAuth endpoints
curl https://auth.yourdomain.com/api/oauth/authorize?redirect_uri=http://localhost:3000/callback&response_type=code&state=test

Security Best Practices

Database Security

• Use Supabase's pooled connection for serverless
• Enable Row Level Security (RLS) policies in Supabase
• Restrict database access to Vercel's IP ranges
• Regularly rotate database passwords

Environment Variables

• Never commit .env.local to version control
• Use Vercel's encrypted environment variables
• Rotate secrets regularly (especially BETTER_AUTH_SECRET)
• Use different secrets for preview vs production

CORS Configuration

Configure allowed origins in your application:

// Example CORS configuration
const allowedOrigins = [
  'https://yourdomain.com',
  'https://www.yourdomain.com',
];

See the security guide for detailed configuration instructions.

Scaling & Performance

Database Connection Pooling

Supabase's pooled connection (POSTGRES_URL) is optimized for serverless:

• Handles connection pooling automatically
• Supports thousands of concurrent connections
• Works seamlessly with Vercel's Edge Runtime

Redis/KV Optimization

Session storage uses Redis/KV with:

• 7-day TTL for sessions
• Efficient key expiration
• Low latency global reads

Monitoring

Monitor your deployment with:

• Vercel Analytics: Built-in performance monitoring
• Upstash Metrics: Redis/KV usage and latency
• Supabase Logs: Database query performance
• Better Auth Events: Authentication events and errors

Backup & Recovery

Database Backups

Supabase provides automatic backups:

1. Navigate to Database → Backups in Supabase dashboard
2. Configure backup schedule (daily recommended)
3. Enable Point-in-Time Recovery (PITR) for critical deployments

Environment Variable Backup

# Export all environment variables
vercel env pull .env.backup

# Store securely (encrypted) in your secrets manager

Troubleshooting

Build Failures

# Clear build cache
vercel --force

# Check build logs
vercel logs --since 1h

Runtime Errors

# Stream production logs
vercel logs --follow production

# Search for specific errors
vercel logs --grep "error" production

Dokploy Setup

Why Dokploy?

Dokploy is ideal for organizations that need:

• Full data sovereignty (host on your own infrastructure)
• No usage limits or metered pricing
• Privacy-first architecture
• Complete control over updates and dependencies

Prerequisites

• A VPS with at least 2GB RAM (DigitalOcean, Hetzner, Vultr, AWS EC2, etc.)
• Ubuntu 20.04+ or Debian 11+
• SSH access to your server
• A domain name pointing to your server

Installation

Step 1: Install Dokploy on Your VPS

SSH into your server and run the one-line installer:

curl -sSL https://dokploy.com/install.sh | sh

This installs:

• Docker and Docker Compose
• Traefik reverse proxy for SSL
• Dokploy dashboard
• PostgreSQL and Redis containers

Step 2: Access Dokploy Dashboard

Navigate to https://your-server-ip:3000 and complete the setup wizard.

Step 3: Create a New Project

1. Click "New Project"
2. Enter project name: sigma-auth
3. Connect your GitHub repository: https://github.com/b-open-io/sigma-auth

Step 4: Configure Services

Dokploy auto-detects Next.js and creates:

# Auto-generated configuration
services:
  web:
    build: .
    ports:
      - "1911:1911"
    environment:
      POSTGRES_URL: ${DATABASE_URL}
      KV_REST_API_URL: ${REDIS_URL}
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
      BETTER_AUTH_URL: https://auth.yourdomain.com

  postgres:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

Step 5: Set Environment Variables

In Dokploy dashboard, navigate to your project settings and add:

BETTER_AUTH_SECRET=your-generated-secret  # Use: openssl rand -base64 32
BETTER_AUTH_URL=https://auth.yourdomain.com
OWNER_PUBKEYS=your-bitcoin-pubkey

Database and Redis URLs are auto-configured by Dokploy.

Step 6: Configure Domain

1. In Dokploy, go to "Domains" tab
2. Add domain: auth.yourdomain.com
3. Dokploy automatically provisions SSL certificate via Let's Encrypt
4. Update your DNS A record to point to your server IP

Step 7: Deploy

Click "Deploy" button. Dokploy will:

• Build your Next.js application
• Start PostgreSQL and Redis
• Configure Traefik reverse proxy
• Provision SSL certificate
• Deploy to https://auth.yourdomain.com

Post-Deployment

Database Migrations

Better Auth auto-creates required tables on first run. No manual migrations needed.

Backup Configuration

Dokploy includes backup tools. Configure daily backups:

# In Dokploy dashboard
Settings → Backups → Enable Daily Backups

Monitoring

Dokploy provides built-in monitoring:

• Container logs via dashboard
• Resource usage graphs
• SSL certificate renewal status

Scaling

To scale horizontally:

1. Use Dokploy's "Scale" feature to run multiple web instances
2. Traefik automatically load-balances traffic
3. PostgreSQL uses connection pooling for concurrency

Dokploy vs. Vercel

Recommendation: Use Vercel for quick prototyping, Dokploy for production self-hosting.

Railway Template Configuration

To enable the Railway one-click deploy button, create railway.json in your repository root:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "numReplicas": 1,
    "startCommand": "bun run start",
    "restartPolicyType": "ON_FAILURE",
    "healthcheckPath": "/api/health",
    "healthcheckTimeout": 100
  },
  "services": [
    {
      "name": "postgres",
      "type": "postgres"
    },
    {
      "name": "redis",
      "type": "redis"
    }
  ]
}

Then update your Railway deploy button to:

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/sigma-auth)

Next Steps

• Integration Guide - Connect your applications
• API Reference - Detailed endpoint documentation
• Security Guide - Harden your deployment
• Customization - Brand your instance

Support

• GitHub Issues: Report bugs
• Documentation: Full API reference
• Discord: Join our community