Installation

Prerequisites

• Node.js 22+ and pnpm 9+
• Docker and Docker Compose (for the database)
• A PostgreSQL 17 instance (or use the bundled Compose file)

1. Clone and install dependencies

git clone https://github.com/circle-rd/auth-service.git
cd auth-service
pnpm install
cd frontend && pnpm install && cd ..

2. Configure the environment

cp .env.example .env

Open .env and fill in the required variables. At minimum you need:

# Generate a 32-byte secret
openssl rand -base64 32   # paste as BETTER_AUTH_SECRET

BETTER_AUTH_SECRET=<32-byte random string>
BETTER_AUTH_URL=http://localhost:3001   # public base URL of this service
DATABASE_URL=postgres://auth:auth_secret@localhost:5433/auth_service

See Environment variables for the full reference.

3. Start the database

The dev Compose file starts only PostgreSQL (exposed on port 5433 to avoid conflicts with a local instance on 5432):

docker compose -f docker-compose.dev.yml up -d postgres

4. Push the schema

pnpm db:push

db:push synchronises the Drizzle schema directly to the database without generating migration files — suitable for development. In production, use pnpm db:migrate or let the container run migrations automatically at startup.

5. Build the frontend

The Vue 3 SPA must be built before the backend can serve it:

pnpm build:frontend

This outputs the built SPA to frontend-dist/.

Production deployment

Build and run everything with Docker Compose:

# Edit .env with production values (never commit this file)
docker compose build
docker compose up -d

The production Compose file (docker-compose.yml) starts both postgres and auth-service. Database migrations run automatically at container startup via runMigrations() in src/migrate.ts.

Note: Add a reverse proxy (Traefik, nginx, Caddy) in front of Auth Service for TLS termination. The service binds to 0.0.0.0:3001 by default.