From fe8f85b4d2b332d5517a1319ae965ef6d8d797bc Mon Sep 17 00:00:00 2001 From: Oleksandr Val Date: Wed, 25 Mar 2026 20:29:36 +0200 Subject: [PATCH] Task-01. Add documentation to simplify on-boarding of new-comers. --- README.md | 326 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) diff --git a/README.md b/README.md index 16ff967..c7b1a49 100644 --- a/README.md +++ b/README.md @@ -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) + - 🧰 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" +``` +- **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. \ No newline at end of file