Problems in the Gentoo Installation Guide^

When the date of a vacation creeps close there is always a slough of minor tasks that you want to check off before climbing into the car and making way. For my most recent trip, it was to get my laptop up and running with Linux so that I would have something to tinker on in the hotel between events.

Over the past year I have spent a lot of time surveying the various minimalist distributions of Linux available. The project absolutely requires a minimalist distribution. When you finish the install and boot up, you should have a black screen with a login prompt. If the installer configures a desktop environment or display manager of any sort, it’s crossed off the list as unsuitable.

Recently, the choice has narrowed to Arch Linux and Gentoo and while I’ve used Arch for a number of years and seen the charms and the warts, lately I’ve begun to lean heavily towards the idea of Gentoo.

So, that was how I spent the evening before my trip.

Installation Failures^

I should prefix this point with a note that I’m no greenhorn in this space. Though in recent years, a job has pushed me onto a MacBook, Linux has been my primary operating system and often my daily driver for the past fifteen years and I was using it on and off long before that.

As is the case with most of us, I spent several years in the distro hop. Running the gauntlet from Ubuntu and Fedora through Debian and CentOS, on down to Arch Linux, NixOS, and others. I was systems punk years before anyone thought technology was cool enough to be punk.

This is all to say, I know how to install Linux and I know what a new installation needs done without some polished opinionated corporate-friendly installer automagically doing all of the things for me. Which is good, because Gentoo doesn’t believe in automagic.

Last Tuesday was the fifth time I installed Gentoo. It was the third time I installed it on my laptop. Twice before I had installed it on my desktop. And, altogether, it was the fourth time I reached the end of the installation instruction and shut down to find a system that would not boot.

Diagnosis^

Being the day before a vacation, I didn’t have time for lengthy diagnostics. I packed an old work MacBook and am drafting this blog from there while I build some hypotheseis on the probable cause.

  • I did not set the appropriate flags on the /efi partition to indicate its purpose.

  • I did not properly configure GRUB to handle boot selections.

  • I made some error when setting up encryption, so it’s not attempt to decrypt the root file system before it starts.

These are just guesses. A large portion of the Gentoo installation guide lies outside of my experience. So, it’s entirely possible the error derives from some misstep in that realm.

In attempting to narrow the causes and decide what I should do when I get home, I started rereading the installation guide, looking for where I went wrong… which led me into consideration of how I went wrong.

Analysis^

When I booted up the live environment, which appears to be a recent release of KDE, I tiled the windows so that I had the terminal on one side of the screen and on the other a web browser open to the Gentoo AMD64 Handbook.

This would appear to be the recommended approach: I worked through the manual, making configuration decisions as I went to set up the disk, stage the system, configure the network, build the kernel as well as all the basic programs I would need to start work setting up X and DWM after a successful boot—which as mentioned, didn’t happen.

Somewhere along the way I had made a mistake or I missed a step that would give me the necessary configuration to boot the system. I was finding it very difficult to say with any clarity where the mistake had occurred beyond a few vague points.

But, the more I read the more I wondered that I hadn’t made more mistakes along the way. The style of the Handbook jumbles together a lot of information and in the later pages I was scratching my head trying to determine whether the section was relevant to what I did or related to some alternate installation path.

The Principle of Choice^

Most distributions of Linux have opinions. The developers consider the technology and what they are able to distribute and maintain and that informs what is available to you the user.

Some distros, like Ubuntu and Fedora, make a lot of decisions on your behalf: like whether you want to use a display server or what desktop environment is best for you. Some, like Arch, limit themselves to picking the init systems and a few other low level things that most people don’t have time to be bothered about. While this is good when you need to get up and go fast, it comes at the cost of choice.

Gentoo treats choice as a design principle. They largely expect you the user to form your own opinions about what is best for your workflow and hardware. Which is very empowering, even if it means you also have to take responsibility for your choices.

The Problem of Choice^

