Skip to content

Dev Mode

Dev mode is designed for developing and testing claritools itself. It runs the full local stack plus Keycloak and oauth2-proxy, providing OIDC authentication in front of all services. This allows you to develop and validate authentication features locally before deploying them to the production CD environment.

When to use dev mode

  • You are working on claritools itself
  • You need to test or develop OIDC authentication features
  • You want to validate auth configuration before deploying to the CD production server

Services

Dev mode includes everything from local mode plus:

Service URL Description
Keycloak https://keycloak.local.ciservers.net OIDC identity provider
oauth2-proxy (internal) Authentication middleware

All local mode services (Homepage, Traefik, Prometheus, cAdvisor, Portainer, IT Tools) are also available at the same URLs.

Setup

task init        # Select option 2 (dev)
task generate-local-self-signed-certs
task start

After starting, visit https://dashboard.local.ciservers.net. You will be presented with a sign-in page that redirects to Keycloak for authentication.

Credentials

Account Username Password Purpose
OIDC dev user dev dev Sign in to protected services
Keycloak admin admin admin Manage realms, clients, and users

Warning

These credentials are hardcoded for local development only. They must never be used in the production CD environment.

How authentication works

Dev mode adds an OIDC authentication layer between the browser and every service using Traefik's ForwardAuth middleware, oauth2-proxy, and Keycloak.

Authentication flow

Browser
  |
  | 1. HTTPS request to dashboard.local.ciservers.net
  v
Traefik
  |
  | 2. ForwardAuth check: GET /oauth2/auth → oauth2-proxy
  v
oauth2-proxy
  |
  |--- 3a. Authenticated (202) → Traefik proxies to the service
  |
  |--- 3b. Not authenticated (401) → Errors middleware calls /oauth2/sign_in
  |         |
  |         | 4. Sign-in page rendered
  |         v
  |       Browser clicks "Sign in"
  |         |
  |         | 5. Redirect to Keycloak
  |         v
  |       Keycloak login page
  |         |
  |         | 6. User authenticates with dev/dev
  |         v
  |       Keycloak redirects to /oauth2/callback
  |         |
  |         | 7. oauth2-proxy validates token, sets session cookie
  |         v
  |       Redirect back to original service
  v
Homepage (or other service)

Key components

Keycloak runs in development mode and provides the OIDC identity provider. It is pre-configured with:

  • A claritools realm
  • A claritools OIDC client (confidential, with a dev secret)
  • A dev user with a non-temporary password

The realm configuration is imported automatically on first start from config/dev/keycloak/claritools-realm.json.

oauth2-proxy acts as the authentication middleware. It is configured as a generic OIDC provider with manually specified endpoints to handle the split between internal (Docker network) and external (browser) URLs:

  • Login URL — points to the external Keycloak URL (https://keycloak.local.ciservers.net/...) because the browser needs to reach it
  • Token and JWKS URLs — point to the internal Docker URL (http://keycloak:8080/...) because these are server-to-server calls

Traefik ForwardAuth is applied to every service via label overrides in docker-compose.dev.yml. Two middlewares work together:

  • oauth-auth — ForwardAuth middleware that checks /oauth2/auth on oauth2-proxy
  • oauth-errors — Errors middleware that catches 401 responses and serves the sign-in page

SSO across services

oauth2-proxy sets a session cookie scoped to .local.ciservers.net. After authenticating once, the cookie is sent with requests to any *.local.ciservers.net service, providing single sign-on across the entire stack.

Exempt services

Keycloak is not protected by ForwardAuth to avoid redirect loops. The /oauth2/ path prefix on all hosts is routed directly to oauth2-proxy via a high-priority catch-all Traefik router.

Docker Compose files

Dev mode uses three compose files layered together:

  • docker-compose.yml — Core services (Traefik, Homepage, Prometheus, cAdvisor)
  • docker-compose.local.yml — Local-only services (Portainer, IT Tools)
  • docker-compose.dev.yml — OIDC services (Keycloak, oauth2-proxy) and ForwardAuth middleware labels

Keycloak administration

The Keycloak admin console is available at https://keycloak.local.ciservers.net. Log in with admin/admin to:

  • Manage the claritools realm
  • Add or modify users
  • Configure OIDC client settings
  • View login events and sessions

Resetting Keycloak

If you need to reset Keycloak to its initial state (e.g., after modifying the realm JSON), delete the data volume and restart:

task stop
docker volume rm current_keycloak_data
task start

Keycloak will reimport the realm from config/dev/keycloak/claritools-realm.json on next start.

Relationship to CD mode

Dev mode is the local testing ground for authentication features that will eventually be deployed to the CD production environment. The OIDC architecture (Traefik ForwardAuth + oauth2-proxy + Keycloak) is designed to be portable between environments with different identity providers and credentials.