Quickstart Guide

Get the realmsso-server backend running on your own machine in a few commands.

Prerequisites

Node.js 20+
Docker and Docker Compose

Everything else — PostgreSQL 16, Redis 7, and a Keycloak 26 instance — is provided by the bundled docker-compose.yml, so there is nothing else to install to try RealmSSO locally.

1. Get the source, then install

Access is granted per account

RealmSSO is not publicly distributed yet. The repositories are private, so there is no public clone URL — request access at enterprise@realmsso.com and you will be granted a repository you can clone. Every step from here on assumes you have it checked out locally.

cd realmsso-server
npm install

2. Configure environment

Copy the example environment file. It already contains dev-safe defaults for every required secret, so it works as-is for local development.

cp .env.example .env

Dev-only secrets

Values like JWT_SECRET, MAGIC_LINK_SECRET, and ENCRYPTION_KEY in .env.example are placeholders (e.g. change-me-in-production). Never carry them into a real deployment — see Configuration for how to generate real ones.

3. Start infrastructure

docker compose up -d postgres redis keycloak

This starts Postgres, Redis, and Keycloak in dev mode (start-dev --import-realm). A first-boot init script also creates a separate keycloak database inside the same Postgres instance, since the Postgres image only auto-creates the one named by POSTGRES_DB.

4. Run migrations and seed data

npx prisma migrate dev
npm run db:seed

The seed script is idempotent (it upserts) and creates a vendor user (dev@example.com), a sample Dev Account (slug dev-org) with that user as an admin, and one SAML connection on it — enough to exercise the dashboard without configuring a real identity provider first.

5. Start the server

npm run dev

This runs tsx watch src/main.ts. The API comes up at http://localhost:4000, with interactive Swagger docs at http://localhost:4000/docs and a readiness probe at http://localhost:4000/readyz that checks Postgres and Redis.

One-command alternative

docker compose up --build builds the server from docker/Dockerfile and starts Postgres, Redis, Keycloak, and the server together — useful for a quick end-to-end check without a local Node install.

Next steps

This gets the backend running for evaluation. For a real deployment, see the Self-Hosting Guide for the Keycloak privileges it needs, Configuration for every environment variable, and Deployment Options for Docker and Kubernetes topologies. To understand the tenant model before creating real accounts, read Accounts (Tenants).

Self-Hosting Guide →