Manual Setup

Overview

If you prefer not to use Dev Containers, or if you’re working on a system without Docker, you can set up the Auth UI Boilerplate manually. This guide covers installation on macOS, Linux, and Windows.

The Dev Container setup is recommended for most users as it ensures a consistent environment. Only use manual setup if you have specific requirements or cannot use Docker.

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js 22+

JavaScript runtime (LTS version recommended)

PostgreSQL

Relational database (version 14+ recommended)

Git

Version control system

npm or pnpm

Package manager (included with Node.js)

Verify Prerequisites

Confirm that you have the required versions installed:

node --version  # Should be v22.0.0 or higher
npm --version   # Should be v10.0.0 or higher
psql --version  # Should be 14.x or higher

Node.js 22+ is required for this boilerplate. Earlier versions may not support the latest Next.js 16 and React 19 features.

Installation Steps

Clone the Repository

Clone the Auth UI Boilerplate repository:

git clone https://github.com/your-org/auth-ui-boilerplate.git
cd auth-ui-boilerplate

Set Up PostgreSQL Database

Create a new PostgreSQL database for the application.

Option 1: Using psql (Command Line)

# Connect to PostgreSQL as the postgres user
psql -U postgres

# Create a new database
CREATE DATABASE auth_boilerplate;

# Create a user (optional - for better security)
CREATE USER auth_user WITH PASSWORD 'your-secure-password';

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE auth_boilerplate TO auth_user;

# Exit psql
\q

Option 2: Using pgAdmin (GUI)

Open pgAdmin and connect to your PostgreSQL server
Right-click Databases → Create → Database
Name: auth_boilerplate
Owner: postgres (or create a dedicated user)
Click Save

Option 3: Using Docker (Standalone PostgreSQL)

If you have Docker but don’t want the full Dev Container:

docker run --name auth-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=auth_boilerplate \
  -p 5432:5432 \
  -d postgres:18

The database name doesn’t have to be auth_boilerplate — use whatever name you prefer, and update DATABASE_URL accordingly.

Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Open .env in your editor and update the DATABASE_URL to match your local PostgreSQL configuration:

.env

# Update this to match your local PostgreSQL setup
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/auth_boilerplate

# Or if you created a dedicated user:
# DATABASE_URL=postgresql://auth_user:your-secure-password@localhost:5432/auth_boilerplate

# Generate a secret: openssl rand -base64 32
BETTER_AUTH_SECRET=change-me-to-a-random-secret

# Auth URLs (keep as localhost for local dev)
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000

# Google OAuth (get from Google Cloud Console)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Optional: Backend API URLs
# BACKEND_API_URL=http://localhost:8080
# NEXT_PUBLIC_BACKEND_API_URL=http://localhost:8080

Generate Better Auth Secret

Use OpenSSL to generate a secure random secret:

openssl rand -base64 32

Copy the output and replace BETTER_AUTH_SECRET in .env.

Set Up Google OAuth (Optional)

To enable Google sign-in:

Go to Google Cloud Console
Create OAuth 2.0 credentials (see Quickstart guide for detailed steps)
Set redirect URI to http://localhost:3000/api/auth/callback/google
Copy Client ID and Secret to .env

Google OAuth is optional. You can use email/password authentication without it.

Install Dependencies

Install all required npm packages:

npm install

This installs all dependencies defined in package.json, including:

next (v16.1.6) — React framework
better-auth (v1.4.18) — Authentication library
drizzle-orm (v0.45.1) — Database ORM
pg (v8.18.0) — PostgreSQL client
axios (v1.13.5) — HTTP client
tailwindcss (v4) — CSS framework
lucide-react — Icon library

Push Database Schema

Create the required database tables:

npm run db:push

This runs drizzle-kit push, which:

Connects to your PostgreSQL database using DATABASE_URL
Reads the schema from src/db/schema.ts
Creates tables: user, session, account, verification, jwks

You should see output like:

Reading config from drizzle.config.ts
Using 'pg' driver for database querying
Pushing schema to database...
✓ Schema pushed successfully!

Verify Tables

Check that the tables were created:

psql -U postgres -d auth_boilerplate -c "\dt"

Expected output:

         List of relations
 Schema |     Name     | Type  |  Owner
--------+--------------+-------+----------
 public | account      | table | postgres
 public | jwks         | table | postgres
 public | session      | table | postgres
 public | user         | table | postgres
 public | verification | table | postgres

Start the Development Server

Run the Next.js development server:

npm run dev

The application will start on http://localhost:3000.Expected output:

▲ Next.js 16.1.6
- Local:        http://localhost:3000
- Environments: .env

✓ Starting...
✓ Ready in 1.5s

The first start may take longer as Next.js compiles the application. Subsequent starts will be faster.

Verify Installation

Open your browser and navigate to http://localhost:3000.You should see the Auth UI Boilerplate home page with:

Navigation bar with Sign In and Sign Up buttons
“How It Works” section
Backend integration guides
Theme toggle (light/dark mode)

Test Authentication

Click Sign Up and create an account with email/password
After signup, you should be automatically signed in
Verify your session appears in the “Authentication Status” card
Test sign out and sign in again

