Skip to content

Task-01. Add documentation to simplify on-boarding of new-comers. #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oleksandrval-is wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Task-01. Add documentation to simplify on-boarding of new-comers. #20

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
326 changes: 326 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,329 @@
- Fork this repository and make pull request with solution

-
# Readme-IS.md — Inventorsoft onboarding guide 🚀

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.


## 0) What you should achieve on Day 1 ✅

- **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) 🛟

---

## 1) TL;DR quick start (Windows / PowerShell) ⚡

> If you only follow one section, follow this one.

- **Prereqs**
- ☕ JDK: **17**, **21**, or **25** (newer is not supported by this repo)
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

What Java (JDK) versions are officially supported by the current Keycloak release? Please provide the official Keycloak documentation/source link.

💡 Result:

The current Keycloak release is 26.5.6 (as of 2026-03-19). It officially supports OpenJDK 21. OpenJDK 17 is deprecated and may still work but is planned for removal in favor of OpenJDK 21. This is confirmed in the getting started guide requiring OpenJDK 21, release notes from Keycloak 25/26 introducing and prioritizing Java 21 support, and statements from Keycloak developers that only 17 and 21 are officially supported (non-LTS like 23 not officially supported).

Citations:

Update JDK version claims against official Keycloak support matrix.

The README claims JDK 25 support, but official Keycloak documentation (v26.5.6) supports only OpenJDK 21, with OpenJDK 17 deprecated and planned for removal. Remove the JDK 25 reference and update to reflect current official support. Reference: https://www.keycloak.org/getting-started/getting-started-zip and Keycloak release notes.

Also applies to: 78-78, 206-206

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 27, Update the README references that claim JDK 25
support: locate the JDK version line(s) containing the text "☕ JDK: **17**,
**21**, or **25**" (and any other occurrences of "☕ JDK:" in the README) and
remove the "**25**" entry, adjusting the wording to reflect only supported
versions per Keycloak docs (e.g., "☕ JDK: **21** (OpenJDK 17 deprecated)") and
ensure any similar JDK references elsewhere in the file are updated consistently
to match the official Keycloak support matrix.

- 🧰 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:

```bash
$env:KEYCLOAK_ADMIN="admin"
$env:KEYCLOAK_ADMIN_PASSWORD="admin"
```
Comment on lines +30 to +36
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add a strict local-only warning for default admin credentials.

Line 30 marks admin/admin as “recommended”. Please mark this as local-dev only and discourage reuse in shared/dev servers to avoid unsafe copy/paste practices.

🔐 Suggested wording tweak 
-- **Set an admin user (recommended, avoids prompts)**
+- **Set an admin user (local dev only; do not reuse in shared environments)**
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- **Set an admin user (recommended, avoids prompts)**
- In the same terminal where you run Keycloak:
```bash
$env:KEYCLOAK_ADMIN="admin"
$env:KEYCLOAK_ADMIN_PASSWORD="admin"
```
- **Set an admin user (local dev only; do not reuse in shared environments)**
- In the same terminal where you run Keycloak:
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 30 - 36, Update the README snippet that sets
KEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD (the `KEYCLOAK_ADMIN="admin"` /
`KEYCLOAK_ADMIN_PASSWORD="admin"` example) to clearly flag these default
credentials as "local-development only" and add a warning sentence discouraging
reuse on shared, staging, or production servers; replace language like
"recommended" with "for local development only — do not use on shared or
production systems" and recommend creating a unique secure admin account for
non-local environments.

- **Build once (skip tests to save time)**

```bash
.\mvnw.cmd clean install -DskipTests
```

- **Run Keycloak (Quarkus dev mode + start-dev)**
- Run from the repo root:

```bash
.\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`

---

## 2) Repo map 🗺️ (what lives where)

