Advanced installation guides

[bobertlo]

I plan to start working on this, but am looking for input on how to handle this. There are SO many installation guides on the wiki, with SO much duplication. My proposal is to create a fleshed out "advanced installation" guide, along with other specific guides, which will only offer differences from the main guide.

Advanced Installation Guide

This guide will detail "manual" installation from start to finish, more in the style of the "live image installer" guide. This guide would be formal and fleshed out, mentioning alternatives to the given procedures. Topics would include:

• preparing and mounting partitions
• manually installing a system with xbps-install
• basic configuration of the system afterwards, up to the point of being able to use the rest of the manual.
• bootloader: only cover "regular" bootloader in this guide for BIOS/UEFI systems

Alternative Installation Guides

These guides will in every instance possible just reference the "main" advanced installation guide, and not duplicate those steps. They will only present changes to that procedure, and enough context for the user to be able to follow what is happening. Initial topics could include:

• encrypted disks
• raspberry pi
• other embedded systems
• dual booting
• alternative bootloaders
• etc

Proposed Process

1. Write a minimal installation guide. It should cover anything needed to go from nothing to a working system, but not try to cram everything from the wiki into it. A minimum viable product to manually install a system.
2. Write Alternative Guides for specific use cases and hardware, referencing them as needed from the main guide.
3. ???
4. Profit

[bobertlo]

@the-maldridge @nilium any opinions on this? I want to make sure we're on the same page before I start writing this. I'd like to start the main guide and possibly recruit others to write other sections as needed/wanted, because that's a lot of work and I don't want to write about things I'm not familiar with.

[Duncaen]

I think the if you can split it into nice logical steps like "Disk setup", with separate pages where you can go in depth into encrypted disks etc you can avoid having "alternative" guides.

The raspberrypi and other embedded systems are too different to setup and basically just hey put this image here and boot, I think they are more like using the installer script and not part of the "Advanced installation" unless they are setup similiar by bootstrapping using xbps-install.

[bobertlo]

Thanks @Duncaen those are good points! Put like that I agree. Since the images are not the same procedure, they should be handled separately, and this might remove the need for different sections.

I'll try writing up the advanced guide and see how disk encryption does or does not fit in that guide.

Also, Im not sure what other things there are to cover within the scope of this document.

[nilium]

