Self-Host

Better Auth Console is open source and designed to be self-hosted. Deploy on your own infrastructure for full control over your data.

Why Self-Host?

Data Control: Your authentication data never leaves your infrastructure
Compliance: Meet regulatory requirements for data residency
No Usage Limits: No per-user or per-request pricing
Customisation: Modify the source code as needed

Deployment Options

Prerequisites

Node.js 20+
pnpm 10.4.1+
PostgreSQL with better-auth database

Build and Run

# Clone and install
git clone https://github.com/arc0ai/better-auth-console.git
cd better-auth-console
pnpm install

# Configure your instances
# Edit instances.config.ts

# Build for production
pnpm build

# Start the server
pnpm start

The console runs on port 3000 by default.

Process Manager (PM2)

For production, use PM2 to keep the server running:

# Install PM2
npm install -g pm2

# Start with PM2
pm2 start pnpm --name "bac" -- start

# Save process list
pm2 save

# Setup startup script
pm2 startup

Environment Variables

.env

# Required: Your better-auth database(s)
PROD_DATABASE_URL=postgresql://user:password@host:5432/db
STAGING_DATABASE_URL=postgresql://user:password@host:5432/db_staging

# Optional: Port configuration
PORT=3000

Dockerfile

FROM node:20-alpine AS base

# Install pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

WORKDIR /app

# Copy package files
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
COPY apps/web/package.json ./apps/web/
COPY packages/*/package.json ./packages/

# Install dependencies
RUN pnpm install --frozen-lockfile

# Copy source
COPY . .

# Build
RUN pnpm build

# Production image
FROM node:20-alpine AS runner
WORKDIR /app

COPY --from=base /app ./

ENV NODE_ENV=production
EXPOSE 3000

CMD ["pnpm", "start"]

Docker Compose

docker-compose.yml

version: '3.8'

services:
  console:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PROD_DATABASE_URL=postgresql://user:password@db:5432/myapp
    restart: unless-stopped

  # Optional: Include your database
  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Run with Docker

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f console

# Stop
docker-compose down

Deploy to Vercel

Or deploy manually:

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Environment Variables

Configure in Vercel Dashboard → Settings → Environment Variables:

Variable	Value
`PROD_DATABASE_URL`	Your production database URL
`STAGING_DATABASE_URL`	Your staging database URL (optional)

Important Notes

Vercel serverless functions have connection limits. For high-traffic deployments, consider using a connection pooler like PgBouncer or Neon's pooled connections.

Use pooled connection strings:

# Direct connection (limited)
postgresql://user:password@host:5432/db

# Pooled connection (recommended)
postgresql://user:password@host:6543/db?pgbouncer=true

Production Checklist

Before deploying to production:

Configure all instance database URLs
Test instance connections locally
Set up SSL/TLS for database connections
Configure reverse proxy (nginx, Caddy) with HTTPS
Set up monitoring and logging
Configure backup strategy for your databases
Review access controls (who can access the console)

Securing the Console

The console doesn't include built-in authentication. Secure access using:

Reverse Proxy Authentication

Use nginx with basic auth or OAuth proxy:

nginx.conf

location / {
    auth_basic "Console Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://localhost:3000;
}

Network Isolation

Deploy in a private network accessible only via VPN or bastion host.

Cloud IAM

Use your cloud provider's identity management:

AWS: ALB with Cognito
GCP: IAP (Identity-Aware Proxy)
Azure: App Service Authentication

Updates

Pull the latest changes and rebuild:

git pull origin main
pnpm install
pnpm build
pnpm start

Or with Docker:

docker-compose pull
docker-compose up -d --build

Next Steps

Configuration - Configure instances
Instances - Multiple instance setup
Plugins - Plugin configuration

Self-Host

On this page