Gentoo begins in the principle of choice. There is no single path you work down. You can structure your disk partitions however way suits your needs. You are free to use any file system that the kernel supports. You can run systemd or OpenRC. You can decide between several kernel options and compile it the way you want.

This principle is of significant value to me and is one of the primary reasons why I decided to explore Gentoo. But, from the perspective of a technical writer I’ll note that it does come with a glaring problem: at each stage of the installation process they have to document the choices you can make, even if some of the choices are no longer possible given earlier decisions. You have to keep track of where you are the process and what you’ve done. And, that’s not necessarily easy given that an installation may stretch over several hours or days.

There is plenty opportunity in this process for you to make mistakes or forget where you’re at or what you’ve done and when then happens you end up like me with a system that won’t start.

Paradigmatic Considerations^

How I found myself in this state comes down to a skills issue. I am very new to Gentoo and the particulars of the Gentoo installation are pushing me into unfamiliar territory. Problems like this are good because they provide opportunities for significant learning and growth.

To ensure this growth, I need to go through the installation process several times and reach successful conclusions. It should be a simple working through the steps and doing what needs to be done to produce a system in the correct state.

That means an intensive reading of the installation guide in order to understand each choice it presents, what it means to make that choice, and how that choice affects the options available later in the guide.

These needs got me thinking about information architecture, which in turn led to a consideration of how Gentoo structures its choices and whether they’re using the best approach.

Docs in the Print Paradigm^

The Installation Guide of the Gentoo AMD64 Handbook is composed of eleven pages, which the reader is expected to work through in order to build out a minimalist system.

digraph Print{ rankdir=TB; node[shape=box, fontsize=10]; about[label=< <b>0. About the Gentoo Linux Installation</b><br/> User introduced to Gentoo with emphasis <br/> on choice opennness, and user empowerment <br/> as well as to the structure of the guide.<br/> >]; medium[label=< <b>1. Choosing the Gentoo Installation Medium</b><br/> Description of the available installation<br/> media, with some consideration on what to<br/> download and how to write it to USB.<br/> >]; net[label=< <b>2. Configure the Network</b><br/> Network configuration, wireless setup<br/> application-specific configurations, basics<br/> of the internet, manual network setup.<br/> >]; disk[label=< <b>3. Prepare the Disks</b><br/> Introduction covers block devices and<br/> the design of partition schemes. Details <br/> partitioning with GPT and MBR as well as<br/> the creation of file systems on each<br/> partition and mounting them.<br/> >]; install[label=< <b>4. Install the Gentoo Installation Files</b><br/> Choose a stage file, systemd versus OpenRC,<br/> download and installation of the stage file<br/> on the root file system, and the configuration<br/> of the various compiler options.<br/> >]; base[label=< <b>5. Install the Gentoo Base System</b><br/> Chroots user into their system to configure<br/> portage, USE variables, and localization.<br/> >]; kernel[label=< <b>6. Configure the Kernel</b><br/> Installs the firmware, installkernel,<br/> then documents the kernels available<br/> in Gentoo and how to build them.<br/> >]; sys[label=< <b>7. Configure the System</b><br/> Covers fstab creation and the<br/> configuration of networking and<br/> system information.<br/> >] tools[label=< <b>8. Install System Tools</b><br/> Configures the system logger, the cron<br/> daemon for systemd and OpenRC, file<br/> indexing and shell completion, tiem<br/> synchronization for systemd and OpenRC,<br/> as well as file system and networking tools<br/> >]; boot[label=< <b>9. Configure the Bootloader</b><br/> Describes the available bootloaders and<br/> how to configure GRUB, systemd-boot, the EFI<br/> stub and other alternatives.<br/> >]; final[label=< <b>10. Finalize Installation</b><br/> Covers user administration, disk cleanup,<br/> and where to go from here.<br/> >]; { rank=same; about; kernel;} about -> medium -> net -> disk -> install -> base; kernel -> sys -> tools -> boot -> final; base -> kernel; }

