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 void-linux/void-linux.github.io#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.