Test Google OAuth (if configured)

Click Sign In
Click Sign in with Google
Complete the OAuth flow
Verify you’re redirected back and authenticated

Database Management Commands

The boilerplate includes several Drizzle commands for managing your database:

Command	Description
`npm run db:push`	Push schema changes directly to database (dev only)
`npm run db:generate`	Generate SQL migration files from schema changes
`npm run db:migrate`	Apply pending migrations to the database
`npm run db:studio`	Open Drizzle Studio (visual database browser)

Drizzle Studio

To visually browse and edit your database:

npm run db:studio

This opens Drizzle Studio at https://local.drizzle.studio, where you can:

View all tables and data
Edit records directly
Run queries
Inspect relationships

Drizzle Studio is for development only. Do not expose it in production.

Production Deployment

For production deployments:

Use migrations instead of push:

npm run db:generate  # Generate migration files
npm run db:migrate   # Apply migrations in production

Set environment variables on your hosting platform:
- DATABASE_URL — Production PostgreSQL connection string
- BETTER_AUTH_SECRET — Strong random secret (32+ characters)
- BETTER_AUTH_URL — Production URL (e.g., https://app.example.com)
- NEXT_PUBLIC_BETTER_AUTH_URL — Same as BETTER_AUTH_URL
- GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — Update redirect URI to production URL

Update Google OAuth redirect URI:

https://your-domain.com/api/auth/callback/google

Build and start:
```
npm run build
npm run start
```

Troubleshooting

Connection refused to PostgreSQL

Symptoms: Error: connect ECONNREFUSED 127.0.0.1:5432Solutions:

Ensure PostgreSQL is running: sudo service postgresql status (Linux) or check Activity Monitor (macOS)
Verify the port: PostgreSQL defaults to 5432, but check your config
Check DATABASE_URL format: postgresql://user:password@host:port/database
Try connecting with psql: psql -U postgres -h localhost

Authentication failed for user

Symptoms: error: password authentication failed for user "postgres"Solutions:

Verify your PostgreSQL password is correct in DATABASE_URL

Reset the postgres password:

sudo -u postgres psql
ALTER USER postgres PASSWORD 'newpassword';

Update .env with the new password

Node.js version too old

Symptoms: Error: The engine "node" is incompatible with this moduleSolutions:

Upgrade to Node.js 22+: Download from nodejs.org
Or use nvm (Node Version Manager):
```
nvm install 22
nvm use 22
```
Verify: node --version

Port 3000 already in use

Symptoms: Error: listen EADDRINUSE: address already in use :::3000Solutions:

Find and kill the process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Or run on a different port:
```
PORT=3001 npm run dev
```

drizzle-kit command not found

Symptoms: bash: drizzle-kit: command not foundSolutions:

Run via npm script: npm run db:push (not drizzle-kit push)
Or install globally: npm install -g drizzle-kit
Verify installation: npx drizzle-kit --version

What’s Next?

Environment Variables

Detailed guide to all configuration options

Database Schema

Learn how to add custom tables with Drizzle

Backend Integration

Connect Go, Python, or Node.js backends

Dev Container Setup

Alternative setup using Dev Containers

Get Started

Configuration

Core Features

Backend Integration

Database

Development

Overview

Prerequisites

Node.js 22+

PostgreSQL

Git

npm or pnpm

Verify Prerequisites

Installation Steps

Option 1: Using psql (Command Line)

Option 2: Using pgAdmin (GUI)

Option 3: Using Docker (Standalone PostgreSQL)

Generate Better Auth Secret

Set Up Google OAuth (Optional)

Verify Tables

Test Authentication

Test Google OAuth (if configured)

Database Management Commands

Drizzle Studio

Production Deployment

Troubleshooting

What’s Next?

Environment Variables

Database Schema

Backend Integration

Dev Container Setup

Build docs developers (and LLMs) love

Get Started

Configuration

Core Features

Backend Integration

Database

Development

​Overview

​Prerequisites

Node.js 22+

PostgreSQL

Git

npm or pnpm

​Verify Prerequisites

​Installation Steps

​Option 1: Using psql (Command Line)

​Option 2: Using pgAdmin (GUI)

​Option 3: Using Docker (Standalone PostgreSQL)

​Generate Better Auth Secret

​Set Up Google OAuth (Optional)

​Verify Tables

​Test Authentication

​Test Google OAuth (if configured)

​Database Management Commands

​Drizzle Studio

​Production Deployment

​Troubleshooting

​What’s Next?

Environment Variables

Database Schema

Backend Integration

Dev Container Setup

Build docs developers (and LLMs) love

Overview

Prerequisites

Verify Prerequisites

Installation Steps

Option 1: Using psql (Command Line)

Option 2: Using pgAdmin (GUI)

Option 3: Using Docker (Standalone PostgreSQL)

Generate Better Auth Secret

Set Up Google OAuth (Optional)

Verify Tables

Test Authentication

Test Google OAuth (if configured)

Database Management Commands

Drizzle Studio

Production Deployment

Troubleshooting

What’s Next?