-
Create onboarding documentation for the project (or part you are working on) for a new employees. Use texts, diagrams
-
Evaluate parts of your project in tokens
-
Fork this repository and make pull request with solution
Welcome! 👋 This repository contains the Keycloak codebase. This document is an Inventorsoft-friendly onboarding path aimed at getting a newcomer to a working local environment fast, with enough context to be productive safely.
- Run Keycloak locally in development mode (
start-dev) and log in to the Admin Console 🔐 - Build successfully once (so your IDE can compile without missing generated sources) 🧱
- Know where to make changes (server vs UI vs docs) 🧭
- Know the “escape hatches” (common fixes, how to clean, how to ask for help) 🛟
If you only follow one section, follow this one.
- Prereqs
- ☕ JDK: 17, 21, or 25 (newer is not supported by this repo)
- 🧰 Git
- 📦 (Optional, for UI work) Node.js + a package manager (see
js/README.md)
- Set an admin user (recommended, avoids prompts)
- In the same terminal where you run Keycloak:
$env:KEYCLOAK_ADMIN="admin"
$env:KEYCLOAK_ADMIN_PASSWORD="admin"- Build once (skip tests to save time)
.\mvnw.cmd clean install -DskipTests- Run Keycloak (Quarkus dev mode + start-dev)
- Run from the repo root:
.\mvnw.cmd -f quarkus\server\pom.xml compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev"- Open
- 🌐 Server:
http://localhost:8080 - 🛠️ Admin Console:
http://localhost:8080/admin
- 🌐 Server:
- Server / runtime (Java)
quarkus/: Keycloak distribution on Quarkus (how we run locally most of the time)services/: large part of server services and logicmodel/: persistence model (JPA, storage)rest/: REST APIs (incl. admin APIs)
- UIs (TypeScript/React)
js/apps/admin-ui/: Admin Console UIjs/apps/account-ui/: Account Console UIjs/libs/ui-shared/: shared UI componentsjs/libs/keycloak-admin-client/: JS admin client library
- Docs
docs/: build docs, tests docs, contributor docs
- Tests
testsuite/,test-framework/,tests/: integration & framework pieces (can be heavy; don’t start here unless you need to)
- Java
- Install JDK 17/21/25
- Verify:
java -version- If you have multiple JDKs installed, set
JAVA_HOMEto the one you want:- PowerShell
$env:JAVA_HOME="C:\Path\To\JDK-21"- Git
git --version-
Maven
- Use the repo wrapper
mvnw.cmd(recommended). It downloads the supported Maven version automatically.
- Use the repo wrapper
-
(Optional) UI prerequisites
- See
js/README.mdfor what to install and how to build UIs.
- See
- Build everything (fast-ish, skip tests)
.\mvnw.cmd clean install -DskipTests- Build the server distribution modules only (faster for backend changes)
- This is useful if you’re working on server-side code and want a smaller build:
.\mvnw.cmd -pl quarkus/deployment,quarkus/dist -am -DskipTests clean install- Tip: IDE compilation
- Some sources are generated by Maven plugins. Do at least one Maven build before relying on IDE “Build/Rebuild”.
- From repo root:
.\mvnw.cmd -f quarkus\server\pom.xml compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev"- Expected:
http://localhost:8080is up- Hot reload works best for changes inside:
quarkus/deployment,quarkus/runtime,quarkus/server
- If you set
KEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD, you can log in right away.
- Build a distribution ZIP first:
- See
docs/building.mdandquarkus/README.mdfor options.
- See
- Then run:
bin/kc.bat start-dev
- Quarkus dev mode
quarkus:devexposes a debug port (commonly5005).- If you need to suspend at startup:
.\mvnw.cmd -f quarkus\server\pom.xml -Dsuspend=true compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev"- Distribution script debug
- When running
kc.bat, you can enable remote debug (commonly8787):kc.bat --debug start-dev
- When running
Keycloak’s UIs live under js/. For details and the most accurate commands, start here:
js/README.md📘
Typical newcomer path:
- Understand structure
js/apps/admin-ui/(Admin Console)js/apps/account-ui/(Account Console)- shared packages in
js/libs/
- When something fails
- First confirm you are using the required Node version (as described in
js/README.md) - Then do a clean install and rebuild inside
js/
- First confirm you are using the required Node version (as described in
This repo has a large test surface. Start with the smallest useful scope.
-
Docs
docs/tests.md(entry point)testsuite/integration-arquillian/HOW-TO-RUN.md(deeper)
-
Browser-based tests
- Selenium-based; can be run with:
-Dbrowser=firefox-Dbrowser=chrome
- Selenium-based; can be run with:
-
Default database
- Embedded H2 by default; see
docs/tests-db.mdfor vendor testing.
- Embedded H2 by default; see
-
“Wrong Java version” / build fails early
- ✅ Ensure JDK is 17/21/25
- ✅
java -versionshows the right one - ✅ Set
JAVA_HOMEaccordingly
-
Build succeeds in CLI but IDE shows missing classes
- ✅ Run one full Maven build first (generated sources)
- ✅ Avoid “Rebuild project” if it wipes generated outputs
-
Port already in use
- ✅ Stop the other Keycloak instance
- ✅ Or run on another port via
quarkus.args/ Keycloak config
-
Everything is slow
- ✅ Build with tests skipped for local iteration (
-DskipTests) - ✅ Prefer building only the modules you’re touching (
-pl ... -am)
- ✅ Build with tests skipped for local iteration (
- Before a PR
- ✅ Keep changes scoped (one intent per PR)
- ✅ Prefer smallest test that proves the change
- ✅ Update docs if behavior changes
- Formatting
- The project uses Spotless; see
CONTRIBUTING.mdforspotless:check/spotless:apply.
- The project uses Spotless; see
- When in doubt
- Start by reading:
docs/building.mdquarkus/README.mdjs/README.mdCONTRIBUTING.md
- Start by reading:
Use this as a shared checklist before requesting review / merging.
Use this checklist to confirm a new team member is ramping up well during Week 1.
- Day 1-2: Environment & orientation 🧭
- ✅ Can build the project once with
.\mvnw.cmd clean install -DskipTests. - ✅ Can run Keycloak locally in
start-devand access Admin Console. - ✅ Understands high-level repo map (
quarkus/,services/,model/,rest/,js/).
- ✅ Can build the project once with
- Day 2-3: First technical contribution 🛠️
- ✅ Picks one small, low-risk task (docs/small bugfix/test improvement).
- ✅ Opens a draft PR early with clear problem statement and plan.
- ✅ Gets at least one local test/build signal relevant to the change.
- Day 3-4: Team workflow adoption 🤝
- ✅ Applies review feedback with reasonable turnaround.
- ✅ Follows project conventions (scoped changes, docs update when needed, Spotless clean).
- ✅ Communicates blockers early in team channel / standup.
- Day 5: Independence baseline 🚀
- ✅ Can move a small task from “in progress” to “ready for review” mostly independently.
- ✅ Can explain touched code paths and basic trade-offs in plain language.
- ✅ Maintains a short “what I learned” note for next newcomers (optional but encouraged).
- Scope & traceability 🧾
- ✅ A clear issue/ticket exists (problem statement + acceptance criteria).
- ✅ The PR does one thing (no drive-by refactors).
- Implementation quality 🧠
- ✅ No obvious performance regressions (startup, hot paths you touched).
- ✅ No new security risks (secrets, auth bypasses, unsafe defaults).
- ✅ Errors are handled intentionally (good messages, no silent failures).
- Tests 🧪
- ✅ Added/updated tests that prove the change (unit/integration as appropriate).
- ✅ Ran the smallest relevant test suite locally; if not possible, documented why.
- ✅ If behavior changed, added coverage for the new behavior and edge cases.
- Docs & UX 📚
- ✅ Docs updated if behavior/config/UI changed (at least in-repo docs; user-facing docs if needed).
- ✅ Any new flags/config options are discoverable (help text / docs link).
- Build / CI readiness 🟢
- ✅ Local build succeeds for the touched area (use
mvnwwrapper). - ✅ Formatting is clean (Spotless passes or changes applied).
- ✅ No new warnings/errors in logs on a basic run (
start-dev) for the flow you changed.
- ✅ Local build succeeds for the touched area (use
- Reviewability 🔍
- ✅ PR description explains why and includes a short test plan.
- ✅ Screenshots / logs attached for UI or behavior changes (when relevant).
- ✅ Backwards-compat/migration notes included if the change impacts existing users.
- Build from source:
docs/building.md - Run on Quarkus:
quarkus/README.md - Run tests:
docs/tests.md - JS/UIs:
js/README.md - Contributing:
CONTRIBUTING.md
Approximation method:
- We sum sizes of tracked files in each top-level folder (
git ls-files). - We estimate tokens as bytes / 4 (rough LLM rule of thumb for mixed code/docs).
Top 5 areas by estimated token weight:
docs/📚- Files:
1151 - Size:
37,354,197bytes - Estimated tokens:
9,338,549
- Files:
testsuite/🧪- Files:
1826 - Size:
17,320,929bytes - Estimated tokens:
4,330,232
- Files:
js/🖥️- Files:
1177 - Size:
9,606,587bytes - Estimated tokens:
2,401,647
- Files:
services/⚙️- Files:
1709 - Size:
9,051,153bytes - Estimated tokens:
2,262,788
- Files:
model/🗃️- Files:
966 - Size:
4,655,568bytes - Estimated tokens:
1,163,892
- Files:
Note: This is a planning estimate, not an exact tokenizer output. Real token counts vary by model/tokenizer.