Use issues for bugs and ideas; the list for discussion.
+Use issues for bugs and ideas; email for discussion.
Longer conversations about philosophy, design decisions, and direction. Subscribe or join the thread.
-keru@keru.org (placeholder)
-A real-time room for early adopters and contributors.
-#keru:matrix.org (placeholder)
+ direct + Email +Longer conversations about philosophy, design decisions, and direction.
+From booting the ISO to a first-boot system — the whole arc in one read.
referencemake.confThe profile file your selections produce, and every variable it knows.
referenceProfile systemHow profile/make.conf templates the build and the swappables.
specRecipe formatThe formal spec for kama package recipes — fields, hooks, tiers.
+ howtoRecipe authoringWrite your first kama recipe, with real examples from the repo.
referenceBuild pipelinescripts/build-root.sh and mkfs-root.sh — how a make.conf becomes a rootfs.
+ referenceToolchain bootstrapbinutils → gcc → libc → self-host: what "from scratch" means.
referenceLive initlive/init — how booting the ISO auto-starts the installer.
+ referenceKama configurationEvery kama variable: PKGDIR, ROOT, CACHEDIR, MAKE_CONF, mirrors.
+ referenceMirrors & cacheThe download order and the dl/src/stage cache layout.
+ referenceSecurityTrust model of a source-only build, stated plainly.
+ guideTroubleshootingDiagnose by stage — boot, network, fetch, build, finalize.
+ referenceRelease processWhat a release contains, and how versioning works.
guideSwappables guideEvery component you can choose at install, with the full option list.
guideInstall guideThe end-to-end installation flow, from BIOS to boot.
guideContributeHow to get involved across the three repos and this site.
diff --git a/web/getting-started.html b/web/getting-started.html new file mode 100644 index 0000000..56c6fb8 --- /dev/null +++ b/web/getting-started.html @@ -0,0 +1,77 @@ + + + + + +Zero to a chosen, booting, source-built system.
+Keru 0.1 ships as an ISO. There is no source build to DIY, no binary download, no flashing a rootfs tarball. Boot the ISO, answer the installer, and Keru builds exactly what you chose while you watch.
+ +mkfs-root.sh formats whatever root device the installer points at. It will be written over.| Choice | Default | Why you might change it |
|---|---|---|
| Init system | runit | systemd for optional use — but Keru never forces it. |
| C library | glibc | musl for a smaller static-leaning system. |
| Filesystem | ext4 | btrfs snapshots, zfs features, xfs scaling. |
| Kernel | linux | linux-lts for longevity, hardened for attacks. |
| Privilege elevation | doas | sudo if you live in its muscle memory. |
| Network tools | nmtui | networkmanager, connman, or systemd-networkd. |
Keru installs a bare, honest base — the packages you chose plus the few kama needs to run. From there you shape the rest:
+Everything you don't install, you don't get. No services pretending to be useful, no telemetry phone-home.
+ +Keru is an anti-opinionated Linux distribution. Choose your init, libc, filesystem, kernel, and tools at install time — and it builds exactly what you chose from source. Nothing forced, nothing you didn't ask for.
-Keru is an anti-opinionated Linux distribution. Choose your init, libc, filesystem, kernel, and tools at install time — and it builds exactly what you chose from source. Nothing forced, nothing you didn't ask for.
+ +live demo
+live boot
The ISO carries only the installer. Boot it, it starts the installer automatically, you make your picks — and it builds your entire system from source.
+The ISO carries only the installer. Boot it, it starts the installer automatically, you make your picks — and it builds your entire system from source, live.
[ keru ] Keru OS — craft your system Select the components, press enter for defaults. -== Init system == [runit] -== C library == [glibc] -== Filesystem == [ext4] -== Kernel == [linux] +== Init system == [runit] +== C library == [glibc] +== Filesystem == [ext4] +== Kernel == [linux] == Privilege elevation == [doas] -== Network tools == [nmtui] +== Network tools == [nmtui] Selecting: btrfs ← you choose, Keru builds it ...fetching source... @@ -99,8 +111,8 @@ Selecting: btrfs ← you choose, Keru builds it
Keru 0.1 will ship as a bootable ISO. No source builds, no manual tooling — boot, choose, then watch it craft your system.
home / docs / kama configuration
+Every knob, every default, every path.
+Kama's configuration is environment variables. Nothing to edit inside the script, nothing hidden — set them in the environment (export in a profile, or inline on the command line) and it's done.
| Variable | Default | What it controls |
|---|---|---|
PKGDIR | the kama-packages repo, sibling of the kama script | Where recipes are found. |
ROOT | /tmp/keru/root | Where installed files land. |
CACHEDIR | /var/cache/kama | Base for the dirty working dirs. |
MAKE_CONF | /etc/kama/make.conf | Profile settings (JOBS, CFLAGS, etc.) if present. |
SOURCE_MIRROR | unset | Mirror tried before upstream (set to e.g. mirror.keru.org). |
PURGE_TEMP_DEPS | 1 | Purge temp build deps after kama make. |
JOBS | nproc | Parallel build jobs; recipes call make -j"$JOBS". |
Inside an installed Keru system, the profile at MAKE_CONF feeds the same variables into kama and the build scripts. Your make.conf reference lists the full set.
MAKE_CONF exists it is sourced; missing is not an error.JOBS and CFLAGS from build-host detection.Where source comes from, and where it waits.
+Every Keru build is a network operation. Two mechanisms keep that sane and reproducible: a mirror-first download policy, and a well-defined cache on disk.
+ +SOURCE_MIRROR — tried first when set (the org runs mirror.keru.org so the org can carry most of the traffic).| Dir | Everything | Purpose |
|---|---|---|
dl | Downloads | Already-downloaded archives are reused, never re-fetched. |
src | Extracted | Extraction is skipped when the checked-out source is present. |
stage | Staged builds | Progress survives a failed build; re-running continues. |
Run a mirror yourself and point SOURCE_MIRROR at it. The layout mirrors dl/; the fetch layer treats it as a read-mostly source of truth.
rm -rf /var/cache/kama/src/* — free extracted source (re-extracts on next build).rm -rf /var/cache/kama/dl/* — dump downloads (re-fetches next time).rm -rf /var/cache/kama/stage/* — discard staged builds.home / news / design decisions
home / news / philosophy is the architecture
home / docs / recipe authoring
+Writing a kama recipe, top to bottom.
+Every package in a Keru system is described by a recipe: a plain POSIX shell script in kama-packages. Writing one is closer to filling a form than engineering a build.
kama-packages/TEMPLATE.sh is the canonical starting point. Copy it, fill the easy tier:
This is the entire busybox recipe currently in the repo:
+That's it. Kama downloads, extracts, strips the top dir, builds, stages, and installs.
+ +| Need | Field / function |
|---|---|
| Colliding with another package | provides=(...) conflicts=(...) |
| Build deps that must stay | runtime_deps=(...) |
| Arch-restricted | arch=(x86_64) |
| Repo or vcs sources | noextract=("$url") + own build() |
| Custom fetch (patch first) | pkg_fetch() { default_fetch; patch ...; } |
| Post-install work | pkg_post() · pkg_split() for subpackages |
install() installs into $pkgdir. Kama commits the staging dir to $ROOT only after a successful build.deps. They're purged automatically after the build (AUR-style). Keeps the door clean.license=(SPDX) — supply chain cleanliness starts here.url + version, never a moving "latest".busybox.sh, the smallest real recipe.How a release leaves the kiln.
+Keru's releases are honest about being releases: each one is a tested point in time of the three repos, assembled into an ISO that boots and installs without fanfare.
+ +| Bump | When |
|---|---|
| major | The swappable set changes shape, or the philosophy moves — real milestones like the first ISO. |
| minor | New swappable or a new kama feature that stays backward-compatible. |
| patch | Recipe fixes, installer bugfixes, docs — anything that changes no contracts. |
installer/install.sh plus its payload.live/init — boot the ISO, installer auto-runs.| Check | What passes it |
|---|---|
| Combos boot | The proven set of the offered swappables all boot after install. |
| Installer clean | A full install from a cold boot, no keyboard runtime. |
| No blockers | Nothing warns-but-doesn't-block where it shouldn't; unproven combos warn loudly. |
| Docs match | make.conf, recipes, and this website agree with the shipped code. |
Releases are announced on the news page, with a changelog and the exact repos/commits the ISO was cut from. "0.1 when it's ready" — as tracked in the status above — remains the only roadmap.
+ +The trust model, stated plainly.
+Keru's security stance follows from its design. No binaries, no opaque machinery, no hidden services. That shrinks the attack surface to things you can actually read.
+ +There is no binary package store to compromise. Every package is compiled in your install from original source fetched over the network. The "prebuilt artifact" class of attack simply doesn't exist.
+ +url and version. Nothing is ever pulled "latest" implicitly.The whole vertical slice from "make.conf" to "booted system" is a handful of shell files. That's the honest counter to the "trust the distro binary blob" model.
+ +Privilege elevation is swappable: doas (slender, auditable) is the default, with sudo, opendoas, and plain su available. Keru never preloads root-owned services or hidden daemons.
Pick linux-hardened at install for a hardened kernel, or stick with stable linux. The choice is yours and applied at the moment your system is built.
All three repos are AGPL-3.0. Recipes tag their license explicitly. Nothing in the pipeline is proprietary-black-boxed.
Found a flaw in the installer, kama, or a recipe? File it with the stage and the failing artifact. See contact and troubleshooting.
+ + +Total: 32 pages, all served from web/ in the KeruOS repo — plain static HTML, no framework, dark, with a shared nav/footer injected at runtime.
Total: 48 pages, all served from web/ in the KeruOS repo — plain static HTML, no framework, pure black, with a shared nav/footer injected at runtime.
What "from scratch" actually means.
+A source distro that seeds its compiler is a lie wearing a costume. Keru's stage 0 builds the toolchain from nothing — the assembler, the compiler, the C library, then a self-hosted toolchain package — before a single package in your system tree is compiled.
+ +| Step | What runs | Why first |
|---|---|---|
| 1 | binutils | as, ld, ar — you can't compile without an assembler and linker. |
| 2 | a bare gcc | The C compiler, built against nothing but binutils. |
| 3 | your libc | glibc, musl, or uclibc-ng. Everything userspace depends on it. |
| 4 | a full gcc | Re-built now that the target libc exists (self-hosting). |
| 5 | toolchain package | Freezes the whole toolchain as a kama package for the rest of the build. |
[ keru ] stage 0: bootstrap toolchain +[ keru ] binutils 2.42 ... ok +[ keru ] gcc 13.2 (bare) ... ok +[ keru ] glibc 2.39 ... ok +[ keru ] gcc 13.2 (self) ... ok +[ keru ] toolchain → ROOT ... ok +[ keru ] stage 1: base system+
--host/--target and CC/CFLAGS so nothing sneaks in.Diagnose by stage. The stage points at the file to blame.
+Almost every Keru failure lands in exactly one of five stages: live boot, network, fetch, build, or finalize. Figure out which, and you're most of the way to a fix.
+ +| Symptom | Cause / fix |
|---|---|
| Drops to an emergency shell | live/init couldn't find the installer payload or mount buffers. Check the ISO layout and that you wrote the whole image, not just the files. |
| Installer never auto-starts | The live init runs installer/install.sh on boot. Run it by hand from the shell to see its errors directly. |
| Nothing on screen | Terminal TTY not your display? Verify the kernel picks your console; a plain getty on tty1 is the default. |
1.1.1.1, github.com, the project mirror) and loops: it will offer to run nmtui, then re-check. Let it.nmtui and set a static address. The installer doesn't care how the link comes up, only that it does.mirror.keru.org is tried first; upstream is the fallback. A broken mirror yields timeouts — check SOURCE_MIRROR.url missed a version bump. Fix it or report it — sources are pinned in kama-packages.rm -rf /var/cache/kama/dl/<pkg>.| Symptom | Cause / fix |
|---|---|
| Compile error in a package | Often a C(FLAGS) interaction or a missing build dep. Add the dep and re-run kama make — stage dirs cache progress. |
| Missing header | That's a temp-dep gap in the recipe's deps=(). Contribute the fix: one line in kama-packages. |
| Toolchain failure | Stage 0 is the sharpest edge. A failing binutils/gcc/libc bootstrap is a bug — file it with the full make.conf combo. |
| Kernel build dies with no reason | Free disk or memory on the build host first; kernel builds are hungry. Then check KERNEL_CONFIG in make.conf. |
default runlevel or its service enabled.make.conf combo, and the failing output. That's everything a maintainer needs. See contact.