path: root/README.org

#+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

*** TODO Manual modifications to Debian's Grub

In ~/etc/default/grub~ we need to modify ~GRUB_DEFAULT=<MENU_ITEM>~

TODO ...

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~
- Modify ~/etc/default/grub~ setting ~GRUB_DEFAULT=<n>~ where ~<n>~ is the menu item number,
  starting from 0, or (preferably) the menu item name/id.

** Network configuration

Using the a snippet from ~/etc/network/interfaces~ 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

For this installation we are using ~/dev/sda~ (a 1.5T ssd which is faster then the
alternative 3.6T ssd in the server).

*** 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
  dd if=/dev/zero of=/mnt/swap/swapfile bs=1M count=32768
  chmod 600 /mnt/swap/swapfile
  chattr +C /mnt/swap/swapfile

  mkswap /mnt/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

* Bootstrap Guix

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]].