Architecture

How all the pieces fit together.

Hub-and-Spoke SSO

All traffic enters through Caddy (reverse proxy) on a single port. Caddy routes by subdomain to the correct backend. Authentication flows through Authentik as the central identity hub.

Browser → http://{app}.{DOMAIN}:{PORT}
           │
           └── Caddy (reverse proxy, static IP 172.28.0.250)
                 ├── auth.*      → Authentik    (OIDC/SAML provider)
                 ├── docs.*      → Outline      (OIDC)
                 ├── chat.*      → Mattermost   (OAuth2)
                 ├── git.*       → Gitea        (OIDC)
                 ├── files.*     → Seafile      (OAuth2)
                 ├── time.*      → Kimai        (SAML)
                 ├── tasks.*     → Vikunja      (OIDC)
                 ├── vault.*     → Vaultwarden  (OIDC)
                 ├── office.*    → OnlyOffice   (JWT)
                 ├── dms.*       → Paperless    (OIDC)
                 ├── draw.*      → Excalidraw   (forward-auth)
                 └── minio.*     → MinIO        (internal)

Authentication Protocols

Blueprints (Zero-Touch Config)

Authentik blueprints are YAML files that declaratively create all SSO providers, webhook transports, and scope mappings. They're mounted into the Authentik worker and auto-applied on startup — no UI clicks needed.

There are 18 blueprints in apps/authentik/blueprints/: one per OIDC/SAML provider, one per webhook transport, plus shared scope and comms launcher configs.

Adapters

Adapters are lightweight FastAPI microservices that receive Authentik webhooks and translate them into app-specific API calls. There are 4 adapters:

Init Containers

Init containers run once at first boot to configure apps that can't be fully configured via environment variables alone. All are idempotent — safe to re-run.

The Split URL Pattern

A critical implementation detail: browser-facing and server-to-server OIDC URLs must differ inside Docker.

• Browser: http://auth.localhost (external, via Caddy)
• Server: http://authentik-server:9000 (Docker internal hostname)

Apps that support separate browser/server URLs use this split directly. Apps with a single authority URL (Gitea, Vikunja, Vaultwarden) use extra_hosts to point the auth domain to Caddy's static IP.

Adapters & Webhooks

How Authentik events propagate to every app in real time.

What Are Adapters?

Adapters are lightweight Python (FastAPI) microservices that act as translators between Authentik and each app. When something happens in Authentik (a group is created, a user logs in), Authentik fires an HTTP webhook to the relevant adapters, which then call the target app's API.

Authentik event
    │
    ├──webhook──→ outline-adapter ──API──→ Outline
    ├──webhook──→ mattermost-adapter ──API──→ Mattermost
    ├──webhook──→ gitea-adapter ──API──→ Gitea
    └──webhook──→ seafile-adapter ──API──→ Seafile

Webhook Events

Pending Queue

Each adapter maintains a SQLite database for pending memberships. If a user is added to a group but hasn't logged into the target app (no local account exists), the membership is queued. On next login, all pending memberships are applied.

Adapter Endpoints

POST /webhook    — Receives Authentik events
GET  /health     — Liveness probe (returns 200)
GET  /pending    — Lists queued pending operations

Shared Base

All adapters share apps/_shared/adapter_base.py which provides:

• SQLite database initialization and pending queue management
• Webhook payload parsing
• load_role_mapping() — parses ROLE_MAPPING env var
• get_group_role() — resolves a group name to its app-specific role (or None for exclusion)

Adding Users & Groups

Step-by-step: create your company's user structure in Authentik.

1 Plan Your Groups

Think about your company's job functions. Each group maps to a set of permissions across all apps. Common examples:

2 Create Groups in Authentik

1. Open Authentik admin: auth.localhost/if/admin → Directory → Groups
2. Click Create
3. Enter the group name (e.g., engineering)
4. Click Create

Within seconds, all 4 adapters receive a webhook and create the corresponding resources:

• Gitea: organization engineering
• Mattermost: channel engineering
• Outline: group engineering
• Seafile: group engineering

3 Create Users

1. Go to Directory → Users in Authentik admin
2. Click Create
3. Fill in: username, display name, email
4. Set a temporary password (user can change on first login)
5. Click Create

4 Add Users to Groups

1. Open the user you just created
2. Go to the Groups tab
3. Click Add to existing group
4. Select the group(s) this user belongs to

5 Tell Users to Log In

Share the app URLs with your users. On first login to any app via SSO:

1. A local account is auto-created in the app
2. All pending group memberships are applied (Mattermost also joins them to the default team)
3. If Mattermost onboarding is enabled, they get a welcome DM with communication links

Industry Presets

Pre-built RBAC configurations for common company types. Zero to productive in seconds.

What Are Presets?

Klyvra ships with 5 industry presets that define groups, roles, and per-app permissions tailored to specific company types. Instead of configuring RBAC from scratch, pick a preset and apply it.

Available Presets

Applying a Preset (Docker Compose)

