Basic Basix installation guide
To follow this guide, you should already largely be comfortable installing a Linux distribution manually.
The installation process for Basix is not unlike that of Kiss Linux or, to a lesser extent, Gentoo.
This guide will be assuming a UEFI target.
Getting started
To start, you need to have another distribution to perform your bootstrap. Generally, I use the Void Linux live ISO, but largely this can be bootstrapped from pretty much whatever will boot.
At minimum, whatever you deploy Basix from needs to have a basic set of utilities, specifically a tar implementation and ideally a chroot wrapper, such as Void's xchroot or Kiss' kiss-chroot. You will also need the fsprogs for whatever filesystem you choose to deploy, as well as cryptsetup if you intend on encrypting your disk (you should).
Partitioning the disk
First, one must partition the target disk- same as any other distribution. You may use fdisk, cfdisk, parted, whatever partitioning tool you want.
Generally, UEFI systems consist of two partitions- that being the ESP (EFI System Partition) and the root partition. For the most part, more than two partitions is rarely ever warranted.
The sizes of these are somewhat arbitrary, but I largely recommend defaulting to a minimum of 500M for your ESP. This should provide you with enough room to grow.
The second partition, in general, consumes the rest of the disk.
Formatting your partitions
Your ESP should generally be formatted as fat32. Some motherboards may have builtin drivers for things like ext4, but this is rather unlikely.
Using sda as an example disk here, you may do this with:
mkfs.vfat -F32 /dev/sda1
where sda1 is the small ESP created in the section prior.
For your root partition, you have several choices.
You may, for example:
- Encrypt the partition as a whole with cryptsetup (no, you do not need to split off /boot)
- Rock it as is and just create the filesystem on the root partition with no encryption
I largely recommend encrypting the root filesytem regardless of what this machine is or what it's used for, it's pretty much free security short of a $5 wrench attack. I can't think of much reason to avoid protecting your data.
Encrypted root
In the case of encryption, you may:
cryptsetup luksFormat --type luks2 /dev/sda2
and enter your passphrase.
Note that the version of GRUB currently in the Basix core repository does not support luks2, so you may replace the --type flag with luks1. This only applies if you don't intend on using something else, such as just booting a UKI directly.
Once encrypted, you must:
cryptsetup luksOpen /dev/sda2 root, where root may be any name you'd like to give this container. This is rather arbitrary.
Once unlocked, it's time to pick a filesystem. The currently supported filesystems by the Basix core repository are xfs and ext4. For this example, I will go with xfs as that is my preference.
Given this example, run:
mkfs.xfs /dev/mapper/root
and wait for it to finish.
Unencrypted root
It's time to pick a filesystem. The currently supported filesystems by the Basix core repository are xfs and ext4. For this example, I will go with xfs as that is my preference.
Simply run:
mkfs.xfs /dev/sda2
and wait for it to finish.
Mounting your partitions
Whether you chose to encrypt or not, the process here is largely the same- we need to mount the root partition, create a directory for the ESP mount, and mount that as well.
Using the encrypted setup as an example, run:
mount /dev/mapper/root /mnt
Your root partition should now be mounted. Now, creating the mountpoint for the ESP:
mkdir -p /mnt/boot/efi
You can largely put this kinda wherever, but /boot/efi is the recommended location for Basix.
Next, mount the ESP:
mount /dev/sda1 /mnt/boot/efi
Extracting the Basix rootfs tarball
Once you've got your disk set up and ready, you may deploy the Basix rootfs.
This guide largely assumes you've downloaded this to your live environment one way or another, but basically:
tar xvf basix-rootfs.tar.gz -C /mnt
Note that basix-rootfs.tar.gz is not likely to be the exact name of the tarball you've downloaded.
Configuring the fstab
If you're using Void, there is an included xgenfstab script that can set up your fstab for you. Arch has an equivalent to this, but it is untested by me.
If you don't have an fstab generation script, you may:
git clone https://github.com/glacion/genfstab
cd genfstab
./genfstab /mnt > /mnt/etc/fstab
Regardless of what you do here, make sure to look over this as opposed to blindly accepting that it's valid.
Chrooting into the Basix system
Once you've done everything listed above, you should be ready to get a shell on your new Basix installation.
I largely test this just with Voids xchroot.
Following that example, run:
xchroot /mnt
and you should be greeted by a Basix shell.
Note that if not all mounts and otherwise are created properly, the bpm build system is unlikely to be functional.
Configuring the build system and recompiling base
First, we need to fetch the Basix core repository.
This can be done by running bpm pull.
Editing your bpm.conf
Open up /etc/bpm/bpm.conf in the included vi text editor.
If there are any adjustments you'd like to make to build flags or otherwise global bpm behavior before building and installing packages, now's the time to do that.
For example, these are my own compiler settings:
: "${CFLAGS:=-O2 -pipe -march=x86-64-v3 -mtune=generic -fno-plt -fno-semantic-interposition}"
: "${CXXFLAGS:=$CFLAGS}"
: "${LDFLAGS:=-Wl,-O1,--as-needed,--sort-common,-z,pack-relative-relocs}"
: "${CGO_CFLAGS:=$CFLAGS}"
: "${CGO_CXXFLAGS:=$CXXFLAGS}"
: "${CGO_LDFLAGS:=$LDFLAGS}"
: "${RUSTFLAGS:=-C opt-level=3 -C target-cpu=x86-64-v3 -C target-feature=-crt-static -C link-arg=-Wl,-O1 -C link-arg=-Wl,--as-needed -C link-arg=-Wl,--sort-common}"
: "${GOFLAGS:=-trimpath -buildvcs=false}"
: "${GOAMD64:=v3}"
: "${CGO_ENABLED:=1}"
: "${ZIGFLAGS:=-Doptimize=ReleaseSafe -Dcpu=x86_64_v3}"
It's also perfectly valid to just not touch these. Up to you.
Recompiling the Basix base system
Before building anything, the base of the buildroot needs to be compiled raw on the host.
The reason for this is that bpm builds packages in what is basically an isolated chroot and the packages to construct it need to exist prior to a build.
To do this, run:
BPM_BUILDROOT= bpm build baselayout musl busybox make binutils gcc linux-headers bzip2 pigz certs pkgconf zstd xz b3sum
Once you've done that and configured your bpm.conf to your liking, recompile and reinstall everything on the base system with:
cd /var/db/bpm/installed/
bpm build * && bpm install *
And wait for this to finish. Given Basix is a rather lean system by default, this shouldn't take too long on reasonable hardware.
Installing the Linux kernel
You may have noticed that Basix didn't ship with a kernel by default. This is very much intentional. You may install the kernel as configured by me by simply running:
bpm install linux-stable for the latest stable kernel release, or
bpm install linux-lts for the latest lts branch
..and waiting. Depending on your hardware, this may take a while.
If you would like to configure your own kernel, you must shadow the linux package. You may view directions for this in the /etc/bpm/repos.conf file.
To configure your own kernel, simply replace the dotconfig file in the linux packages files/ directory with your own. This is very much not a required step.
You may also tune your kernel to a lesser extent with use flags. By default I've disabled various things I can't imagine a typical user needing, such as FPGA support for example- but also support for things that won't work well or at all on Basix anyway, such as novideo GPUs. If you want to do this, take a look at /etc/bpm/package.use and bpm q linux-stable for a readout of available use flags.
Installing firmware
If you aren't running Basix in a virtual machine, you probably need to do this (if you're using fully foss hardware, i figure you're well aware of that fact).
You may install the mostly closed source set of firmware blobs by running:
bpm install linux-firmware
By default, this includes a slightly shrunk down subset (no nvidia support, primarily) of the Linux firmware collection, and should cover all reasonable hardware.
If you would like to strip this of things you don't need, or I've disabled something you do need, you may control this with use flags the same way you may have with the kernel.
Installing fsprogs
Install whatever filesystem programs you need. For this example, the package name would be xfsprogs. At minimum, you should probably have dosfstools on a UEFI system.
Installing network utilities
If you simply use dhcp on your network via ethernet, all you need to do is install the dhcpcd package and enable its services (see the services page).
Otherwise, if you're using wireless, you may additionally install the wpa_supplicant package.
Configure these the same way you would elsewhere.
Setting up an initramfs
You probably need to do this.
If you've decided to roll with an encrypted setup, install the cryptsetup package BEFORE generating your UKI.
The currently supported option for initramfs generation on Basix is via tinyramfs, documentation can be found on the linked Github repo.
A valid configuration for the setup I've described here today may be:
compress="gzip -9"
hostonly=true
hooks="mdevd,luks"
root_type=xfs
luks_root=UUID=<UUID of your luks container>
luks_name=root
root=UUID=<UUID of your root partition under the luks container>
and this config is expected to be created at /etc/tinyramfs/config.
Note the inclusion of the mdevd hook and the order the hooks are listed in.
Setting up a boot chain
This is a required step. As is, your Basix installation will be unable to boot.
There are several things you can choose to do here:
- Use a UKI to boot the system directly via the UEFI (recommended)
- Use the GRUB bootloader (useful for BIOS installations, potentially also useful if you're Librebooted)
- Set up your kernel to be its own bootloader via efistub
Assuming you choose to roll a UKI, install the following packages:
buki
systemd-boot-efistub
efibootmgr
After doing so, run buki for help on building a UKI.
If you've installed the tinyramfs initramfs generator, you may use that to generate your UKI instead of using buki. Consult their documentation on that.
Once you've built your UKI, place it somewhere on your ESP. A valid location is typically /boot/efi/bootx64.efi.
Next, we need to generate a boot entry that points at this UKI. This can be done with the following, given the examples on this page:
efibootmgr --create --label "Basix Linux" --disk /dev/sda --part 1 --loader "\bootx64.efi"
Note the backslash in the loader path, we're in Windows land here. In addition, note that the loader path is relative to the root of your ESP.
The label can be whatever you want, get creative.
Non-UKI boot chains
Consult other distributions instructions on setting up GRUB or efistub.
Can this be automated once I've set it up once?
Yep. Create hooks in /etc/bpm/hooks/ to automate the configuration of your boot chain setup on update for the Linux kernel.
Finishing up
Don't forget to set your passwd for the root user at least.
You should look at /etc/sv and see if there are any services you want to enable before rebooting. At minimum, you should probably enable some gettys, mdevd, and mdevd-coldplug.
From this point on, you should be ready to reboot into your new system. You could go ahead and build and install more packages now if you want, though. Good examples may be a more fleshed out text editor such as vim or emacs, or potentially something like openresolv for networking.
Have fun!