System Crafters

Installing Guix as a Complete GNU/Linux System

Watch the video on YouTube!

The time has come!

Today we're finally going to learn how to install GNU Guix as a full Linux distribution. My goal here is to make the installation process as smooth as possible for first-time Guix installers, particularly when you're installing on a machine that has hardware which isn't supported by the Linux kernel that comes with the official Guix installation image.

By the end of this video, we'll have Guix installed with the GNOME desktop environment and working WiFi, and I'll also show you how to update your system so that you can keep things up to date!

NOTE: If you're watching this video a month or later after it has been released, please check the show notes linked in the description just in case any corrections are needed for the steps we take today! Guix is constantly changing so there's a chance the instructions will be updated over time.

Assumptions

I'm going to make a few assumptions in this video:

  • You haven't installed GNU Guix before, but you've probably installed Linux before
  • You don't have a pre-existing Guix system configuration
  • You are installing Guix on a machine that requires nonfree firmware and drivers, most likely a laptop that only has WiFi for Internet access

I want to make sure I point out that this is a customized Guix installation image, so some of the steps I tell you to follow here don't apply to the installer you will find on the main Guix website!

I'll point out any deviations from the official installer when we reach them.

Preparing the installer

First of all, you'll need to download the .iso file for the latest release on this GitHub repository:

https://github.com/SystemCrafters/guix-installer/releases/latest

I'll be using this release of the installer today but it's probably better to try the latest version first and then use the one I'm using if you run into any trouble with the newest one.

