mighty easy rde

unlisted · bienjensu's blog

Guix System and rde for the masses

Table of Contents

⚠ This guide is unfinished and a work in progress. Do not use it.

introduction #

Several people I know who use Nix have recently been asking me how best to start using Guix. That is, without going through the difficult series of configuration bankruptcies which usually precede a full installation.

Hence, this is a guide for installing Guix System, configured with rde, using a new Guix and rde starter pack, me-rde (mighty easy rde).

It is aimed at people familiar with NixOS and its home-manager module who want to transition to, or try out, a Guix set-up. I will point out parallels when apt.

However, pains have been taken to make this guide accessible.

a short note on non-free software #

As a GNU project, Guix recommends (among other things) the use of a fully free software stack and discourages the use of any non-free components.

I agree.

However, precisely because GNU respects your autonomy as a user-engineer, it is easy to add in non-free components to your Guix install.

This guide will detail both free and non-free installations. But it strongly recommends the free path, and urges you to make changes to your hardware and habits which might prevent you from traveling down this path.

On a similar topic, the Guix HPC non-free repository says,

″ This [repository] is provided for convenience to HPC researchers and practitioners. However, note that non-free software denies users the ability to study and modify it. Thus, these packages are detrimental to user freedom and to proper scientific review and experimentation.1

The information on non-free installations is provided here in very much the same spirit, perhaps consider it 'harm reduction'. I won't mention this topic again in this guide in this register, but please keep it in mind.

making an installation usb #

downloading an iso #

Depending on whether you require non-free components to carry out an install (such as firmware for wifi cards), you will need to download one of two Guix ISOs:

Bear in mind that unless you need non-free components to carry out an installation (even if you plan to install a non-free kernel), the free iso is preferable as it's more up-to-date.

Additionally, if you want to try out a Guix/rde live image before installing, to get feel for it, download one of:

If the ISO you've downloaded has a signature file, you can verify the file against the signature by typing

1gpg --verify [signature file] [iso]⮐

🤔 This guide represents typing return/enter with the ⮐ symbol.

writing the usb #

Assuming you're using some kind of POSIX compatible system, you can type

1ls /dev/⮐

to get a list of devices.

If you've plugged in a USB stick, it should show up in the listing under something like /dev/sdb or /dev/sdc.

If you're unsure, and you have standard Linux utilities, type

1lsblk⮐

which will show a list of block devices with their corresponding size and mount point.

⚠ Beware that the following step could damage your system and/or obliterate data if you've misidentified the block device. Double check and ask a friend if you're still unsure.

Then, to write to the USB stick, type

1dd if=[path to ISO] of=[path to device] bs=32M status=progress oflag=sync⮐

You will need privileges to run this command, so you need to use sudo or some other utility.

For instance, my USB device is located on /dev/sdb I am in the directory of my ISO file named guix.iso, and I use sudo, so I will type

1sudo dd if=guix.iso of=/dev/sdb bs=32M status=progress oflag=sync⮐

This process might take some time, be patient.

booting into Guix #

  1. Plug the USB in to the computer you want to install Guix on,
  2. interrupt its boot process by whatever means necessary (pressing f12 or tab or something), and
  3. ensure the USB stick is booted.

Some BIOSs make this convenient by allowing you to select a temporary boot device, for others you have to increase the priority of the USB stick in the boot order.

A GRUB interface should show up, select the first option.

😎 If you decided to try out rde using one of the live images, you should be able to log in to the system with username guest and password guest. Have a look around!

getting to the shell #

Once the install disk has loaded, a bright blue screen will greet you.

It will ask you to set your locale language and location, using ↓ ↑ and ⮐.

Kindly oblige, although refuse to stay for tea by selecting the second option, "Install using the shell based process".

Press ⮐ again, and you're in the shell.

setting up #

partitioning #

This guide recommends setting up full disk encryption with LUKS and running a btrfs filesystem.2

