Espresso Linux

Installing Espresso

Boot any live CD (Debian, Gentoo, SystemRescue, NixOS...), unpack the root filesystem, chroot in and build up from there. Partitioning, the kernel and the bootloader are yours.

0. Partition the disk

On UEFI you need two partitions on a GPT disk: a small FAT32 EFI system partition (ESP) that the firmware boots the kernel from, and the root filesystem. Find your disk first. This wipes it:

lsblk                          # sda, nvme0n1, ...
printf 'label: gpt\nsize=512MiB, type=U\ntype=L\n' | sfdisk /dev/sdX
mkfs.vfat -F 32 /dev/sdX1      # the ESP
mkfs.ext4 /dev/sdX2            # root

type=U is the EFI system partition and type=L Linux; the second partition takes the rest of the disk. On NVMe the partitions are /dev/nvme0n1p1 and p2. If the live CD has no mkfs.vfat, install dosfstools (apt install dosfstools on Debian). fdisk or cfdisk work too if you'd rather partition by hand: make the first partition 512 MiB of type "EFI System".

1. Unpack the root filesystem

mount /dev/sdX2 /mnt
cd /tmp
curl -fLO https://pkg.charliesmp.net/espresso/espresso-rootfs-latest.tar.xz
curl -fLO https://pkg.charliesmp.net/espresso/SHA256.sig
curl -fLO https://site.charliesmp.net/espresso/espresso.pub
signify -C -p espresso.pub -x SHA256.sig espresso-rootfs-latest.tar.xz
tar xpf espresso-rootfs-latest.tar.xz -C /mnt

The tarball holds espresso-base, bean, curl, sdhcp and their dependencies, all owned by bean.

signify checks that the tarball is the one we signed. It should print Signature Verified and espresso-rootfs-latest.tar.xz: OK; don't unpack it if it doesn't. Debian's live CD calls the tool signify-openbsd. Check that espresso.pub ends in this key, which is also in the bean repository:

RWR0n3H6q6y7RNf3tmO5/AcL+sNPy+fUtSg35nt5PeAwPVWAqU9P5RbP

Without signify, sha256sum at least catches a damaged download, but it can't tell you who made the tarball:

curl -fLO https://pkg.charliesmp.net/espresso/espresso-rootfs.sha256
sha256sum -c --ignore-missing espresso-rootfs.sha256

After that, every bean update checks the package index against the same key, which the rootfs ships as /etc/bean/espresso.pub.

2. Chroot in

cp /etc/resolv.conf /mnt/etc/
mount -t proc proc /mnt/proc
mount --rbind /dev /mnt/dev && mount --make-rslave /mnt/dev
mount --rbind /sys /mnt/sys && mount --make-rslave /mnt/sys
chroot /mnt /bin/env -i HOME=/root TERM="$TERM" PATH=/bin:/usr/bin /bin/sh -l

Use --make-rslave: without it, unmounting the chroot's /dev and /sys later can unmount the live system's own.

3. Build a kernel

bean update
bean -y install gcc make bison flex bc libelf pkg-config xz gzip netbsd-curses
curl -fLO https://cdn.kernel.org/pub/linux/kernel/v7.x/linux-7.4.tar.xz
tar xJf linux-*.tar.xz && cd linux-*/
cp /usr/share/espresso/kernel.config .config
make olddefconfig && make menuconfig   # add your hardware's drivers
make -j"$(nproc)" bzImage
cp arch/x86/boot/bzImage /boot/vmlinuz

kernel.config is a tinyconfig-based baseline: it boots on UEFI with the EFI stub, has a framebuffer console, SATA (AHCI) and NVMe disks, Intel e1000e and virtio for VMs. Add your own hardware's drivers, and set CMDLINE to your root partition. kernel.config.t440p is a known-good config for a ThinkPad T440p to compare against. On real hardware, check that you have:

4. Boot it

The simplest way on UEFI is no bootloader: the kernel is its own EFI program (EFI_STUB), and the firmware runs EFI/BOOT/BOOTX64.EFI from the ESP by default. Build the root partition into the kernel's command line, in menuconfig under "Processor type and features": CMDLINE_BOOL with CMDLINE="root=/dev/sdX2 rw rootwait". Then, still in the chroot:

mkdir -p /boot/efi
mount /dev/sdX1 /boot/efi
mkdir -p /boot/efi/EFI/BOOT
cp /boot/vmlinuz /boot/efi/EFI/BOOT/BOOTX64.EFI
umount /boot/efi

Later kernels go in the same way; keep the previous one next to it (e.g. EFI/BOOT/old.efi) to pick from the firmware's boot menu if a new one fails. Espresso has no /etc/fstab and doesn't mount the ESP at boot, so mount it only to install a kernel. With a bootloader such as GRUB or Limine instead, point it at /boot/vmlinuz with root=/dev/sdX2 rw.

Leave the chroot, unmount and reboot:

exit
umount -R /mnt
reboot

/init starts a login prompt on tty1-4 and ttyS0. Networking and daemons go in /etc/rc, which brings up wired networking with sdhcp, and Wi-Fi when eiwd is installed.

5. Users

root starts with an empty password: log in as root, set one, then add yourself.

passwd -a sha512             # root's password
adduser alice                # /home/alice, groups wheel audio video input
passwd -a sha512 alice

For doas (root for members of wheel, with your own password), install it while you're still root:

bean install opendoas

Normal users can su and change their own password. /etc/profile sets up PATH and XDG_RUNTIME_DIR.

6. Optional: Wi-Fi

bean install eiwd firmware-iwlwifi-7260   # or your card's firmware
printf '[Security]\nPassphrase=secret\n' > /var/lib/iwd/MyNetwork.psk
chmod 600 /var/lib/iwd/MyNetwork.psk

eiwd is iwd without D-Bus: networks are files, and it joins them and runs DHCP by itself. /etc/rc starts it at boot. The kernel needs CFG80211, MAC80211, your driver (IWLWIFI and IWLMVM for Intel), the kernel crypto iwd uses (KEYS, KEY_DH_OPERATIONS, CRYPTO_USER_API_HASH, CRYPTO_USER_API_SKCIPHER, HMAC, CMAC, MD5, SHA1/256/512, AES, ECB, CBC, DES) and the firmware built in: EXTRA_FIRMWARE="iwlwifi-7260-17.ucode" with EXTRA_FIRMWARE_DIR="/lib/firmware".

7. Optional: the desktop

bean install yawc
swc-launch yawc

Run it from a real terminal (tty1), not over SSH. yawc brings hst, neumenu and wawa along: Mod+Return opens a terminal, Mod+Space the launcher, and ~/wall.jpg becomes the wallpaper. Screenshots: swcsnap image shot.ppm && ppm2png shot.ppm shot.png.

Next: the guide covers packages, building your own, sound, video and the rest of day-to-day use.