Installation
For a step-by-step first run, follow the Quick start. This page lists what auth-service needs and the versions it is tested with.
Prerequisites
| Requirement | Version | Needed for |
|---|---|---|
| Docker and Docker Compose v2 | recent | Running the published image, and the PostgreSQL container |
| PostgreSQL | 17 | Database (provided by the Compose file as postgres:17-alpine) |
| Node.js | 22 | Running from source. The Docker image is node:22-alpine |
| pnpm | 10 (packageManager is pnpm@10.33.0) | Running from source. The frontend/ workspace is a separate pnpm project |
Running the published image needs only Docker: no Node.js, no pnpm.
Get the code
git clone https://github.com/circle-rd/auth-service.git
cd auth-service
pnpm install # backend dependencies
cd frontend && pnpm install # admin SPA dependencies, only to work on the UI
pnpm install at the root does not install the frontend/ dependencies.
Environment
cp .env.example .env
openssl rand -base64 32 # value for BETTER_AUTH_SECRET
.env.example documents the main variables (the complete list is the environment variables reference; for example APP_NAME, APP_LOGO_URL and TEMPLATES_DIR are not in the file). The Compose file expands ${DOMAIN} and ${PUBLIC_SCHEME} references, but pnpm dev does not: write final values when running from source. The required settings are described in Configuration.
The Compose file publishes PostgreSQL on port 5433 (POSTGRES_PORT) to stay clear of a local instance on 5432. In the Compose network the host name is postgres; from the host it is localhost:5433.
Runtime dependencies
Versions below are the ranges declared in package.json.
| Package | Version | Purpose |
|---|---|---|
better-auth | ^1.7.7 | Authentication engine and plugins (organization, two-factor, admin, JWT…) |
@better-auth/oauth-provider | ^1.7.7 | OAuth 2.1 / OIDC provider |
@better-auth/passkey | ^1.7.7 | WebAuthn passkeys (server side) |
@better-auth/drizzle-adapter | ^1.7.7 | Drizzle ORM adapter |
fastify | ^5.8.5 | HTTP server |
@fastify/cors, @fastify/helmet, @fastify/rate-limit, @fastify/static | ^11.2.0, ^13.1.1, ^10.3.0, ^9.1.3 | CORS, security headers, rate limiting, SPA serving |
drizzle-orm | ^0.45.2 | ORM (migrations with drizzle-kit ^0.31.10) |
postgres | ^3.4.9 | PostgreSQL driver |
ioredis | ^6.0.0 | Optional shared rate-limit and admin-event state (REDIS_URL) |
stripe | ^22.2.0 | Billing and wallet top-ups |
nodemailer | ^8.0.10 | SMTP |
eta | ^3.5.0 | Server-rendered pages and e-mail templates |
pino | ^10.3.1 | Logging |
zod | ^4.4.3 | Environment and request validation |
dotenv | ^17.4.2 | .env loading |
The admin SPA uses Vue ^3.5.35, Vue Router ^5.1.0, Pinia ^3.0.4, vue-i18n ^11.4.4, Vite ^8.0.16 and Tailwind CSS ^4.3.0.
Development tooling: TypeScript ^6.0.3, tsx ^4.22.4, Vitest ^4.1.8, ESLint ^10.11.0, Prettier ^3.9.9, Playwright ^1.60.0 and testcontainers ^12.0.1.