docs/USAGE.md (5263 bytes)
1 # waybase 2 3 A bootable USB/SD installer that puts a fresh Linux on a blank disk: your pick 4 of **KISS, Gentoo, Arch or Alpine**, plus the **Nix** package manager and a 5 **Wayland-only** desktop (no X11) with the compositor you choose. 6 7 One POSIX `sh` installer core (`install.sh`, about 300 lines) and one short 8 backend per base (`backends/*.sh`). It asks a few questions from plain text 9 menus, or reads an answers file for unattended installs. 10 11 ## Quickstart 12 13 ```sh 14 git clone https://github.com/equwal/waybase && cd waybase 15 sh build-image.sh out # needs docker; writes out/waybase.img 16 dd if=out/waybase.img of=/dev/sdX bs=4M conv=fsync # sdX = your USB stick or SD card 17 ``` 18 19 Boot the stick (UEFI or BIOS), log in as `root` (no password), connect 20 Ethernet, and run: 21 22 ```sh 23 sh /media/*/waybase/install.sh # interactive 24 sh /media/*/waybase/install.sh answers.txt # unattended, see answers.example 25 ``` 26 27 Reboot, log in on tty1, and the compositor starts. Super+Return opens foot, 28 Super+d opens fuzzel (dwl: Alt+Shift+Return and Alt+p, its built-in keys). 29 30 ## What you get 31 32 | | KISS | Gentoo | Arch | Alpine | 33 |---|---|---|---|---| 34 | Bootstrap | official chroot tarball + `baseinit` | desktop-openrc stage3 + binary packages only (`getbinpkg`, `usepkgonly`) | official bootstrap tarball + pacman | `apk --root` | 35 | Init | busybox init + runit | OpenRC | systemd | OpenRC | 36 | Seat | seatd (Nix) | elogind | systemd-logind | seatd | 37 | Kernel | Alpine linux-lts + mkinitfs | gentoo-kernel-bin + dracut | linux + mkinitcpio | linux-lts + mkinitfs | 38 | Nix | release tarball, multi-user daemon (runit) | release tarball, multi-user daemon (OpenRC) | release tarball, multi-user daemon (systemd socket) | Alpine `nix` package, daemon (OpenRC) | 39 | Desktop packages | all from Nix | binpkg when one exists, else Nix | native | native (dwl from Nix) | 40 41 Every install also gets PipeWire + WirePlumber, the foot terminal, the fuzzel 42 launcher, optional LUKS2 encryption of the root partition, GRUB for both UEFI 43 (removable path, no NVRAM writes) and BIOS, and one user account in the 44 `wheel`, `video`, `input` and `audio` groups. 45 46 Disk layout (GPT): 1 MiB BIOS boot, 512 MiB ESP, 1 GiB `/boot` (ext4, 47 unencrypted), the rest is `/` (ext4, on LUKS2 if you choose encryption). 48 49 Compositors: **sway, river (river-classic 0.3; river 0.4+ needs a separate 50 window manager), labwc, dwl**. Hyprland is left out: it has no headless 51 software-rendering mode to test and needs a GPU. When a base has no native 52 package, the installer takes it from Nix into the system profile 53 `/nix/var/nix/profiles/waybase` and links Mesa to `/run/opengl-driver`, so Nix 54 GL programs find drivers. `/etc/waybase-from-nix` lists what came from Nix. 55 56 ## Tested matrix 57 58 `test.sh` boots the image in QEMU (KVM, `-cpu Nehalem` so nothing may need 59 AVX), installs unattended, boots the result by BIOS and by UEFI, unlocks LUKS, 60 logs in as the new user, and checks `nix --version`, the Nix daemon, and that 61 each compositor starts headless (`WLR_BACKENDS=headless`) and opens a Wayland 62 socket. 63 64 MATRIX 65 66 Run one yourself: `sh build-image.sh out && sh test.sh out arch sway encrypt`. 67 68 ## Security notes 69 70 - The installer erases the whole target disk. Interactive mode makes you type 71 the disk name twice; `YES=1` in an answers file skips that. 72 - An answers file is shell code, sourced as root, and holds passwords in plain 73 text. Keep it off shared media and delete it after the install. 74 - `/boot` is not encrypted (kernel and initramfs are readable and could be 75 replaced by someone with physical access). Only `/` is on LUKS2. 76 - Live image: `root` has no password, as on the stock Alpine ISO. Do not boot 77 it on an untrusted network longer than the install takes. 78 - Downloads come over HTTPS from the official mirrors (Alpine, Arch, Gentoo, 79 GitHub for KISS, releases.nixos.org). Arch and Gentoo verify package 80 signatures with their own keyrings; the KISS tarball and the Nix tarball are 81 trusted on HTTPS alone. 82 - On KISS, the root-run `seatd` and `udevd` come from the root-owned Nix 83 profile, which users cannot modify. 84 85 ## Licences and why no image is released 86 87 waybase itself is MIT. The image is the official Alpine ISO with these 88 scripts added; it contains GPL software, so redistributing it would oblige us 89 to also ship the matching sources. The bases (KISS, Gentoo, Arch), Nix (LGPL 90 2.1) and linux-firmware (mixed, redistributable) are downloaded from their 91 official mirrors at install time and never redistributed by this project. So 92 this repo ships the build script, not a built image: `build-image.sh` takes 93 about a minute. 94 95 ## Prior art 96 97 archinstall (Arch only), setup-alpine (Alpine only), Gentoo has no official 98 installer, nixos-anywhere (NixOS only), KISS has a manual install guide. None 99 of them offers a choice of base, Nix on that base, and a ready Wayland 100 session from one image. waybase does, with an unattended mode tested in CI. 101 102 ## Known gaps 103 104 - GPU, audio and input on real hardware are not covered by the QEMU tests. 105 - Nix-supplied compositors on KISS and Gentoo use Nix's Mesa; NVIDIA needs 106 extra work. 107 - Kernel updates on Gentoo produce new file names; `/boot/grub/grub.cfg` then 108 needs the new names by hand. 109 - No Wi-Fi setup: install over Ethernet.