You'll then need to burn the ISO onto either a DVD or USB stick. You can follow the instructions in the GNU Guix manual for how to burn the ISO once you've downloaded it (just don't download the ISO that they recommend!)

GNU Guix Manual: USB Stick and DVD Installation

An example:


$ sudo dd if=guix-installer-<date number>.iso of=/dev/sdX status=progress
$ sync

Make sure to update the .iso path and the target drive path in the command above!

If you're on Windows, the program Rufus can be helpful for putting the image on a USB stick:

https://rufus.ie/en_US/

Prepare your hard drive

The last prerequisite is to make sure you've prepared your hard drive and partitions before you start the installation process.

First of all, back up your important files, just in case! If you accidentally delete an important partition while going through the Guix process, you'll want to have that backup around.

You'll also need to make sure you have enough free space to create a new partition for Guix. You have two options:

  • Let the Guix installer delete all your partitions and create from scratch (slightly risky, but OK if you don't use this computer for anything else)
  • Resize the partition of your main operating system to make space for Guix. If you're using Windows, you can launch the "Disk Manager" application, right click on your Windows partition, and click "Shrink Volume" to make space for a new partition.

Booting the Installer

Let's boot with the installation media! When you plug in the USB stick (or DVD) you may need to press a key to get to the boot menu and select the device with the installer on it.

Once booting completes, you'll see a blue and red screen with a menu. You'll first need to select the language and territory for the installation process.

You will then be presented with a choice to use the "graphical" installer or the "shell-based" process. We're going to pick the "graphical" installation process because we don't have an existing Guix system configuration.

If you have an existing configuration, I still recommend starting with the graphical installer because it can help you connect to WiFi a little more easily than on the console!

Using the graphical installer

We're now going to proceed through the installation "wizard" which will ask us to fill in some information about the system we will be installing.

Choosing basic system details

The first question is to choose the appropriate timezone for where you are in the world. You will then be asked about the keyboard layout you use. There are lots of options for keyboard layouts, so take a moment to look through them!

Next you will be asked for the hostname of the system. Enter something fun here!

Network setup

If you're installing on a laptop or a device with a WiFi adapter, select "WiFi" in the list and press Enter. It will try to power on your WiFi antenna to find available access points. If for some reason no access points are returned the first time, press Tab to select "Scan" and then Enter and then you may get a list of results.

Select the network you want to connect to and enter the password in the next dialog that appears. Once you authenticate, the installer will try to access the Internet. I've seen this dialog report that the Internet isn't accessible, so just select the same network again and it might work the second try!

Enable substitute servers

Now you'll be asked if you want to turn on substitute server discovery. I highly recommend choosing "Enable" here or you will be building the source for all your packages from scratch!

Choose a root password

Enter a root password for the machine in the next prompt. It doesn't matter what you enter here because we won't finish installation using the graphical installer!

Create a user

On the "User creation" dialog, press Enter to raise the dialog to add a user.

Enter the name and details for the user (leave the password field blank!) then use TAB to reach the OK button and press Enter.

The cursor should now be on the OK button, so if you don't need to add more users, just press Enter!

Choosing a desktop environment

Here's the fun part! At this point you can choose what your initial desktop environment will be. You can also select multiple environments if you want to try different ones in your new system!

I know that since we're on the System Crafters channel that "Emacs EXWM" option is going to be tempting, but I recommend picking a more conventional option in addition to that you have an easier time setting things up after installation.

Use the arrow keys to select "Emacs EXWM" and press Enter, then use TAB and Enter to confirm the dialog.

Service selection

In the next screen you can choose services to add to your system. The NSS certificate service will be selected by default (don't uncheck it!) and you can add either of the following services by selecting them with the arrow keys and pressing Enter:

  • OpenSSH: Enables SSH access to this machine
  • Tor: Enables you to access the Tor network

Once you've made your selections, use Tab and Enter to choose OK.

Partitioning the disk

On this screen, we can choose how we want to partition the disks in our system. We can either have the installer guide us through the partitioning process or do the work manually.

Partitioning is probably the trickiest part of the installation if you already have another operating system installed that you need to use (like Windows)!

Guided Partitioning

We'll select the option "Guided - using the entire disk with encryption" with the Enter key to install Guix into an encrypted file system. In the next screen you'll be asked which disk to partition. Select that disk with the arrow keys and press Enter to continue.

You'll also be asked for the partition table type and the options presented will depend on the type of system you are installing to. We will chose "gpt" here and press Enter.

Now you'll be asked if you want a separate home partition. This can be useful if you'd like to reinstall your Guix system at some point later, but due to the nature of Guix you should never have to reinstall! For the sake of simplicity we will choose "Everything is one partition" and press Enter.

We will now be asked to confirm the proposed partitioning. Verify that everything looks good and then use Tab then Enter to select "OK" to continue.

Since we chose an encrypted volume, we'll now be asked for the password. Choose something relatively strong but memorable for this! A series of words of 20 characters or longer is usually sufficient for this purpose. After you enter the password and choose OK you will be asked to confirm the password one more time.

Now we will be asked to continue with formatting the disk. Press Enter to continue if everything looks good! The partitions of the disk will now be formatted and prepared for installation.

Manual Partitioning

If you select the "Manual" option in this screen, you will be shown a list of existing partitions on your hard drive(s).

If you've already made space for Guix on your drive, you may see an entry in the list that says "Free space". If you select that item and press Enter it will allow you to create a new partition! You can leave the type and size settings as they are and enable encryption if desired. You should also set the mount point to / for the root partition!

You can also delete a selected partition to make space using the Delete key!

If you want to reuse an existing partition, select it using the arrow keys and press Enter. You can change the partition type, select it for formatting, and enable encryption if you want.

No matter what you do here, the important thing is to make sure you've set the mount point of / for the partition where you want to install Guix!

Editing the generated configuration

We'll now be shown a screen with the final configuration that was generated for our system install. This is actually the last page we will use on the graphical installer! We'll use this generated configuration to finish the installation process manually.

Since we want to install the full Linux kernel, we need to make some tweaks to the config before continuing. Instead of choosing "OK" or "Edit" here, we will actually switch to a different TTY using Ctrl+Alt+F3. Once you switch to this TTY, press Enter to get to the shell.

Now we can edit the generated configuration file to add the parts we need to install with the full Linux kernel. Open up the file /mnt/etc/config.scm in either Emacs or Vim (both are installed already). I'll open the file in Emacs:


emacs /mnt/etc/config.scm

The first edit will be on the first use-modules line (line 4), replace it with the following:


(use-modules (gnu) (nongnu packages linux))

The next section of the file (line 7) starts with (operating-system, we need to insert a couple lines just after that line:


(kernel linux)
(firmware (list linux-firmware))  ; Don't forget the second parentheses at the end!

These two lines will set up the full Linux kernel and firmware in the installed system.

That's it! Save the file (C-x C-s in Emacs) and then exit (C-x C-c).

Installing the system

Now we can start the system installation!

First we need to set up the Guix build daemon to target the new system partition by running this command:


herd start cow-store /mnt

We also want to save the channel configuration that was used to produce the installer image onto our new machine, so we will copy it over now:


cp /etc/channels.scm /mnt/etc/
chmod +w /mnt/etc/channels.scm

The following command will install your system configuration using the included channels.scm file so that you get both the main Guix channel and the Nonguix channel which contains the full Linux kernel:


guix time-machine -C /mnt/etc/channels.scm -- system init /mnt/etc/config.scm /mnt

Installation can take a while here because many packages will need to be downloaded for the base system install. If the installation process ever seems to hang, you can just use Ctrl+C to cancel it and then run the same guix time-machine command again to continue!

Once everything is done, type the following command to restart the computer:


reboot

While the reboot is going on, remove the installation media so that it doesn't try to boot the installer again!

Booting your new system

Your new system should be installed now! If you created encrypted partitions, the first thing you will have to do is type in your passphrase before you will reach the Guix boot screen. It will take a few seconds before booting proceeds after you enter the password.

Now you will get the Guix boot screen and can press Enter to proceed. You will receive a second prompt for your passphrase if the root partition is encrypted!

Once booting completes you will be at the login screen for your desktop environment. You can't log in yet though because no password has been set!

Use Ctrl+Alt+F5 to switch to another virtual terminal and log in as root. Now you need to set passwords for both root and the user(s) you created!


# Change the root password
passwd

# Change your user account password
passwd daviwil

Once you've changed the passwords, type exit to log out from the root shell and then press Ctrl+Alt+F7 to go back to the desktop environment log in screen.

You can now log in successfully!

Saving your configuration

Now that we've booted into our new system and logged in, we need to copy over the channel and configuration files that we used during installation. This is important, these files won't exist after we update the system!

You can save these files with the following commands:


mkdir -p ~/.config/guix
cd ~/.config/guix
cp /etc/channels.scm .
cp /etc/config.scm ./system.scm
chmod +w channels.scm

Next we need to edit the channels.scm file so that we're not pinned to specific commits anymore. Open up ~/.config/guix/channels.scm in Emacs or Vim and remove the lines containing (commit ...).

The file should now look like this:


(list (channel
        (name 'guix)
        (url "https://git.savannah.gnu.org/git/guix.git")
        (introduction
          (make-channel-introduction
            "9edb3f66fd807b096b48283debdcddccfea34bad"
            (openpgp-fingerprint
              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"))))
      (channel
        (name 'nonguix)
        (url "https://gitlab.com/nonguix/nonguix")
        (introduction
          (make-channel-introduction
            "897c1a470da759236cc11798f4e0a5f7d4d59fbc"
            (openpgp-fingerprint
              "2A39 3FFF 68F4 EF7A 3D29  12AF 6F51 20A0 22FB B2D5")))))

Updating the system

One last thing you'll want to know how to do is update your system! Before we can do that, though, make sure to connect to WiFi!

You can update your Guix system by running the following commands:


guix pull
sudo -E guix system reconfigure ~/.config/guix/system.scm

This may take some time depending on how many changes were made to Guix since your installer image was generated. Once the guix system reconfigure command is done, you can reboot to use your updated system!

Usage tips

  1. Don't use your system.scm to install packages you want to use day to day, use guix install instead!
  2. You don't really need to update the full system very often (especially to avoid kernel recompiles)

Watch my video Everyday Package Management with GNU Guix to learn how you can use Guix to manage user-level packages!

Becoming acclimated with the Guix system takes time, so be patient! The usage patterns for Guix are very different than other Linux distributions you may be familiar with.

Have fun with your new Guix system!

What's next?

I'm planning to make more videos to show you how to use Guix as your daily driver Linux distribution! Here are some topics we will cover:

  • Improving your system configuration to remove unneeded packages
  • Sharing a base system configuration between multiple machines
  • How to manage user-level packages and profiles

In the meantime, you can learn more helpful things from the GNU Guix Manual and also in the System Crafters Discord or IRC chat where you can ask questions share tips!

I also recommend checking out the Guix section of the System Crafters Wiki to find more tips about how to use the system. Please feel free to contribute if you learn anything useful!