# Generate ROLE_MAPPING env vars for your .env file
python3 scripts/apply_preset.py presets/software-house.yaml --env-format >> .env

# Restart adapters to pick up new role mappings
make restart

Applying a Preset (Helm)

# Generate Helm values override
python3 scripts/apply_preset.py presets/software-house.yaml --helm-format > my-rbac.yaml

# Install or upgrade with the preset
helm install klyvra ./chart/klyvra -f my-rbac.yaml --set global.domain=company.com

Custom Domain & TLS

Move from localhost to a real domain with automatic HTTPS.

Setting a Custom Domain

make destroy                                        # Clean slate (if upgrading from localhost)
make bootstrap DOMAIN=company.com TLS_EMAIL=admin@company.com
make up

All services become https://auth.company.com, https://docs.company.com, https://chat.company.com, etc.

DNS Setup

Point a wildcard DNS record to your server:

*.company.com    A    → your-server-ip

Or create individual A records for each subdomain: auth, docs, chat, git, files, time, tasks, vault, office, dms, draw, mail, calendar, contacts.

TLS (HTTPS)

TLS is fully automated when using a custom domain:

1. Run make bootstrap DOMAIN=company.com TLS_EMAIL=admin@company.com
2. Point DNS wildcard *.company.com to your server
3. Run make up — Caddy auto-provisions Let's Encrypt certificates for all subdomains

Caddy handles certificate issuance, renewal, and HTTPS redirects automatically. No manual configuration needed.

Switching Between Dev and Production

The bootstrap command manages this automatically:

Deploying with Helm

Deploy Klyvra on Kubernetes with the Helm chart.

Prerequisites

• Kubernetes cluster (1.25+)
• Helm 3
• An ingress controller (nginx-ingress, Traefik, etc.)
• cert-manager (for automatic TLS) — optional but recommended

Build & Push Images

Klyvra builds custom images for the adapters, init jobs, and Seafile (embedded OAuth boot). Build and push them to your registry:

# Build locally
make images

# Push to your registry
REGISTRY=ghcr.io/your-org TAG=v0.1.0 make push-images

Install

helm install klyvra ./chart/klyvra \
  --set global.domain=company.com \
  --set global.imageRegistry=ghcr.io/your-org \
  --set global.imageTag=v0.1.0

Configure RBAC in values.yaml

The chart's values.yaml has a dedicated RBAC section. Define your groups and their per-app roles:

rbac:
  groups:
    engineering:
      displayName: "Engineering"
      roles:
        gitea: owner
        outline: member
        mattermost: member
        seafile: member
        kimai: user

    management:
      displayName: "Management"
      roles:
        gitea: read
        outline: member
        mattermost: admin
        seafile: member
        kimai: teamlead

    hr:
      displayName: "Human Resources"
      roles:
        gitea: null            # Excluded from code repos
        outline: member
        seafile: member
        kimai: teamlead

The chart converts this into per-adapter ConfigMaps automatically — no manual JSON wrangling.

Enable/Disable Apps

# values.yaml
outline:
  enabled: true

kimai:
  enabled: false     # Don't need time tracking? Disable it.

Ingress

The chart creates Ingress resources for every enabled app's subdomain. Configure your ingress class:

global:
  ingress:
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod

App Reference

All 11 apps at a glance — what they do, how they authenticate, and what they replace.

Notes

• OnlyOffice has no user accounts — it's a document server accessed via Seafile's integration for editing Word/Excel/PowerPoint files. Authenticated via shared JWT secret with Seafile.
• MinIO is the S3 backend for Outline's file storage. Not a user-facing app. Uses static admin credentials.
• Vaultwarden uses the OIDCWarden fork — the official image doesn't support SSO.
• Mattermost uses Enterprise Edition (free tier, no license needed) because Team Edition removed OAuth in v9.x.
• Kimai maps SAML group claims to roles: kimai-admin → SUPER_ADMIN, kimai-teamlead → TEAMLEAD.
• Kimai matches group names literally — the Authentik group must be named exactly kimai-admin or kimai-teamlead (not engineering or management). This is a Kimai limitation.

Environment Variables

All config lives in .env, generated by make bootstrap.

User-Configurable