Assuming you're using a new-ish computer with support for UEFI and GPT,3 we'll need to create two partitions:

  1. the EFI partition, which will store the files needed to boot, and
  2. the main partition, for our btrfs filesystem, encrypted with LUKS.

Firstly, identify the block device of the disk you want to install Guix on to, just like you identified the USB stick above, using ls /dev/ and lsblk.

For instance, my lsblk reports two main devices:

Hence I'll run my partitioning commands on /dev/sda.

⚠ As above, the following steps will effectively erase all the data on the disk specified. Make sure you've identified the right disk.

Start by opening an fdisk command line by typing,

1fdisk [primary disk]⮐ # for me, fdisk /dev/sda

You can type p⮐ to see the current layout of the drive, if any, and m⮐ to see a list of all available commands.

Type,

1g⮐

to queue up creating a new, empty GPT partition table.

Then type,

1n⮐

to start making our first partition, the EFI partition.

Press ⮐ to accept the default sector number, and press ⮐ again to accept the default first sector, 2048, and then type

1+1G⮐

to make it 1GB large.

Type p⮐ to check your work. There should be one entry, looking something like

1Device     Start     End Sectors Size Type
2/dev/sda1   2048 2099199 2097152   1G Linux filesystem

Let's make the next partition, which will be our encrypted btrfs partition.

Type,

1n⮐             # new partition
2⮐              # default sector number
3⮐              # default first sector
4+[size]G        # or just ⮐ to use whole disk

which will create the partition.

Again, type p⮐ to check your work. It should look something like

1Device       Start       End   Sectors Size Type
2/dev/sda1     2048   2099199   2097152   1G Linux filesystem
3/dev/sda2  2099200  84095999 838860800 400G Linux filesystem

Finally, we need to set the type of our EFI partition to.. well.. EFI!

Type,

1t⮐       # change a partition type
21⮐       # select the first partition
31⮐       # change its type to 1 (EFI)

to change the partition type.

Typing p⮐ should now show that the type of your first partition has been changed to EFI.

Mine looks like this,

1Device       Start       End   Sectors  Size Type
2/dev/sda1     2048   2099199   2097152    1G EFI System
3/dev/sda2  2099200 840959999 838860800  400G Linux filesystem

😇 Feel like you've messed up? Don't worry, all these changes have only been queued up! Type q⮐ to exit fdisk, and start again.

Finally, type w⮐ to write your queued changes to disk.

encrypting + formatting #

Running lsblk should now show two, newly created partitions on the disk to which you want to install Guix.

Mine looks like this,

1NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
2sda      8:32   0 476.9G  0 disk
3├─sda1   8:33   0     1G  0 part
4└─sda2   8:34   0   400G  0 part

Now we're going to format the partitions.

EFI partitions need to be formatted as FAT32, hence type,

1mkfs.fat -F32 [path to EFI partition]⮐ # /dev/sda1 for me

Next, we're going to format the main partition using LUKS. This command will prompt you for a password which you will use to decrypt the partition on boot.

1cryptsetup luksFormat [path to main partition]⮐ # /dev/sda2 for me

✍ This is an important password. It's a good idea to make it something different than the password you'll use to log in to your account. Consider writing it down somewhere so you don't forget it.

Next, we're going to open our encrypted partition and mount the transparently decrypted partition on /dev/mapper/enc. This command will prompt you for the password you just used.

1cryptsetup open [path to main partition] enc⮐

Finally, we're going to format the transparently decrypted partition as btrfs,

1mkfs.btrfs /dev/mapper/enc⮐

Running lsblk again should show something like this,

1sdc       8:32   0 476.9G  0 disk
2├─sda1    8:33   0     1G  0 part
3└─sda2    8:34   0   400G  0 part
4  └─enc 253:0    0   400G  0 crypt

creating + mounting btrfs subvolumes #

Btrfs supports making multiple subvolumes inside a single btrfs filesystem, this not only helps you organise your disk, but it also will allow you to specify and otherwise control the characteristics of the various subvolumes.

For instance, you might want to utilise btrfs's snapshot feature, but only for your /home directory. Or you might want to put /var/log on its own subvolume with a quota to prevent logs filling up your device.