This approach should be very familiar to anyone who has spent a lot of time reading tech publications in print, such as those of O’Reilly Media.

There are stages of work such as configuring the kernel or installing the base system and then a series of options covered under each. But, just glancing at the diagram you may notice a problem.

When the user downloads the installation files in step 4 they have to choose between systemd and OpenRC, but in steps 7, 8, and 9 they are given additional choices whose availability depends on systemd or OpenRC.

This clutters the process and forces the user to spend time building a deep understanding of things they’ve already ruled out as possibilities.

Docs in the Web Paradigm^

While the print paradigm works well for a book, it doesn’t really take full advantage of single-source content and hypertext. An alternative would be the web paradigm, where we can ensure that the choices users make at one stage decide what options are presented to them at later stages.

Rather than breaking out the above diagram in its full complexity, consider steps 3 and 4 within the context of the web paradigm:

digraph web { node[shape=box, fontsize=10]; start[label="...", shape=none]; intro[label=< <b>3. Prepare Disks</b><br/> Introduction to the disk preparation<br/> process and what the user can expect.<br/> >]; start -> intro; gpt[label=< <b>GPT Partitons</b><br/> Documents the creation of GPT<br/> partition tables for UEFI.<br/> >]; mbr[label=< <b>MBR Partitions</b><br/> Documents the creation of MBR<br/> partition tables for BIOS.<br/> >]; intro -> gpt; intro -> mbr; gpt_fs[label=< <b>File System Creation (GPT)</b><br/> Guide to creating file systems.<br/> >]; mbr_fs[label=< <b>File System Creation (MBR)</b><br/> Guide to creating file systems.<br/> >]; gpt -> gpt_fs; mbr -> mbr_fs; gpt_install[label=< <b>4a. Installation Files (GPT)</b><br/> Introduction to install files,<br/> introduces reader to systemd<br/> and OpenRC as init options<br/> >]; mbr_install[label=< <b>4b. Installation Files (MBR)</b><br/> Introduction to install files,<br/> introduces reader to systemd<br/> and OpenRC as init options<br/> >]; gpt_fs -> gpt_install; mbr_fs -> mbr_install; gpt_systemd[label=< <b>systemd Installation (GPT)</b><br/> Guide to installing systemd files<br/> >]; gpt_openrc[label=< <b>OpenRC Installation (GPT)</b><br/> Guide to installing OpenRC files<br/> >]; mbr_openrc[label="...", shape=none]; gpt_install -> gpt_systemd; gpt_install -> gpt_openrc; mbr_install -> mbr_openrc; elip_openrc[label="...", shape=none]; elip_systemd[label="...", shape=none]; gpt_openrc -> elip_openrc; gpt_systemd -> elip_systemd; }

While this process does echo the eleven steps of the Gentoo Handbook, it doesn’t replicate the link pattern.

Instead of a single page for each step, an individual step is broken down into a set of pages. It starts with a concept page that outlines the choice you need to make at this stage. Then, your choice links you to a task page that describes how to actualize that choice. The link at the bottom of the task page does not go to a top level concept page for the next step: instead it goes to a branched concept page that assumes the earlier choice on virtue of the link path.

This framework means a lot of repeated content, so it usually depends on a build system like Sphinx that allows you to customize content drawn in from a single source.

Knowledge Base^

Many people who find themselves where I am will either throw up their hands and use something else or meticulously work through the Handbook until they find the right path for them. What sets me apart is that I not only have a Blog but also a Knowledge Base.

What this means is that instead of just working out things for myself I can also develop content that might benefit others—where others includes future me.

Goal then is to build out a shortened version of the Gentoo installation guide according to the web paradigm. My goal is not to explain things in the context of Gentoo so much as to explain the process in the context of general knowledge to hopefully produce something that others find useful and/or interesting.

For more information, see Gentoo in the KB.

Book Metrics Knowledge Base