Skip to content

2. Installation guidelines and usage

Jump to bottom
fabnicol edited this page Apr 29, 2022 · 42 revisions

Installation guidelines

  • Clone or unpack
  • Run in the local mkg directory
  • Check possible options and option defaults by calling: ./mkg help

In a nutshell

MKG can be run with standard user privileges (denoted as $), unless test mode is used, or an operating system is directly installed on a block device, or the default third-party workflows are not used (in these cases, we use the standard denotation #).

  • To create a bootable ISO run (use the .iso extension):
    $ ./mkg filename.iso

  • To burn to DVD run:
    $ ./mkg filename.iso burn (if there is only one optical disc writer to your platform, you may have to run as root in some cases).

  • To directly install Gentoo on any block device (disk drive, USB stick..) mounted or not:
    # ./mkg [iso file] [burn] hot_install ext_device=/dev/sdX

  • To install a minimal platform, without LibreOffice and data science tools add # (...) minimal use_mkg_workflow=false to command line.

  • To run the process silently (without the VirtualBox graphical interface) add gui=false

  • To run in the background, either add gui=false & to your command line or, if you want to keep a VirtualBox GUI and not run in headless mode, first launch in the foreground then use bg %n (where n is the corresponding shell job shown in the output of the jobs command). Starting MKG in the background with & and gui=true (default value) will result in a crash. When the virtual disk is completed, if your command line has an *.iso file in it, a second virtual machine will be fired to create the ISO installer. If MKG was first launched in the background and in GUI mode (using bg), this chained VM will crash for the same reason. Overall, it is preferable to run in the foreground if you wish to stick to gui mode.

An alternative Github Actions-based way of running MKG

Instead of using MKG in its above command-line version, you may prefer, for example for testing or security motives, to use it in its virtual instantiation only.
In this usage, MKG does not run on your platform but only within a virtual machine over which you keep full control.
This way of running MKG requests more input from the user but avoids all but potential security issues. Artifacts that are to be used are exclusively built by automated Github Actions workflows on a regular basis from GPG-signed commits in Github projects mkg and clonezilla_with_virtualbox.
User input is limited to creating one (or two) VirtualBox machines, setting their parameters and firing them. Please consult the comments and installation advice in the master Release section for Plasma desktops or in the gnome Release section for Gnome desktops.

Bandwidth-saving options

Spare Gentoo and Sourceforge servers, cut down on bandwidth and speed up the build!

I you already fetched the appropriate tools (the minimal install Gentoo ISO, a recent stage3 archive and a Ubuntu-based CloneZilla ISO), you may just reuse them without downloading, using the following options on command line :

  • download=false : Reuse the Gentoo install ISO (named install-amd64-minimal.iso)
  • download_clonezilla=false : Reuse Ubuntu-based CloneZilla ISO (named clonezilla.iso)
  • download_arch=false : Reuse stage3 XZ archive (named stage3-amd64.tar.xz)
  • custom_clonezilla=path/to/ISO : Reuse previously created custom Ubuntu-based CloneZilla ISO, with added VirtualBox and guest additions (named clonezilla.copy.iso). This augmented version of the CloneZillo distribution is automatically created in the process of transforming the virtual disk into a CloneZilla compressed image. It is also available independently for downloads in the Release section of the companion repository clonezilla_with_virtualbox

The files should be named as indicated in bold above.
These options will save a lot of bandwidth, some electric power, and noticeably cut down on processing time, especially if a high-speed internet connection is not available.

Other options

  • The default user is fab with password _user2021_. Root password is _dev2021_. You can specify other choices by adding nonroot_user=name_of_user and passwd=password_of_user and/or rootpasswd=password_of_root to command line.

  • To create a Gentoo installer on a USB stick (or any block device), for example on device /dev/sdf, add to command line: device_installer ext_device=sdf or alternatively ext_device="model_name", where model_name is the first few letters of the relevant output line of lsblk -oMODEL | grep . (use this if there is only one such model tag on your platform!). You can use this to create an installer stick as an alternative to a DVD install.

  • To process a VM disk already created at a prior stage into an ISO file and/or external device installation, add:
    from_vm. In case of several virtual machines, you can specify vm=name-of-virtual-machine (without .vdi).
    If vm is not specified, the default VM name Gentoo will be used.

  • To process an existing Gentoo operating system into an ISO file and/or a USB-stick Gentoo installer add: from_device ext_device=sdX and the install options (device_installer, ISO filename and/or burn)

  • Likewise to process an already created ISO installer into a USB stick Gentoo installer and/or burn the ISO to DVD add from_iso. Direct installation to device from iso is currently not supported: please use the ISO (e.g. burned to DVD) to create the installed OS.

  • The project comes in with a default kernel configuration file (.config) adapted from the Ubuntu 20.04 platform. This configuration may be overall too overloaded with unnecessary built-in drivers but will come in handy to many users. Should you wish a lighter, possibly more reactive kernel, add your custom configuration file with option:
    use_mkg_workflow=false kernel_config=/path/to/cutom/config/file

  • If your PC was made prior to 2015, its processor may not enable the AVX2 register, which is set as a global compiling option by default. In this case you should tweak the building process by adding:
    use_mkg_workflow=false cflags=\'[-core2,-O2]\'
    (note the list format enclosed within escaped single quotes) to command line, if your processor is at least CORE2-compatible, otherwise just cflags="-O2".

  • You can optionally build VirtualBox by running:
    # ./mkg build_virtualbox
    You will have to manually add the root directory to your PATH variable and either uninstall the vanilla version of VirtualBox or place the root directory and the bin subdirectory in the PATH so that this version gains precedence.

This Wiki in PDF

Clone this wiki locally