Firstly, let's mount our base btrfs partition, /dev/mapper/enc, on /mnt,

1mount -t btrfs /dev/mapper/enc /mnt⮐
2cd /mnt⮐

Now let's make a series of subvolumes,

1btrfs subvolume create {@, @boot, @home, @gnu, @var}

The '@' symbols aren't necessary, but they help us remember these are subvolumes and not regular directories. In fact, an ls -l will reveal these look very much like subdirectories. That subvolume named just '@' will be our root, and we'll mount the other subvolumes inside of our root subvolume.

You can think of the base btrfs filesystem we currently have mounted at /mnt as being a bag, or container, of subvolumes which we then map to the correct places at boot.

In fact, lets do that mapping manually, right now.

First, unmount the base btrfs filesystem (our bag) from /mnt,

1cd /⮐
2umount /mnt⮐

Next, mount our root subvolume, @, at /mnt,

1mount -o subvol=@ /dev/mapper/enc /mnt⮐
2cd /mnt⮐

Now we'll create the mount points for each of our subvolumes (and our EFI partition from earlier),

1mkdir {boot, boot/efi, home, gnu, var}⮐

and mount our subvolumes (and EFI partition),

1mount -o subvol=@boot /mnt/boot⮐
2mount -o subvol=@home /mnt/home⮐
3mount -o subvol=@gnu /mnt/gnu⮐
4mount -o subvol=@var /mnt/var⮐
5mount /dev/sda1 /mnt/boot/efi⮐

After all that we're ready to start configuring our system with rde!

configuring Guix with rde #

downloading me-rde and starting minimal-emacs #

Now we're going to introduce some Guix utilities by way of setting up the environment we'll use to configure our system before installing it to our newly organised disk.

Just like Nix, Guix has a command which lets us create temporary environments filled with whatever we like. There's lots of ways to use it, including flags to completely isolate an environment or even run it in a container.

For now, we just need git and make to fetch and initialise our configuration.

Type,

1guix shell git make⮐

And Guix will spin up our shell.

Note what's happening. While Guix's main repository is completely built from source, the project also serves a system of substitutes built by remote machines, as Nix's binary cache does.

These substitutes are intended and often checked to be byte-for-byte identical (when possible)4 to the version you might build locally with the same derivation, unlike Nix.5 Combined with Guix's ability, like Nix, to declaratively specify the state of a system, Guix is highly reproducible.

Both in the sense of being able to do cool things (behavioural reproducibility, a toolchain like Nix's which lets you do things like spin a VM up from a declared configuration), and in a stronger theoretical sense where the only guarantee of true behavioural reproducibility we have is byte-for-byte reproducibility (maybe because of the halting problem, I'm not an expert!).

Once Guix has spun up our shell, we can clone the rde starter pack I made in tandem with this guide,

1cd ~⮐
2git clone https://git.sr.ht/~bienjensu/me-rde⮐
3cd me-rde⮐

We'll be using this to configure our Guix system almost entirely declaratively. First we need to bootstrap the very guix command we'll be using, according to the commits of the 'guix' and 'rde' channels specified in lock/channels-lock.scm.

Type,

1make -k guix⮐

This will take a while!

configuring your rde system #

configuring your rde user #

installing to disk #

tips, tricks and pointers #

  1. https://gitlab.inria.fr/guix-hpc/guix-hpc-non-free ↩︎

  2. If you don't want to do this, partition the disk in the way you prefer and with the filesystem(s) you prefer. Guix provides a guide to do this here. Arch provides a guide here. Follow either guide until you've set up and mounted your partitions correctly on /mnt and continue to here. ↩︎

  3. The GUID partitioning table, not the object in a canonical Grothendieck topos. ↩︎

  4. For some information on the difficulty and status of this project, have a look at these Guix blog posts. ↩︎

  5. For a slightly partisan account of this fact, see this article and the (more balanced) lobste.rs comment chain including this one which has some Guix mentions. ↩︎