Only thing I'd add is that PXE / iPXE booting is probably worth covering at some level. I've at least used iPXE booting for my build server, and documenting that would be probably only a few paragraphs because of how simple it is. Other than that, I don't think I've done any installations that'd fall under this category, so I don't have much of an opinion (edit: except that I don't know if Raspberry Pi counts as advanced).

[the-maldridge]

I also vote for reducing if possible the number of alternative guides. It would be much better imho to have a choose-your-own-adventure flow to it rather than a bunch of guides that are running on rails. To cover @nilium's suggestion maybe you could have a section on "booting the installer" where you could talk about dd or its windows equivalent, iPXE, regular PXE, and whatever other exotic methods people have used.

[pltrz]

I also think it would work better broken up. Choose-your-own-adventure sounds really ideal.

One possibility for this is to have something like a very high level overview of an installation, with each step mentioning some of the possible options (LUKS, LVM, filesystems, PXE, etc) and with each of those having it's own page with the necessary info (in the same consice style as all the existing pages). Then, users can pick which ones are relevant to them, and find each topic in it's own page.

Of course, in terms of a real installation, this might mean the reader should be expected have thought through a bit of what they're doing since they wouldn't be following an Arch Wiki type installation guide, where they would have had each step they must do put in front of them. They will have to think for themselves a bit more, but I believe this is for the better in terms of [1] organization of information in void-docs and [2] we already have an installer script for those who don't know what they're doing, so having a "use commands X, Y, Z to get a working install" guide won't add anything.

[bobertlo]

To be clear, I did mean for the "Advanced Guide" to be presented in logical sections. Thanks for all the input. I'll try to start work on this tomorrow.

[pltrz]

@bobertlo have you started on this? If you haven't, I can and I can open up a WIP pull request

[bobertlo]

@pltrz I hadn't had time yet. You're welcome to try to start one.

[ralphee]

As an initial draft layout :

PRE-INSTALLATION

3.3.0 Verify Signature 3.3.1 Boot Live Environment 3.3.2 Shell Choices 3.3.3 Keyboard Layout 3.3.4 Verify Boot Mode 3.3.5 Internet Connection 3.3.6 Partition Disks 3.3.6a lvm 3.3.6b luks 3.3.6c mdraid 3.3.6d Example Layouts 3.3.7 Format Partitions 3.3.8 Mount File System

INSTALLATION

3.3.9 Selecting Mirrors 3.3.10 nstall Packages / Templates 3.3.11 Chroot 3.3.12 Root / User Password 3.3.13 Fstab 3.3.14 Localization 3.3.15 Time Zone 3.3.16 Network Configuration 3.3.17 Bootloader 3.3.18 rc.conf

Reboot

Post-Installation

if general methodology / flow is ok I can slowly start with each sub-section

[bobertlo]

@ralphee : This looks like a reasonable start to me. Some of the things could be in a different order, but that's not something to worry about now.

Quickly looking:

• I don't think shell choices is needed, that is covered elsewhere and not really important in the installation process.
• Some of the things like LVM, luks, raid, example layouts, etc, might be moved into a third section (advanced configuration or something) just to make this more clear. I would like anything on these topics to be in one place and presented as a set of changes necessary on the base methods already laid out in the pre-installation and installation sections. I just don't want all of these things mixed in on a basic manual installation guide.
• If all these sections are moved out, is the pre-installation section really necessary? Isn't creating partitions and such part of the installation process? I'm not sure just asking.

I think this is a good plan. Try to start out as minimally as possible. Ideally we would get a streamlined version commited and go from there. Ideally some of the content (like verifying images) would be moved from the Live Install guides to a more general section here also.

[ericonr]

Hey there! The guides for rootfs installation for the ready to boot ARM images are currently located in the wiki, as well (as I mentioned here https://github.com/void-linux/void-linux.github.io/issues/88 ). I'd definitely be interested in trying to write a general guide for the ARM boards (even if my experience is mostly with RaspPis), and then only mention the platform specific stuff, without duplicated information. For that, though, I'd need some guidance. Where could such a page fit in the current index structure? And who could help me with curating the ARM board information from the wiki? I can test what's relevant on a Pi Zero, but I don't currently have access to anything else.

[ericonr]

alternative bootloaders

@bobertlo what kind of bootloaders are you thinking? At least for rEFInd, it worked exactly the same way it does on Manjaro, so I don't think it requires its own page (unless you wan to document its existence, which is a fair point). Regarding Gummiboot I don't know how much it differs from systemd-boot, so perhaps it requires some documentation. From my experience, at least, the EFI stubs from both work exactly the same.

[MatthiasGrandl]

@ericonr Maybe a plain EFISTUB boot? This certainly shouldn't be recommended for most users, but if you don't want to boot anything but Void, this is the most minimal approach to booting I know of: https://wiki.archlinux.org/index.php/EFISTUB

[bobertlo]

@ericonr I think grub with BIOS and UEFI would be a good start :)

I'm not sure bootloaders need much void specific setup otherwise. I would guess documentation that would be considered useful would be for other platforms like ARM, but I am not saying specifically we would not add anything else.

[jeffayle]

It's been a while since anyone has said they're working on this, so I'll add my name to that list.

Here is my work in progress: https://gist.github.com/jeffayle/e8d5565301b549383678f747f3540d8a

notes:

• I relied heavily on a handful of guides from the wiki. I'd like to make sure the original authors are credited somewhere
• it is written in markdown but has not been put through the void-doc formatter
• it is written in the style of basic guide plus supplements for advanced setups. this might be confusing if you're trying to follow more than one supplement at the same time. I don't think this could be made into a choose-your-own-adventure nicely with the current documentation system because some supplements need to be inserted at more than one place. An idea I came up with is to write all the supplements interspersed into the main guide, then present the reader with a bunch of check boxes that control which sections of the guide are visible. This should be doable with straight CSS, but would cause problems for browsers like elinks and dillo.
• Every paragraph beginning with TODO will be removed from the guide. These are areas that I either need feedback on or to do more research into.
• This guide is only for PC architecture. I didn't think it was, but at some point yesterday I realized that I have no idea how my raspberry pi boots. There are no guides on the wiki for doing a chroot install on any ARM systems. I am not sure right now how this will fit into the guide, but it will probably be a supplement.
• UEFI & BIOS booting are both included in the main guide. I think the if/thens this puts into the guide is a bit confusing given the basics/supplements structure of the guide (this was the reason musl I wrote musl into a supplement). I'd like to move BIOS booting into its own supplement, but I'm not sure.
• FWIW, I'd like this guide to include something about non-grub bootloaders. I'm not sure it needs to include details on how to set anything up, but at least explaining what other options are out there and why you might want to use them.

I'd appreciate any feedback--do the instructions make sense, is there anything I've missed? If this looks like a viable start, I'll fork the repository and continue work on the guide in there.

[bobertlo]

RE: UEFI/BIOS. I think UEFI would be the item belonging in its own supplement if that was found necessary. I really don't think it's that confusing. In the end the only thing we can't do is duplicate the entire guide just for the small difference in partitioning and required mounting of that extra partition.

A lot of the bootloader and partitioning issues are covered in the main guide also. I wonder if we could just have a bootloader/partition notes section that everything can point to for an overview, and then just have a base set of example commands in the actual guides.

[bobertlo]

@jeffayle it would be good to think of this as a collection of guides, vs a monolithic document. I would encourage you to open a pull request if you would like to pursue a guide and recieve feedback, but please consider choosing a tight scope like chroot install, or a partitioning guide.

I really think we would be better off doing this in small pieces, and de duplicate other sections as we go. Modifying other sections can be done as a separate step also.

There are a lot of questions in your gist that are good, but should definitely all be addressed at once. Many of those could be opened as single issues for discussion.

[jeffayle]

@bobertlo do you disagree with the style of basic chroot install guide + supplements? My intention wasn't to create a monolithic guide, although I do see how I may have presented what I've written so far as a monolithic document.

Right now, I think what makes most sense for me to do is to strip out all my "advanced" sections and get the problems with the basic chroot guide ironed out so that we have a solid chroot installation guide in the docs that can be built upon in guides for more advanced setups.

A lot of the bootloader and partitioning issues are covered in the main guide also. I wonder if we could just have a bootloader/partition notes section that everything can point to for an overview, and then just have a base set of example commands in the actual guides.

I agree with this completely, and that's why the sections I wrote on partitioning and formatting drives are pretty sparse. I'll be sure to go through those docs and make sure that I'm pointing to those sections instead of duplicating anything.

[bobertlo]

@jeffayle Okay nope i don't disagree. I didn't peruse your gist, just skimmed it.

Yes, I think the best start is a chroot install guide. I think it would be smart to give a lighter treatment to partitioning and UEFI bootloader than we might otherwise, to anticipate other sections. I would really like an explaination of bootstrapping through xbps and then a simple recipe to getting a bootable system, with simple examples that reference other sections for more information. I.E. two lines to setup a locale and a link to that section.

It's not that I don't want everytihng covered, but in my experience it's a lot easier to get a basic coverage merged, and then multiple people can work on further additions. I don't want a giant guide held up in a pull request. :)

