Install Lockatus

Lockatus ships as a single Docker image plus a Postgres database. It generates its RS256 signing key on first boot (stored encrypted in the database) and seeds the first superadmin — so a single docker compose up gives you a working identity hub.

Requirements

Docker

The supported path. The bundled docker compose brings up the hub and Postgres together.

A master key

LOCKATUS_SECRET encrypts the TOTP secrets and signs the hub session. Generate 32 random bytes.

A reachable issuer URL

LOCKATUS_ISSUER is the public URL the tokens carry — it must be reachable from both the browser and the federated apps.

Run with Docker

git clone https://github.com/diegoparras/lockatus.git && cd lockatus
cp .env.example .env        # set POSTGRES_PASSWORD and LOCKATUS_SECRET
docker compose up -d --build
docker compose logs lockatus   # the generated admin password is printed once here
# → http://localhost:8081

Generate the master key with:

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

The issuer URL

For a single host, http://localhost:8081 is fine. When apps run in separate containers, use a URL that resolves the same from the browser and the containers (for example http://host.docker.internal:8081 on Docker Desktop), so the front-channel redirect and the offline JWKS verification agree.

First run

1. Open http://localhost:8081 and sign in as LOCKATUS_ADMIN_EMAIL with the password printed once in the logs (or the one you set in LOCKATUS_ADMIN_PASS).
2. In Access, the matrix shows who has which role in each app. Create users and assign roles.
3. Optionally enroll two-factor for your account, and add any new family app from the matrix with the + App button.

OIDC discovery endpoints

Route	Purpose
GET /health	Service health (and database status).
GET /.well-known/openid-configuration	Issuer metadata for OIDC discovery.
GET /jwks.json	The public key, so apps verify the tokens offline.

Environment variables

Variable	Default	Description
POSTGRES_PASSWORD	(required)	Database password.
LOCKATUS_SECRET	(required)	Master key — encrypts TOTP secrets and signs the hub session.
LOCKATUS_ISSUER	http://localhost:8081	Public issuer URL embedded in the tokens.
LOCKATUS_ADMIN_EMAIL	admin@lockatus.local	The first superadmin.
LOCKATUS_ADMIN_PASS	(empty)	Empty → generated and printed once in the logs.
LOCKATUS_SECURE_COOKIE	0	Set to 1 behind TLS.
LOCKATUS_PORT	8081	Host port.