// chapter 01

install

three explicit, gated stages: rootfs deployment, initramfs build, target configuration. each step enforced and verified.

// good news

praxis v1.5 is out now and fixes most install process issues from v1. grab the latest release and keep in mind there could still be issues - if you find any, report them on github or discord.

preconditions

  • gpt partition table with uefi system partition (512m vfat) and linux root
  • root partition must be ext4
  • both partitions must be mounted before starting
  • hostname must be rfc-compliant

quick setup

praxis-disk /dev/vda /mnt/praxis

does: partition → mkfs → mount → ready for stage 1

manual partitioning

sfdisk /dev/vda <<EOF
label: gpt
size=512M,   type=C12A7328-F81F-11D2-BA4B-00A0C93EC93B
size=+,      type=0FC63DAF-8483-4772-8E79-3D69D8477DE4
EOF
wipefs -a /dev/vda1 /dev/vda2
mkfs.vfat -F32 -n BOOT /dev/vda1
mkfs.ext4 -L ROOT /dev/vda2
mkdir -p /mnt/praxis/boot
mount /dev/vda2 /mnt/praxis
mount /dev/vda1 /mnt/praxis/boot

stage 1 - rootfs deployment

praxis-install --hostname myhost /mnt/praxis

what it writes:

  • /etc/hostname - your hostname
  • /etc/hosts - localhost entries
  • /etc/fstab - uuid-based mounts (from blkid)
  • /etc/machine-id - random 32-char hex
  • /etc/locale.conf - defaults to en_US.UTF-8
  • /etc/localtime - defaults to UTC
  • /etc/praxis/initramfs.conf - initramfs build settings
  • /boot/limine.conf (×4 paths) - bootloader config
  • /boot/EFI/BOOT/BOOTX64.EFI - limine uefi stub
  • /etc/praxis/install-stage - writes "rootfs"

override defaults before stage 2 if needed:

ln -sf /usr/share/zoneinfo/Region/City /mnt/praxis/etc/localtime
echo 'LANG=xx_XX.UTF-8' > /mnt/praxis/etc/locale.conf

stage 2 - initramfs build

mkinitrd /mnt/praxis

what it does:

  • validates stage 1 was run (reads install-stage file)
  • validates /etc/fstab has uuid entries for / and /boot
  • packs live rootfs into newc-format cpio, compressed with gzip -9
  • copies kernel from /usr/share/praxis/vmlinuz → /boot/praxis/vmlinuz
  • writes /boot/praxis/initramfs.cpio.gz
  • writes /etc/praxis/install-stage → "initrd"

stage 3 - chroot configuration

praxis-chroot /mnt/praxis

what it does:

  • validates stage 2 was run (reads install-stage file)
  • bind-mounts /proc, /sys, /dev, /dev/pts, /run into target
  • drops you into a shell inside the target
  • on clean exit, writes /etc/praxis/install-stage → "chroot"

at minimum:

passwd
exit

verification

targetcheck /mnt/praxis

verifies (hard fails if any check fails):

  • all three install stages completed
  • /boot/praxis/vmlinuz and /boot/praxis/initramfs.cpio.gz exist
  • /etc/fstab mounts / and /boot by uuid
  • /boot/limine.conf configured correctly
  • identity files (/etc/hostname, /etc/hosts, /etc/machine-id)
  • timezone and locale configured
  • boot entry matches kernel/initramfs paths

finish and boot

sync
umount /mnt/praxis/boot
umount /mnt/praxis
reboot

with desktop and bundles

praxis-install --hostname myhost --desktop xfce --bundle developer /mnt/praxis

next: qemu - vm workflows for testing and install validation.