Skip to content
Kotauth

Quickstart

import { Steps, Aside } from ‘@astrojs/starlight/components’;

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

  1. Clone the repository

    Terminal window
    git clone https://github.com/your-org/kotauth.git
    cd kotauth

  2. Create your .env file

    Terminal window
    cp .env.example .env

    The defaults work for local development. Optionally set a persistent secret key so sessions survive container restarts:

    Terminal window
    echo "KAUTH_SECRET_KEY=$(openssl rand -hex 32)" >> .env
    echo "KAUTH_BASE_URL=http://localhost:8080" >> .env

  3. Start the stack

    Terminal window
    docker compose up

    Kotauth starts on port 8080. Flyway runs all database migrations automatically on first boot — no manual schema setup needed.

  4. Open the admin console

    http://localhost:8080/admin

    On first run, the master workspace admin credentials are printed to the startup log. Find them with:

    Terminal window
    docker compose logs kotauth | grep "Admin credentials"

  5. 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.

  6. 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.

What’s running

Section titled “What’s running”

After docker compose up you have:

URLDescription
http://localhost:8080/adminAdmin console
http://localhost:8080/t/{slug}/loginLogin page for workspace slug
http://localhost:8080/t/{slug}/.well-known/openid-configurationOIDC discovery document
http://localhost:8080/t/{slug}/api/v1/docsSwagger UI (REST API)
http://localhost:8080/healthLiveness probe
http://localhost:8080/health/readyReadiness probe

Create your first application

Section titled “Create your first application”

Once inside your workspace in the admin console:

  1. Go to Applications → New Application
  2. Set the type: Public (for SPAs / mobile) or Confidential (for server-side apps)
  3. Add your redirect URI (e.g. http://localhost:3000/callback)
  4. 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

Section titled “What’s next”