Quick Start

Get Cerberus IAM up and running in under 5 minutes.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: 18.x or 20.x (LTS versions)
• PostgreSQL: 14.x or higher
• Docker & Docker Compose (optional, recommended for development)
• Git: For cloning the repository

Installation

1. Clone the Repository

git clone https://github.com/cerberus-iam/api.git
cd api

2. Install Dependencies

npm install

3. Set Up Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Edit .env and set the required variables:

# Database
DATABASE_URL="postgresql://cerberus:secret@localhost:5432/cerberus_iam"

# Application
NODE_ENV="development"
PORT=4000
ISSUER_URL="http://localhost:4000"

# Cryptography
JWT_ALG="EdDSA"
SECRET_ENCRYPTION_KEY="your-base64-encoded-32-byte-key"

# CORS
ADMIN_WEB_ORIGIN="http://localhost:3000"

# Email (using Mailhog for development)
EMAIL_FROM="[email protected]"
SMTP_HOST="localhost"
SMTP_PORT=1025

Generate a secure encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

4. Start the Database

Using Docker Compose (recommended):

docker-compose up -d postgres mailhog

Or manually start PostgreSQL on localhost:5432.

5. Run Database Migrations

npm run db:migrate

6. (Optional) Seed the Database

Populate the database with sample data:

npm run db:seed

This creates:

• A sample organization: "Acme Corp" (slug: acme-corp)
• An admin user: [email protected] / password123
• Default roles and permissions

7. Start the Development Server

npm run dev

The server will start on http://localhost:4000.

Verify Installation

Check Health Endpoint

curl http://localhost:4000/health

Expected response:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Test Registration

Register a new user:

curl -X POST http://localhost:4000/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-Org-Domain: acme-corp" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "firstName": "John",
    "lastName": "Doe"
  }'

Expected response:

{
  "id": "uuid-here",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Check Email (Mailhog)

If using Docker Compose, open http://localhost:8025 to view the verification email sent by Mailhog.

Test Login

curl -X POST http://localhost:4000/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Org-Domain: acme-corp" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }' \
  -c cookies.txt

The session cookie will be saved to cookies.txt.

Access Protected Endpoint

curl http://localhost:4000/v1/me/profile \
  -H "X-Org-Domain: acme-corp" \
  -b cookies.txt

Expected response includes user profile and permissions.

Next Steps

Now that you have Cerberus IAM running, explore these topics:

Learn Core Concepts

• Authentication - Understand authentication flows
• Authorization & RBAC - Learn about permissions and roles
• Multi-Tenancy - Understand organization isolation
• OAuth2 & OIDC - Integrate OAuth2 clients

Integration

• OAuth2 Client Setup - Connect your application
• API Keys - Server-to-server authentication
• Webhooks - Event-driven integrations

Deployment

• Docker Deployment - Deploy with Docker
• Production Checklist - Production-ready configuration

API Reference

• Authentication API - User registration and login
• OAuth2 API - OAuth2 flows
• Admin API - User and role management

Common Issues

Port Already in Use

If port 4000 is already in use, change the PORT environment variable:

PORT=5000

Database Connection Error

Ensure PostgreSQL is running and the DATABASE_URL is correct:

docker-compose ps postgres

Restart the database if needed:

docker-compose restart postgres

Migration Errors

If migrations fail, reset the database:

npm run db:reset

WARNING

This will delete all data in the database.

Missing Encryption Key

If you see "SECRET_ENCRYPTION_KEY is required", generate a key:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Add it to .env:

SECRET_ENCRYPTION_KEY="generated-key-here"

Development Workflow

Running Tests

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests
npm run test:integration

# E2E tests
npm run test:e2e

# With coverage
npm run test:coverage

Linting and Formatting

# Lint
npm run lint

# Fix lint issues
npm run lint:fix

# Format
npm run format

# Format and fix
npm run format:fix

Database Management

# Create a new migration
npm run db:migrate:create

# Apply migrations
npm run db:migrate

# Reset database (caution!)
npm run db:reset

# Seed database
npm run db:seed

# Open Prisma Studio
npm run db:studio

Using Docker Compose

The full development environment includes:

• PostgreSQL (port 5432)
• Mailhog SMTP/Web UI (ports 1025, 8025)
• Cerberus IAM API (port 4000)

Start all services:

docker-compose up

Stop all services:

docker-compose down

View logs:

docker-compose logs -f api

Getting Help

If you encounter issues:

1. Check the troubleshooting guide
2. Search GitHub Issues
3. Ask in GitHub Discussions
4. Read the full documentation

What's Next?

• Installation Guide - Detailed setup instructions
• Configuration - Configure Cerberus IAM
• Environment Variables - Complete reference
• API Reference - Explore API endpoints