Quickstart

You need Docker and Docker Compose. Nothing else. No JDK, no database client, no external dependencies.

Pre-built image (fastest)
Build from source

No repo clone required. Pull the image directly from GitHub Container Registry.

Grab the compose file and env template

mkdir kotauth && cd kotauth
curl -O https://raw.githubusercontent.com/inumansoul/kotauth/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/inumansoul/kotauth/main/.env.example
cp .env.example .env

Set your secret key

Open .env and generate a secret key:
Terminal window
```
KAUTH_SECRET_KEY=        # paste output of: openssl rand -hex 32
```
KAUTH_BASE_URL defaults to http://localhost:8080. Change it if deploying remotely.

Caution: Do not skip KAUTH_SECRET_KEY. Without it, SMTP configuration cannot be saved and sessions will be lost on every container restart.
Start the stack
Terminal window
```
docker compose up -d
```
Kotauth pulls from GHCR and starts on port 8080. PostgreSQL is bundled — no external database needed. Flyway runs all migrations automatically on first boot.

To also start Redis for distributed sessions and rate limiting:
Terminal window
```
docker compose --profile redis up -d
```
Open the admin console
```
http://localhost:8080/admin
```
On first run, master workspace admin credentials are printed to the startup log. Find them with:
Terminal window
```
docker compose logs kotauth | grep "Admin credentials"
```
Caution: Change the master workspace admin password immediately after first login.
Create a workspace

In the admin console, click New Workspace and enter a slug (e.g. my-app). A workspace is a fully isolated tenant — it gets its own user directory, applications, signing keys, and settings.
Verify OIDC discovery

Your workspace’s OIDC discovery document is immediately available:
```
http://localhost:8080/t/my-app/.well-known/openid-configuration
```
This is the URL you’ll give to any OAuth2 / OIDC library as the issuer or discovery URL.

For contributors or anyone iterating on the source code.

Clone the repository

git clone https://github.com/inumansoul/kotauth.git
cd kotauth

Create your .env file

cp .env.example .env

Open .env and set KAUTH_SECRET_KEY:

KAUTH_SECRET_KEY=        # paste output of: openssl rand -hex 32

Build and start

make up

This builds the image from the local Dockerfile via docker-compose.yml and starts the full stack. Flyway runs all migrations on first boot.

Run make help to see all available developer targets. The most useful ones:

make up        # build from source and start all services
make down      # stop containers
make nuke      # stop and wipe volumes (destroys the database)
make logs      # follow app container logs
make test      # run unit/integration tests
make e2e       # run E2E browser tests (Playwright, headless)
make lint      # run ktlint check
make build     # full CI-equivalent build (CSS + lint + tests + JAR)
make health    # probe the local health endpoint

Open the admin console
```
http://localhost:8080/admin
```
Find your initial admin credentials:
Terminal window
```
docker compose logs kotauth | grep "Admin credentials"
```
Caution: Change the master workspace admin password immediately after first login.
Create a workspace and verify OIDC

Same as the pre-built path — create a workspace in the admin console, then visit:
```
http://localhost:8080/t/my-app/.well-known/openid-configuration
```

What’s running

After startup you have:

URL	Description
`http://localhost:8080/admin`	Admin console
`http://localhost:8080/t/{slug}/authorize`	Authorization endpoint for workspace `slug`
`http://localhost:8080/t/{slug}/.well-known/openid-configuration`	OIDC discovery document
`http://localhost:8080/t/{slug}/api/v1/docs`	Swagger UI (REST API)
`http://localhost:8080/health`	Liveness probe
`http://localhost:8080/health/ready`	Readiness probe

Create your first application

Once inside your workspace in the admin console:

Go to Applications → New Application
Set the type: Public (for SPAs / mobile) or Confidential (for server-side apps)
Add your redirect URI (e.g. http://localhost:3000/callback)
Copy the client_id — this is what you pass to your OAuth2 library

Your app is now registered. Point your OAuth2 library at the discovery document URL and use the client_id. Done.

What’s next

Core Concepts — understand how workspaces, applications, and tokens relate
Authorization Code + PKCE — the standard flow for SPAs and mobile apps
REST API Overview — manage users, roles, and sessions programmatically