By Fabrixly in Documentation — 07 Jul 2026

How to Configure Fabrixly-IDS for First-Time Use

Overview

This guide will walk you through setting up Fabrixly-IDS from scratch!

Prerequisites

Node.js (v18 or later)
PostgreSQL database (or use Docker for PostgreSQL)
npm or yarn

Step 1: Clone the Fabrixly-IDS Repository

git clone <your-fabrixly-ids-repo-url>
cd fabrixly-identity-server

Step 2: Install Dependencies

npm install
# OR
yarn install

Step 3: Configure Environment Variables

Copy .env.example to .env and fill in the values!

cp .env.example .env

Edit `.env` File

Here are the key environment variables you need to set:

# Server
NODE_ENV=development
PORT=3000
HOST=localhost

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your-db-password
DB_DATABASE=fabrixly_ids

# JWT & OIDC
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
OIDC_ISSUER=https://ids.fabrixly.com/oidc

# Email (for sending OTPs, magic links)
EMAIL_PROVIDER=smtp  # or sendgrid, etc.
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
FROM_EMAIL=noreply@your-domain.com

# SMS (optional, for mobile OTPs)
SMS_PROVIDER=twilio
TWILIO_ACCOUNT_SID=your-twilio-sid
TWILIO_AUTH_TOKEN=your-twilio-token
TWILIO_PHONE_NUMBER=+1234567890

# OTP Settings
OTP_EXPIRY_MINUTES=5
OTP_LENGTH=6

# Session
SESSION_SECRET=your-session-secret-change-this-in-production

# Admin User (created automatically on first run)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin-password-change-this!

# Licensing (optional)
LICENSE_PUBLIC_KEY=
LICENSE_PRIVATE_KEY=

Step 4: Set Up the Database

Option A: Use Docker Compose to run PostgreSQL:

docker-compose up -d postgres

Option B: Use existing PostgreSQL database—make sure DB is created!

Step 5: Run Database Migrations

npm run migration:run
# OR
yarn migration:run

Step 6: Start Fabrixly-IDS

# Development mode (with hot reload)
npm run dev
# OR
yarn dev

# Production mode
npm run build
npm run start

Step 7: Access Fabrixly-IDS

OIDC Issuer: https://ids.fabrixly.com/oidc
Admin Console: https://ids.fabrixly.com/admin
API Docs: https://ids.fabrixly.com/api-docs (if Swagger is enabled)

Open https://ids.fabrixly.com/admin and log in with:

Email: ADMIN_EMAIL from .env
Password: ADMIN_PASSWORD from .env

Step 9: Create Your First Organization (Optional, for Multi-Tenant)

If using multi-tenant mode:

In Admin Console → go to Organizations
Click Create Organization
Fill in org name, subdomain, etc.
Save!

Step 10: Create Your First OIDC Client

In Admin Console → go to Clients
Click Create Client
Fill in details:
- Client name: "My First App"
- Redirect URIs: http://localhost:3001/callback (your app's callback URL)
- Response types: code
- Grant types: authorization_code, refresh_token
- Token endpoint auth method: client_secret_basic
- Auth mode: flexible
Save! Note your client ID and secret!

Step 11: Test Your Setup

Use the authorization code flow how-to guide to create a test app and test logging in!

Development Tips

Hot reload: npm run dev
Run tests: npm run test
Build for production: npm run build
Docker: docker-compose up

Production Checklist

Change all secrets: JWT_SECRET, SESSION_SECRET, ADMIN_PASSWORD, DB_PASSWORD!
Use HTTPS: Always use HTTPS in production!
Secure Database: Use a strong DB password, restrict network access!
Backups: Set up regular database backups!
Environment: Set NODE_ENV=production!
Email/SMS: Configure production email/SMS providers!

Troubleshooting First-Time Setup

"Database connection failed": Check DB credentials in .env!
"Migrations failed": Make sure database is created and accessible!
"Admin user not created": Check ADMIN_EMAIL and ADMIN_PASSWORD in .env!
"Can't access admin console": Make sure server is running on correct port!

Next Steps

Explore the how-to guides for specific authentication modes!
Set up Fabrixly Licensing Portal for license management!
Customize branding in Admin Console!