feat: architecture page with the three scenarios #4

Merged

marcos-mendez merged 2 commits from feat/architecture-page into main

2026-09-29 17:27:01 -03:00

marcos-mendez commented

2026-09-29 17:09:43 -03:00

(Migrated from github.com)

What the page shows

A new page, architecture.html (served by GitHub Pages at keellinux.org/architecture): the architecture the project aims for, in three scenarios, one inline SVG infographic each, with a status badge in the heading and inside the diagram.

Keel Linux Standalone, "Our goal · not yet released". The goal of the first release: one LXC or VM with application, database and files; keel inspect, keel diff, keel spec apply. It runs from source and test images; there is no release for end users. The network change with its 120 s confirmation window is marked "VM only · in keel 0.9.0, not yet released": in an LXC container the host owns the network and keel only compares it. Webmin shows the network read-only (0019).
Keel Cloud, three nodes, "Planned, decision 0020". Decided, not built. One primary and replicas on WireGuard, two or three of the nodes holding the application; one etcd election by keel-quorum, every data node a voter, the third optionally a data-less voter that is not an appliance; fencing to read-only; database replication and replicas pulling files with rsync. keel-cloud (DNS with a health check, discovery, key exchange) is optional: hand-configured nodes elect and fail over alike, and the public name is then moved by hand. Failover, rejoin and failback choices with 0020's defaults, made once when the set is formed and stored in etcd. The read-only confconsole status panel, and what the design does not promise.
Separated tiers, "Future". A direction with no design yet: only the remote database (0013 phase 1) and Galera (0013 phase 4) are planned pieces. Sharding shown as possible with 0013's caveat.

Example addresses are IPv6 in 2001:db8::/32.

Decisions followed

0013, 0018, 0019, 0020 (final text), and BRIEF section 2 and problem 7.

Other changes

An "Architecture" item in the menu of index.html and guidelines.html, and in the footers. Links use architecture.html like guidelines.html, because tools/sitecheck.py resolves links to files; GitHub Pages also serves it at /architecture.
index.html Status: the stale "nothing is published" line now says what is served for testing and that there is no release for end users; "What is next" no longer lists inspect, diff and apply as future.
README.md lists the new page.
style.css: badges, diagram classes on the existing theme variables, the choices table. No new dependency.

Open question

index.html loads the Plausible analytics script; guidelines.html and the new page do not. Left as is, matching guidelines.html: should the script be on every page?

How it was verified

python3 tools/sitecheck.py .: 3 pages, 7 assets, 0 findings.
The CI command (coverage run -m pytest -q tests, threshold 95): 38 passed, 99 percent.
Headless Chromium screenshots at 1280 px and 375 px, light and dark, checked by eye. Each diagram has a wide and a vertical narrow variant, switched at 56rem; the smallest SVG text is 13 px in the viewBox.
A clean clone of the pushed branch passes the same checks and renders the page.

## What the page shows A new page, `architecture.html` (served by GitHub Pages at keellinux.org/architecture): the architecture the project aims for, in three scenarios, one inline SVG infographic each, with a status badge in the heading and inside the diagram. 1. **Keel Linux Standalone, "Our goal · not yet released".** The goal of the first release: one LXC or VM with application, database and files; `keel inspect`, `keel diff`, `keel spec apply`. It runs from source and test images; there is no release for end users. The network change with its 120 s confirmation window is marked "VM only · in keel 0.9.0, not yet released": in an LXC container the host owns the network and keel only compares it. Webmin shows the network read-only (0019). 2. **Keel Cloud, three nodes, "Planned, decision 0020".** Decided, not built. One primary and replicas on WireGuard, two or three of the nodes holding the application; one etcd election by keel-quorum, every data node a voter, the third optionally a data-less voter that is not an appliance; fencing to read-only; database replication and replicas pulling files with rsync. keel-cloud (DNS with a health check, discovery, key exchange) is optional: hand-configured nodes elect and fail over alike, and the public name is then moved by hand. Failover, rejoin and failback choices with 0020's defaults, made once when the set is formed and stored in etcd. The read-only confconsole status panel, and what the design does not promise. 3. **Separated tiers, "Future".** A direction with no design yet: only the remote database (0013 phase 1) and Galera (0013 phase 4) are planned pieces. Sharding shown as possible with 0013's caveat. Example addresses are IPv6 in 2001:db8::/32. ## Decisions followed 0013, 0018, 0019, 0020 (final text), and BRIEF section 2 and problem 7. ## Other changes - An "Architecture" item in the menu of `index.html` and `guidelines.html`, and in the footers. Links use `architecture.html` like `guidelines.html`, because `tools/sitecheck.py` resolves links to files; GitHub Pages also serves it at `/architecture`. - `index.html` Status: the stale "nothing is published" line now says what is served for testing and that there is no release for end users; "What is next" no longer lists inspect, diff and apply as future. - `README.md` lists the new page. - `style.css`: badges, diagram classes on the existing theme variables, the choices table. No new dependency. ## Open question `index.html` loads the Plausible analytics script; `guidelines.html` and the new page do not. Left as is, matching `guidelines.html`: should the script be on every page? ## How it was verified - `python3 tools/sitecheck.py .`: 3 pages, 7 assets, 0 findings. - The CI command (`coverage run -m pytest -q tests`, threshold 95): 38 passed, 99 percent. - Headless Chromium screenshots at 1280 px and 375 px, light and dark, checked by eye. Each diagram has a wide and a vertical narrow variant, switched at 56rem; the smallest SVG text is 13 px in the viewBox. - A clean clone of the pushed branch passes the same checks and renders the page.