- **Server / runtime (Java)**
- **`quarkus/`**: Keycloak distribution on Quarkus (how we run locally most of the time)
- **`services/`**: large part of server services and logic
- **`model/`**: persistence model (JPA, storage)
- **`rest/`**: REST APIs (incl. admin APIs)
- **UIs (TypeScript/React)**
- **`js/apps/admin-ui/`**: Admin Console UI
- **`js/apps/account-ui/`**: Account Console UI
- **`js/libs/ui-shared/`**: shared UI components
- **`js/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)

---

## 3) Prerequisites & setup (Windows-first) 🧰

- **Java**
- Install **JDK 17/21/25**
- Verify:

```bash
java -version
```

- If you have multiple JDKs installed, set `JAVA_HOME` to the one you want:
- **PowerShell**

```bash
$env:JAVA_HOME="C:\Path\To\JDK-21"
```

- **Git**

```bash
git --version
```

- **Maven**
- Use the repo wrapper **`mvnw.cmd`** (recommended). It downloads the supported Maven version automatically.

- **(Optional) UI prerequisites**
- See **`js/README.md`** for what to install and how to build UIs.

---

## 4) Build workflows 🧱

- **Build everything (fast-ish, skip tests)**

```bash
.\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:

```bash
.\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”.

---

## 5) Run Keycloak locally 🏃‍♂️

### 5.1 Run in Quarkus dev mode (recommended) 🧪

- From repo root:

```bash
.\mvnw.cmd -f quarkus\server\pom.xml compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev"
```

- Expected:
- `http://localhost:8080` is 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.

### 5.2 Run the distribution (more “realistic”) 📦

- Build a distribution ZIP first:
- See `docs/building.md` and `quarkus/README.md` for options.
- Then run:
- `bin/kc.bat start-dev`

---

## 6) Debugging 🔎

- **Quarkus dev mode**
- `quarkus:dev` exposes a debug port (commonly `5005`).
- If you need to suspend at startup:

```bash
.\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 (commonly `8787`):
- `kc.bat --debug start-dev`

---

## 7) UI development (Admin / Account consoles) 🖥️

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/`

---

## 8) Tests (don’t run the full suite first) 🧪

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`

- **Default database**
- Embedded H2 by default; see `docs/tests-db.md` for vendor testing.

---

## 9) Troubleshooting cheat sheet 🛠️

- **“Wrong Java version” / build fails early**
- ✅ Ensure JDK is **17/21/25**
- ✅ `java -version` shows the right one
- ✅ Set `JAVA_HOME` accordingly

- **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`)

---

## 10) How we work (Inventorsoft expectations) 🤝

- **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.md` for `spotless:check` / `spotless:apply`.
- **When in doubt**
- Start by reading:
- `docs/building.md`
- `quarkus/README.md`
- `js/README.md`
- `CONTRIBUTING.md`

---

## 11) Definition of Done (DoD) ✅

Use this as a shared checklist before requesting review / merging.

### 11.1 Newcomer first-week DoD (good progress in first days) 🌱

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-dev` and access Admin Console.
- ✅ Understands high-level repo map (`quarkus/`, `services/`, `model/`, `rest/`, `js/`).
- **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).

### 11.2 Standard PR DoD (for all contributors) 📌

- **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 `mvnw` wrapper).
- ✅ 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.
- **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.

---

## 12) Useful links inside this repo 🔗

- **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`

---

## 13) LLM context sizing: top 5 heaviest areas 🧠

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,197` bytes
- Estimated tokens: `9,338,549`
- **`testsuite/`** 🧪
- Files: `1826`
- Size: `17,320,929` bytes
- Estimated tokens: `4,330,232`
- **`js/`** 🖥️
- Files: `1177`
- Size: `9,606,587` bytes
- Estimated tokens: `2,401,647`
- **`services/`** ⚙️
- Files: `1709`
- Size: `9,051,153` bytes
- Estimated tokens: `2,262,788`
- **`model/`** 🗃️
- Files: `966`
- Size: `4,655,568` bytes
- Estimated tokens: `1,163,892`

> Note: This is a planning estimate, not an exact tokenizer output. Real token counts vary by model/tokenizer.