Auto-Generated (don't touch)

make bootstrap generates 30+ secrets using openssl rand. These include:

• Database passwords for all 8 databases
• OIDC client secrets for all 7 OIDC providers
• Authentik secret key, bootstrap token
• MinIO root password
• OnlyOffice JWT secret
• Paperless admin password & secret key

Troubleshooting

Common issues and how to fix them.

Port 80 in use

make bootstrap HTTP_PORT=8080
make up

Stale volumes after re-bootstrapping

If you re-run make bootstrap (which regenerates passwords), existing database volumes still have the old passwords:

make destroy        # removes containers AND volumes
make bootstrap      # fresh .env
make up             # clean start

*.localhost doesn't resolve

Most modern systems resolve *.localhost to 127.0.0.1 (RFC 6761). If your browser can't reach the URLs, add entries to /etc/hosts:

# /etc/hosts
127.0.0.1 auth.localhost docs.localhost chat.localhost git.localhost
127.0.0.1 files.localhost time.localhost tasks.localhost vault.localhost
127.0.0.1 dms.localhost draw.localhost office.localhost minio.localhost

Service won't start

docker compose logs <service-name>    # Check logs
docker compose ps -a                    # Check exit codes
make logs SVC=<service-name>           # Follow logs

SSO button missing in Seafile

Seafile's OAuth config is patched at runtime by an embedded boot script. If the SSO button is missing:

docker logs klyvra-seafile-1 2>&1 | grep oauth-boot

Vaultwarden SSO not working

Klyvra uses OIDCWarden (timshel/oidcwarden:latest), not the official Vaultwarden image. The official image silently ignores SSO_* env vars. OIDCWarden still requires a master password after SSO login (by design — it encrypts your vault).

Mattermost shows "GitLab" as SSO provider

This is a legacy label. If your Mattermost still shows "GitLab" instead of "Login with Klyvra", check that you're using the latest Klyvra compose config. Mattermost's free tier only supports "GitLab" as an OAuth2 provider type — Klyvra patches the button text to say "Login with Klyvra" but the internal provider type remains "gitlab".

Init container keeps restarting

Init containers use restart: on-failure and retry until their target app is ready. Check if the target app is healthy:

docker compose ps        # Look for unhealthy services
make status              # Full status dashboard

Checking adapter health

# View adapter logs
make logs SVC=outline-adapter
make logs SVC=gitea-adapter

# Check pending queue
docker compose exec outline-adapter curl -s localhost:8000/pending

Production Deployment

Deploy Klyvra in production using Docker Compose or Kubernetes.

Hardware Requirements

Software Requirements

• Docker Compose: Docker Engine 24.0+ with Compose v2
• Kubernetes: Version 1.25+ (if using Helm)
• DNS: A wildcard A record (*.company.com) pointing to your server
• make and openssl installed on the deployment machine

Docker Compose Deployment

1 Bootstrap with production settings

make bootstrap DOMAIN=company.com TLS_EMAIL=admin@company.com

This generates 35+ random secrets, sets the base domain for all subdomains, configures Caddy for automatic HTTPS via Let's Encrypt, and symlinks the production Caddyfile.

2 Start services

make up

3 Configure firewall

Email (Bring Your Own Provider)

Klyvra does not self-host email — port 25 blocking, IP reputation, and SPF/DKIM/PTR coordination make it the one service that can't ship turnkey. Instead:

1. Choose a hosted provider (EU providers work well for data-sovereignty requirements)
2. Set MAIL_URL, CALENDAR_URL, and CONTACTS_URL in .env to its web endpoints
3. mail.company.com, calendar.company.com, and contacts.company.com redirect there, and Mattermost's /mail, /calendar, /contacts commands link users directly

Backup & Restore

# Back up all databases, volumes, and .env
make backup

# Restore from a specific backup
make restore BACKUP=backups/klyvra-YYYYMMDD-HHMMSS

Run backups daily and copy the archive to offsite storage.

Upgrading

# Docker Compose: pull latest images, rebuild, restart
make upgrade

# Kubernetes
helm upgrade klyvra ./chart/klyvra

Security Hardening

Klyvra's Caddy reverse proxy injects security headers on all responses automatically:

• Strict-Transport-Security (HSTS) — forces HTTPS for 1 year (production mode)
• X-Content-Type-Options — prevents MIME-type sniffing
• X-Frame-Options — restricts iframe embedding to same-origin
• Referrer-Policy — limits referrer information to external sites
• Permissions-Policy — disables camera, microphone, geolocation

Additional measures

• Restrict Authentik admin access to specific IPs via Caddy/Ingress rules
• Keep management ports (MinIO console 9001) internal or behind VPN
• On Kubernetes, enable global.networkPolicies.enabled for pod-to-pod isolation

Monitoring

make status         # Container status dashboard
make healthcheck    # HTTP check on all 14 routes
make smoke-test     # Automated E2E verification
make logs SVC=x     # Follow logs for a specific service

Communications Front Door

Unified mail, calendar, and contacts access via Mattermost and dedicated subdomains.

What It Is

Klyvra provides a "communications front door" — dedicated subdomains and Mattermost slash commands that give users quick access to email, calendar, and contacts without needing to remember separate URLs.

Subdomain Routes

Until configured, these routes serve a small page explaining how to set them up. Set MAIL_URL, CALENDAR_URL, and CONTACTS_URL to your hosted provider and the routes redirect there directly.

Mattermost Slash Commands

When ENABLE_COMMS_COMMANDS=true (default), Mattermost init creates these slash commands:

Onboarding DM

When ENABLE_COMMS_ONBOARDING=true (default), new users receive a one-time direct message in Mattermost after their first Authentik login. The DM contains links to mail, calendar, and contacts.

Configuration

Makefile Commands

Every command available for managing your Klyvra deployment.