[ericonr]

Just for safe keeping, some guides about Void:

• https://github.com/zdykstra/zfsbootmenu/blob/master/void-install.md
• https://docs.miratengointernet.com/voidfde/
• https://github.com/atweiden/voidvault

[jeffayle]

What are the next steps, once #177 is merged? Is someone working on refactoring fde.md?

I think arm is a pretty big hole in the documentation right now. The download page still points to the wiki because there's nothing in the new manual about arm. I've started putting together some notes on it, but I'd like some feedback on what should go into it and how it should be structured. Unfortunately I only have one arm computer, so I can't test any of this out on most platforms.

Here's what I'm thinking so far,

• How to install from a disk image--- this is what most new users will come here looking for, everything past here will assume that the reader knows how to partition and format the device so that it will boot (most of the arm images have a small vfat /boot partition, so I gather this is something these platforms need to boot---this seems to be the case at least with my raspberry pi)
• How to install from platformfs tarball
• How to install from chroot--- both these sections would be small modifications of the chroot guide. I'd like to see how fde.md ends up looking so I can write these sections in the same style. The chroot guide especially would be as platform agnostic as possible, probably a list of platforms -base packages that exist (including some that there aren't distributed any other way, and as far as I can tell are not advertised anywhere), and a note that if you're not using one of those platforms the guide assumes you know how to install a kernel and bootloader.
• How to do an arm chroot install on a non-arm host using qemu--- some arm platforms are very resource constrained so you might not want to actually use them to install an operating system. Another option is to do a normal chroot install on a non-arm host, and use an emulator to do the configuration inside the chroot, which you can do surprisingly easily without even needing an emulated kernel.

