From db2be366c4338e848de6eee0ef94781c26479be9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= Date: Thu, 2 Feb 2023 15:15:39 +0100 Subject: [PATCH 1/4] quickstart guide --- quickstart.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 quickstart.md diff --git a/quickstart.md b/quickstart.md new file mode 100644 index 0000000..18071d5 --- /dev/null +++ b/quickstart.md @@ -0,0 +1,129 @@ +# Disko quickstart + +This tutorial will guide you through the process of installing NixOS on a single +disk system using Disko. + +- 1. Download NixOS ISO images from the NixOS download page +(https://nixos.org/download.html#nixos-iso) and create a bootable USB drive +following the instructions in [Section 2.4.1 "Booting from a USB flash drive"](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb) +of the NixOS manual. + +- 2. Identify the name of your system disk by using the lsblk command. + +``` +$ lsblk +NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS +nvme0n1     259:0    0   1,8T  0 disk +``` + +In this example, an empty NVME SSD with 2TB space is shown as "nvme0n1" disk. +Please note that Disko will reformat the entire disk and overwrite any existing +partitions. Dual booting with other operating systems is not supported. + + +- 3. Choose a disk layout from the [examples directory](https://github.com/nix-community/disko/tree/master/example) + +For those who are unsure of which layout to pick, use the hybrid configuration +found at https://github.com/nix-community/disko/blob/master/example/hybrid.nix +and save it as `/tmp/disko-config.nix`. This layout is compatible with both BIOS +and EFI systems. + +- 4. The following step will reformat your disk and mount it to `/mnt`. Replace + `` with the name of your disk obtained in step 1. + +Please note: This will erase any existing data on your disk. + +``` +$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/" ]' +``` + +For example, if the disk name is `nvme0n1`: + +``` +$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]' +``` + + +After executing the command, the file systems will be mounted. You can verify +this by running the following command: + +``` +$ mount | grep /mnt +/dev/nvme0n1p1 on /mnt type ext4 (rw,relatime,stripe=2) +/dev/nvme0n1p2 on /mnt/boot type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro) +``` + +- 5. Generate and modify the NixOS configuration: + +You now need to create a file `/mnt/etc/nixos/configuration.nix` that specifies +the intended configuration of the system. This is because NixOS has a +declarative configuration model: you create or edit a description of the desired +configuration of your system, and then NixOS takes care of making it happen. The +syntax of the NixOS configuration file is described in +[Chapter 6, Configuration Syntax](https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax), +while a list of available configuration options appears in +[Appendix A, Configuration Options](https://nixos.org/manual/nixos/stable/options.html). +A minimal example is shown in +[Example: NixOS Configuration](https://nixos.org/manual/nixos/stable/index.html#ex-config). + +The command nixos-generate-config can generate an initial configuration file for +you. + +``` +$ nixos-generate-config --no-filesystems --root /mnt +``` + +We will include `--no-filesystems` the flag here so it won't add any filesystem +mountpoints to the generated `/mnt/etc/nixos/hardware-configuration.nix` since +we will re-use our disko configuration for that. + +Next move the disko configuration as well to /etc/nixos + +``` +$ mv /tmp/disko-config.nix /mnt/etc/nixos +``` + +You should then edit /mnt/etc/nixos/configuration.nix to suit your needs + +``` +$ nano /mnt/etc/nixos/configuration.nix +``` + +While being in this file also add the disko nixos module as well as the +disko-config.nix in the imports section of your generated configuration: + +``` +imports = + [ # Include the results of the hardware scan. + ./hardware-configuration.nix + "${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix" + (pkgs.callPackage ./disko-config.nix { + disks = ["/dev/"]; # replace this with your disk name i.e. /dev/nvme0n1 + }) + ]; +``` + +If you went for the hybrid-partition scheme, than choose grub as a bootloader. +Otherwise consult the NixOS manual. The following configuration for Grub works +both EFI and BIOS systems. Add it to your configuration.nix while commenting out +the existing lines about `systemd-boot`: + +``` +# ... + #boot.loader.systemd-boot.enable = true; + #boot.loader.efi.canTouchEfiVariables = true; + # replace this with your disk i.e. /dev/nvme0n1 + boot.loader.grub.devices = [ "/dev/" ]; + boot.loader.grub.enable = true; + boot.loader.grub.version = 2; + boot.loader.grub.efiSupport = true; + boot.loader.grub.efiInstallAsRemovable = true; +# ... +``` + +Than finish the installation and reboot your machine + +``` +$ nixos-install +$ reboot +``` From 66b265be447e542f15664b20cd8baf213f275d65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= Date: Fri, 3 Feb 2023 13:22:39 +0100 Subject: [PATCH 2/4] add quickstart guide --- README.md | 10 +--------- quickstart.md => docs/quickstart.md | 0 2 files changed, 1 insertion(+), 9 deletions(-) rename quickstart.md => docs/quickstart.md (100%) diff --git a/README.md b/README.md index 5a719e4..ab1ed98 100644 --- a/README.md +++ b/README.md @@ -18,15 +18,7 @@ system itself is declarative, but the actual formatting of disks is manual. ### NixOS installation -During the NixOS installation process, replace the [Partitioning and -formatting](https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning) -steps with the following: - -1. Find a disk layout in ./examples that you like. -2. Write the config based on the example and your disk layout. -4. Run the CLI (`nix run github:nix-community/disko`) to apply the changes. -5. FIXME: Copy the disko module and disk layout around. -6. Continue the NixOS installation. +For a NixOS installation follow this [quickstart guid](./docs/quickstart.md). ### Using without NixOS diff --git a/quickstart.md b/docs/quickstart.md similarity index 100% rename from quickstart.md rename to docs/quickstart.md From 753b5543a0ee6de208482cac1f100214506788b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= Date: Fri, 3 Feb 2023 13:27:21 +0100 Subject: [PATCH 3/4] better structure --- docs/quickstart.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 18071d5..716d9fa 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -3,12 +3,16 @@ This tutorial will guide you through the process of installing NixOS on a single disk system using Disko. -- 1. Download NixOS ISO images from the NixOS download page +1. Booting the installer + +Download NixOS ISO images from the NixOS download page (https://nixos.org/download.html#nixos-iso) and create a bootable USB drive following the instructions in [Section 2.4.1 "Booting from a USB flash drive"](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb) of the NixOS manual. -- 2. Identify the name of your system disk by using the lsblk command. +2. The disk name + +Identify the name of your system disk by using the lsblk command. ``` $ lsblk @@ -21,15 +25,18 @@ Please note that Disko will reformat the entire disk and overwrite any existing partitions. Dual booting with other operating systems is not supported. -- 3. Choose a disk layout from the [examples directory](https://github.com/nix-community/disko/tree/master/example) +3. Disk layout + +Choose a disk layout from the [examples directory](https://github.com/nix-community/disko/tree/master/example) For those who are unsure of which layout to pick, use the hybrid configuration found at https://github.com/nix-community/disko/blob/master/example/hybrid.nix and save it as `/tmp/disko-config.nix`. This layout is compatible with both BIOS and EFI systems. -- 4. The following step will reformat your disk and mount it to `/mnt`. Replace - `` with the name of your disk obtained in step 1. +4. Formatting + +The following step will reformat your disk and mount it to `/mnt`. Replace `` with the name of your disk obtained in step 1. Please note: This will erase any existing data on your disk. @@ -53,7 +60,9 @@ $ mount | grep /mnt /dev/nvme0n1p2 on /mnt/boot type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro) ``` -- 5. Generate and modify the NixOS configuration: +5. Rest of the NixOS installation: + +Generate and modify the NixOS configuration. You now need to create a file `/mnt/etc/nixos/configuration.nix` that specifies the intended configuration of the system. This is because NixOS has a From a9e0f9ba442931b87fd9f2eedc54d6dcedddf074 Mon Sep 17 00:00:00 2001 From: Aiden Date: Wed, 1 Feb 2023 13:52:46 +0000 Subject: [PATCH 4/4] insert output of the cli --help --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ab1ed98..69d616b 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,32 @@ TODO: link to generated module options ### CLI -TODO: output of the cli --help +``` +$ nix run github:nix-community/disko -- + +disko [options] disk-config.nix +or disko [options] --flake github:somebody/somewhere + +Options: + +* -m, --mode mode + set the mode, either create or mount +* -f, --flake uri + fetch the disko config relative to this flake's root +* --arg name value + pass value to nix-build. can be used to set disk-names for example +* --argstr name value + pass value to nix-build as string +* --root-mountpoint /mnt + where to mount the device tree +* --dry-run + just show the path to the script instead of running it +* --debug + run with set -x + +``` + + ## Installing NixOS module