README.md
Rama main · réplica de lectura del repositorio original.
# KubeQuest
[](https://github.com/ramideltoro/kubequest/actions/workflows/ci-cd.yml)
**[Open KubeQuest →](https://kubequest.ramideltoro.com)**
Learn Kubernetes by seeing what happens, trying a change, and understanding why it worked. KubeQuest follows one example application, Little Notes, from a first browser request to a recoverable Kubernetes workload.
- **Before Kubernetes:** sixteen public chapters explain apps, client/server requests, HTTP/HTTPS, DNS, ports, server processes, deployment, Git, builds, CI/CD, configuration, data, containers, traffic, debugging and orchestration through browser experiments. [Start here](https://kubequest.ramideltoro.com/foundations).
- **Kubernetes Basics:** fourteen public, short visual lessons with clickable diagrams, simulations, prediction exercises, plain-language explanations and optional deeper commands. No signup, terminal or cluster required. Progress stays in the browser.
- **CKAD Practice:** eight original incident missions with real Kubernetes, a browser terminal, YAML editor, live resource diagrams, progressive hints, authored behavioral grading and explained solutions. Guided, independent and timed modes are available to the authorized owner.
- **Community exercise library:** 152 public, searchable tasks from [dgkanatsios/CKAD-exercises](https://github.com/dgkanatsios/CKAD-exercises) across 10 topics, including Helm, CRDs and container images. Each exercise now has a mission situation, subtitle, interactive diagram, hints, an independently prepared and graded lab, and a public solution video. Practiced/review status stays on this device. [Browse exercises](https://kubequest.ramideltoro.com/ckad/exercises).
- **Guided CKAD curriculum:** four focused lessons add Kustomize overlays, least-privilege RBAC, startup-probe troubleshooting and JSONPath reporting. Each links existing prerequisites and uses the same mission layout, real lab, checks and public walkthrough as the exercise library. Adapted from pinned MIT/Apache-2.0 community sources with visible attribution. [Start guided practice](https://kubequest.ramideltoro.com/ckad/curriculum).
- **Public walkthroughs:** captioned recordings and transcripts show the actual exercises. Live labs, private progress and the optional local AI tutor require verified owner Google sign-in.
- **Visual explanations everywhere:** 45 reviewed diagrams cover all 30 lessons, eight original missions, and the main overviews; another 156 diagrams accompany the exercise and guided missions. Select a part, follow labeled arrows, or compare an example failure. Mobile layouts include readable connections and text alternatives. Progress and curriculum charts explain their actual measures.
- **Dark amber interface:** official Kubernetes/CNCF artwork, readable labels, mobile layouts, reduced-motion support and a compact NutsNews-style footer with local search.
This is an independent CKAD **pilot**, not complete exam coverage or an official exam simulator. Availability depends on the home server and internet connection.
## Links
| Resource | Link |
| --- | --- |
| Live portal | [kubequest.ramideltoro.com](https://kubequest.ramideltoro.com) |
| Public Readme | [Project overview](https://kubequest.ramideltoro.com/readme) |
| Detailed wiki | [Architecture, operations and learning documentation](https://ramideltoro.github.io/kubequest-wiki) |
| UML library | [16 diagrams covering all 14 UML categories](https://ramideltoro.github.io/kubequest-wiki/UML-diagrams) |
| CI/CD | [GitHub Actions](https://github.com/ramideltoro/kubequest/actions) |
| Wiki source | [Versioned Markdown and editable PlantUML](https://github.com/ramideltoro/kubequest-wiki/blob/main/pages/Home.md) |
## Architecture
TypeScript, React/Vite, Fastify and SQLite run on the existing AI server behind Cloudflare Tunnel. Private labs use one disposable KVM guest capped at 4 vCPUs and 8 GiB RAM, with K3s `v1.35.8+k3s1`, preloaded images, ingress, storage and network-policy support. The guest cannot initiate connections to private infrastructure or the internet. Resets recreate the overlay; 30 minutes of inactivity expires a session.
The optional existing Ollama `qwen2.5:7b` tutor receives bounded reviewed content and sanitized evidence. It cannot run commands or determine grades. Answers stream as they are generated, can be cancelled, and have a bounded timeout. Compact resource context and 15-minute model retention reduce waiting. Authored help remains available when inference fails. No additional paid service is required.
## Local development
Use Node **22.22.1** or newer compatible Node 22. Public pages work without credentials; private endpoints fail closed.
```sh
npm ci --ignore-scripts
npm test
npm run docs:check
npm run build
npm start
```
Open `http://127.0.0.1:4340`. For frontend development, run `npm run dev` in a second terminal. Copy the variable names in `.env.example` into your local environment only when needed; never commit real values. Production environment loading is performed by systemd.
Browser verification requires Chromium:
```sh
npx playwright install chromium
npm run test:browser
```
The backend must be running before browser checks. `BROWSER_PATH` can select an existing Chromium executable. UML rendering is maintained in the separate wiki repository using a checksum-verified PlantUML jar and Java 21+.
## Delivery
Pull requests run tests, security/dependency checks, documentation validation, build, browser interactions and automated accessibility checks on GitHub-hosted runners. Successful `main` builds produce an immutable artifact and deploy over the existing Cloudflare SSH route using a dedicated restricted key.
Deployment refuses to restart an active lab, backs up SQLite, atomically switches releases and verifies the exact commit. Failed local health checks restore the previous release. A separate manual workflow rolls back to an installed commit. The authored wiki lives in [kubequest-wiki](https://github.com/ramideltoro/kubequest-wiki) and is hosted on GitHub Pages. Every deployment and rollback exports current code-derived documentation, triggers wiki publishing, and waits for the hosted wiki to match the live application commit. Changes affecting written guides require a reviewed wiki commit in `wiki-review.json`, enforced by CI.
See [CI/CD](https://github.com/ramideltoro/kubequest-wiki/blob/main/pages/CI-CD.md), [operations/recovery](https://github.com/ramideltoro/kubequest-wiki/blob/main/pages/Operations.md), [content authoring](https://github.com/ramideltoro/kubequest-wiki/blob/main/pages/Content-authoring.md) and [validation](https://github.com/ramideltoro/kubequest-wiki/blob/main/pages/Validation.md).
## Artwork and ownership
Kubernetes symbols come from the [official community icons](https://github.com/kubernetes/community/tree/main/icons); project logos come from [CNCF artwork](https://github.com/cncf/artwork) or their vendors. Original colors/proportions remain intact. Source/license records and hashes are in [public/icons/sources.json](public/icons/sources.json). UI controls use Lucide icons. KubeQuest is a plain text wordmark.
Created by [Rami Del Toro](https://www.ramideltoro.com). Not affiliated with CNCF, Kubernetes, or The Linux Foundation. Third-party artwork retains its respective ownership and licensing terms.
## Community exercise attribution
The exercise library is adapted from **CKAD-exercises**, copyright (c) 2018 Dimitris-Ilias Gkanatsios, under the MIT license. The complete license is preserved in `content/ckad-upstream/LICENSE` and served at `/licenses/ckad-exercises.txt`. The pinned, unmodified source snapshot and provenance are in `content/ckad-upstream/`; generated library data can be rebuilt with `npm run exercises:import`. The source snapshot preserves the original commands and version assumptions. Runnable missions are adapted for the isolated Kubernetes 1.35 guest; each mission explains changes such as bundled Helm charts and local practice registries. Rebuild the mission data with `npm run labs:build`. The source topic percentages are historical, not current exam weights. See the wiki exercise-library guide for maintenance and validation.