diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/initial-setup.org | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/docs/initial-setup.org b/docs/initial-setup.org new file mode 100644 index 0000000..99c61a3 --- /dev/null +++ b/docs/initial-setup.org @@ -0,0 +1,346 @@ +#+TITLE: Guix North America +#+AUTHOR: Collin J. Doering + +#+begin_abstract +This repository contains setup and management instructions for a Guix North American Build +Farm. +#+end_abstract + +* Install Guix on debian to be used to bootstrap the Guix os installation + +Optionally, the below steps can be completed within tmux or screen. Tmux was installed and +used in this case using the following. + +#+begin_src shell + sudo apt update + sudo apt install tmux + tmux +#+end_src + +Following the [[https://guix.gnu.org/manual/en/html_node/Binary-Installation.html][Binary Installation]] section from the Guix manual to install guix. + +#+begin_src shell + sudo apt install -y guix +#+end_src + +This installs the Debian's packaged version of Guix, which likely is older then what's +available upstream. As such, update our installation of Guix (following the [[https://guix.gnu.org/manual/en/html_node/Upgrading-Guix.html][Updating Guix]] +documentation specific to foreign distros'). + +#+begin_src shell + sudo -i guix pull + sudo systemctl restart guix-daemon.service +#+end_src + +* Define Guix operating-system for the machine + +See: [[file:balg02.scm][balg02.scm]] + +** Bootloader configuration + +For this installation, debian and its bootloader Grub will be left in place. Because we want +to retain Guix's interactions with Grub (eg. to allow for restoring from failed upgrades to +an earlier generation), we will have debian's Grub chainload Guix's Grub. To do so, we will +need to manually adjust Debians' Grub in order to add another menu entry, and set it as the +default menu item. + +Below is a snippet from debian's ~/etc/default/grub~. + +#+begin_src text + GRUB_DEFAULT=0 + GRUB_TIMEOUT=5 + GRUB_DISTRIBUTOR=`lsb_release -i -s 2> /dev/null || echo Debian` + GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0,115200n8" + GRUB_CMDLINE_LINUX="console=tty1 console=ttyS0,115200n8" + GRUB_TERMINAL="console serial" + GRUB_SERIAL_COMMAND="serial --speed=115200 --unit=1 --word=8 --parity=no --stop=1" +#+end_src + +From this we extract the necessary guix bootloader configuration options (for serial). + +- serial-unit :: 1 +- serial-speed :: 115200 +- terminal-inputs :: console serial +- terminal-outputs :: console serial + +*** Manual modifications to Debian's Grub +:PROPERTIES: +:CUSTOM_ID: manual_modifications_to_debians_grub +:END: + +Modify grub config on debian to add an additional (and default) option to chainload Guix +grub. + +- Add a menuitem for Guix in ~/etc/grub.d/40_custom~, where ~<EFI-UUID>~ is replaced with the + efi partition UUID. + + #+begin_src text + menuentry "Gnu Guix" { + insmod part_gpt + insmod search_fs_uuid + insmod chain + search --fs-uuid --no-floppy --set=root <EFI-UUID> + chainloader ($root)/EFI/Guix/grubx64.efi + } + #+end_src + +- Modify ~/etc/default/grub~ setting ~GRUB_DEFAULT="Gnu Guix"~ + +- Run ~grub-mkconfig -o /boot/grub/grub.cfg~ + +** Network configuration + +Using the a snippet taken from ~/etc/network/interfaces~ on the existing debian installation +(below), we can extract the necessary details to configure Guix's static-networking-service. + +- Interface :: eno8303 +- Address :: 216.37.76.55/24 +- Gateway :: 216.37.76.1 +- DNS Name Servers :: 216.37.64.2 216.37.64.3 +- DNS Search :: genenetwork.org + +#+begin_src text + # The primary network interface + allow-hotplug eno8303 + iface eno8303 inet static + address 216.37.76.55/24 + gateway 216.37.76.1 + # dns-* options are implemented by the resolvconf package, if installed + dns-nameservers 216.37.64.2 216.37.64.3 + dns-search genenetwork.org +#+end_src + +** Disk Partitioning +:PROPERTIES: +:CUSTOM_ID: disk_partitioning +:END: + +For this installation we are using ~/dev/sdb~ (a 1.5T ssd which is faster then the +alternative 3.6T ssd in the server). + +First, we require a variety of tools to setup and partition the disk destined for Guix +installation. These could be installed on debian, however an alternative approach would be to +use Guix from debian as a package manager to temporarily provide the prerequisite tools. This +can be done using the shell spawned from the following command. + +#+begin_src shell + guix shell parted btrfs-progs dosfstools +#+end_src + +*** Create disk partition table and layout + +#+begin_src bash + parted /dev/sda mklabel gpt +#+end_src + +*** Create partitions + +A simple™️ partition layout is used for this installation, consisting of an EFI ESP partition, +and the remaining disk partitions for use by btrfs, where btrfs subvolumes and a swapfile +will be used. + +#+begin_src bash + parted /dev/sda mkpart primary fat32 0% 512MiB + parted /dev/sda mkpart primary 512MiB 100% +#+end_src + +*** Create EFI partition + +#+begin_src bash + parted /dev/sda set 1 esp on + mkfs.fat -F32 /dev/sda1 +#+end_src + +*** Create btrfs 'pool' (file-system) and subvolumes + +**** Create btrfs file-system + +#+begin_src bash + mkfs.btrfs --label root /dev/sda2 +#+end_src + +**** Create btrfs subvolumes + +First mount the btrfs top-level file-system. + +#+begin_src bash + mount /dev/sda2 /mnt +#+end_src + +Then create the root subvolume, and a subvolume for swapfiles. + +#+begin_src bash + btrfs subvolume create /mnt/@ + btrfs subvolume create /mnt/@swap +#+end_src + +Unmount the top-level btrfs file-system. + +#+begin_src bash + umount /mnt +#+end_src + +Mount the root subvolume. + +#+begin_src bash + mount -o subvol=@,compress=zstd /dev/sda2 /mnt +#+end_src + +Create nested subvolumes for ~/gnu/store~ and ~/home~. + +#+begin_src bash + mkdir -p /mnt/gnu + + btrfs subvolume create /mnt/gnu/store + btrfs subvolume create /mnt/home + btrfs subvolume create /mnt/var +#+end_src + +*** Create swap + +#+begin_src bash + mkdir /mnt/swap + mount -o subvol=@swap /dev/sda2 /mnt/swap + btrfs filesystem mkswapfile --size 32g --uuid clear /swap/swapfile +#+end_src + +*** Prepare ~/mnt~ for Guix installation + +Create ~/boot/efi~ directory for UEFI boot and mount the ESP partition there. + +#+begin_src bash + mkdir -p /mnt/boot/efi + mount /dev/sda1 /mnt/boot/efi +#+end_src + +Both root and swap are already mounted and ready due to earlier steps. + +** Testing + +To test the configuration in a vm before deployment, the following can be used. + +#+begin_src shell + $(guix time-machine -C channels.scm -- system vm -e '(@ (guix-na config balg02) %system)') -m 2G -smp 2 -nic user,model=virtio-net-pci +#+end_src + +** Manual Testing of bootstrapping Guix from a Debian VM + +To correctly test this deployment, a environment that mimics bal02g should be used. The +closest to this is a VM with debian installed, with an additional virtual disk to bootstrap +guix onto. This will enable validating bootloader changes required to chainboot Guix's Grub. + +This testing could be automated, but was done manually as we do not expect to have to +bootstrap a system like this often. + +*** Setup Debian VM + +1. Using ~qemu~, ~libvirt~, ~virtualbox~, etc.. create a VM that boots using UEFI firmware. + + 1. Create an additional virtual disk that will be used to bootstrap Guix onto from Debian. + This disk should be ~>20GiB~. + + 2. Ensure that there is a serial device attached to the VM. + +2. Install Debian 12 on the VM created during step 1 (this can be a minimal server + installation, no desktop, etc..). + + 1. It's worth noting that for some reason debian didn't setup a efi boot + entry for some reason. Not sure why. To create one I used: + + #+begin_src shell + efibootmgr --create --disk /dev/vda -p 1 -L "Debian" -l "\EFI\debian\grub64.efi" + #+end_src + + After which I would have adjusted the boot order with: + + #+begin_src shell + efibootmgr -o X,Y,... + #+end_src + + However, in my case it was not needed as the boot order had debian first. + +3. Reboot VM; further configure Debian. + + 1. Enable serial for debian grub + + Modify ~/etc/default/grub~, adjusting ~GRUB_TERMINAL~ and ~GRUB_CMDLINE_LINUX_DEFAULT~ as + follows. + + #+begin_src text + GRUB_TERMINAL="console serial" + GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0,115200n8" + #+end_src + + 2. Enable getty over serial + + #+begin_src shell + systemctl enable getty@ttyS0.service + systemctl start getty@ttyS0.service + #+end_src + +*** Test Bootstrapping Gnu Guix from Debian + +With the Debian VM setup, we can now apply the documented bootstrapping steps. + +1. [[#disk_partitioning][Disk Partitioning]], but with disks adjusted to match the testing VM. +2. [[#bootstrap_guix][Bootstrap Guix]], ensure ~<EFI-UUID>~ matches the VM efi partition used for Guix. +3. [[#manual_modifications_to_debians_grub][Manual modifications to Debian's Grub]], again ensuring ~<EFI-UUID>~ matches the VM efi + partition used for Guix. +4. Reboot + +Following rebooting the VM, its expected that: + +- Debian Grub boots first, has "Gnu Guix" as its default selected option, which boots Guixs' + Grub. +- Serial access works for: + - Debian and Guix Grub/s + - Debian and Guix linux console + +As this testing is occurring in a VM, its worth noting things that are NOT expected to to be +testable. + +- The network interfaces are not going to match what is on balg02, so its expected that the + networking service will not be able to start. + +* Bootstrap Guix +:PROPERTIES: +:CUSTOM_ID: bootstrap_guix +:END: + +Using Guix on debian, bootstrap the machine using the configuration in [[*Define Guix operating-system for the machine][Define Guix +operating-system for the machine]]. + +** Configure Guix Channels + +First, fetch the most recent channel file from the target machine. + +#+begin_src shell + curl -O https://git.rekahsoft.ca/rekahsoft/guix-north-america/raw/branch/master/channels.scm +#+end_src + +** Create and Bootstrap System + +Create a ~bootstrap.scm~ file like below, but where ~<EFI-UUID>~ is replaced with the efi +partition UUID. + +#+begin_src scheme + ((@ (guix-na config balg02) balg02) "<EFI-UUID>") +#+end_src + +Use ~guix system init ...~ to instantiate the system, but using guix time-machine to use +pinned dependencies. + +#+begin_src shell + guix time-machine -C channels.scm -- system init bootstrap.scm /mnt +#+end_src + +** Post Boostrapping + +After guix has been bootstrapped, its useful to do an initial ~guix pull~ using the same +channels that were used during bootstrapping. + +#+begin_src shell + guix pull -C /run/current-system/channels.scm +#+end_src + +To ensure your shell refers to the correct guix after its been updated, run ~hash guix~. |