[flexibeast]

@jeffayle:

Is someone working on refactoring fde.md?

Not that i'm aware of; @ericonr, is anyone working on this?

(i'm trying to add GH 'assignees' where possible, so it's clearer who's working on what.)

I think arm is a pretty big hole in the documentation right now.

i agree. The relevant open issue is https://github.com/void-linux/void-docs/issues/133. i actually don't have access to any ARM hardware myself (well, apart from my non-rooted phone :-) ), but if appropriate, i can help test things in a QEMU VM.

[ericonr]

@flexibeast afaik no one is working on those pages yet. I can be assigned to the FDE one, tentatively.

@jeffayle do you have access to any ARM boards? I ran through the installation on my RaspPi Zero, only. The thing with ARM stuff is:

• for SBCs there are images, which are basically PLATFORMFS tarballs unpacked into a pre-partitioned disk; and the PLATFORMFS tarballs, which you can unpack into the disk yourself. Neither of those installation methods require a chroot or anything, unless you want to update the image before storing it (that part could be complicated, I'm not sure how to do it. Perhaps proot -q, which uses QEMU?). The important part of this installation is configuring passwords, daemons (linking to /etc/runit/runsvdir/current instead of /var/service), and possibly some overlays. I used this repo as a reference: https://github.com/jdek/voidzero
• for something like a Pinebook, you'd probably use a generic image (someone who has one can correct me here) and an installation process closer to the one in the chroot guide.

[jeffayle]

do you have access to any ARM boards?

Platforms that void officially supports, just a Raspberry Pi 3. I have a bunch of odd devices with arm processors, but they're all locked down.

proot -q, which uses QEMU?).

This works and is surprisingly easy to setup. It can be done without proot but it involves injecting magic numbers into the kernel. (systemd has some stuff that does this configuration automatically so this isn't an issue on most distributions)

I think all three installation methods should be documented. PLATFORMFS installation can be described as a variation on ROOTFS installation---just instead of chrooting you boot off the disk and login.

chroot installation is going to be very different from x86, but not in ways that we really need to document here. For supported platforms, it should just be a matter of installing an additional something-base package. For unsupported platforms there's really nothing to say except read the documentation for your device.

[flexibeast]

@ericonr: Okay, i've just created #284 with you as the assignee. i don't know the details of what needs to be done, so please feel free to describe that there. :-)