From 15020a63953c2a10bd7c403101d2e00125936d52 Mon Sep 17 00:00:00 2001
From: JillThornhill <121565493+JillThornhill@users.noreply.github.com>
Date: Tue, 9 May 2023 11:38:07 +0200
Subject: [PATCH 1/6] Update README.md
Editing Readme
---
README.md | 261 +++++++++++++++++-------------------------------------
1 file changed, 81 insertions(+), 180 deletions(-)
diff --git a/README.md b/README.md
index 1db7f88..9338584 100644
--- a/README.md
+++ b/README.md
@@ -1,210 +1,111 @@
-# disko - declarative disk partitioning
+# disko - Declarative disk partitioning
-Disko takes the NixOS module system and makes it work for disk partitioning
-as well.
+NixOS is a Linux distribution where everything is described as code, with one exception: during installation, the disk partitioning and formatting are manual steps. **disko** aims to correct this sad 🤡 omission.
-I wanted to write a curses NixOS installer, and that was the first step that I
-hit; the disk formatting is a manual process. Once that's done, the NixOS
-system itself is declarative, but the actual formatting of disks is manual.
+This is especially useful for unattended installations, re-installation after a system crash or for setting up more than one identical server.
-## Features
+## Overview
-* supports LVM, ZFS, btrfs, GPT, mdadm, ext4, ...
-* supports recursive layouts
-* outputs a NixOS-compatible module
-* CLI
+**disko** can either be used after booting from a Nixos installer, or in conjunction with [nixos-anywhere](https://github.com/numtide/nixos-anywhere) if you're installing remotely.
-## How-to guides
+Before using **disko**, the specifications of the disks, partitions, type of formatting and the mount points must be defined in a Nix configuration. You can find [examples](./example) of typical configurations in the Nix community repository, and use one of these as the basis of your own configuration.
-### NixOS installation
+You can keep your configuration and re-use it for other installations, or for a system rebuild.
-For a NixOS installation follow this [quickstart guide](./docs/quickstart.md).
+**disko** is flexible, in that it supports most of the common formatting and partitioning options, including:
-### Using without NixOS
+- Disk layouts: GPT, MBR, and mixed.
+- Partition tools: LVM, mdadm, LUKS, and more.
+- Filesystems: ext4, btrfs, ZFS, bcachefs, tmpfs, and others.
-### Upgrading from older disko versions
+It can work with these in various configurations and orders, and supports recursive layouts.
-Read our [upgrade guide](/docs/upgrade-guide.md) when updating from older versions.
-## Reference
+## How to use disko
-### Module options
+Disko doesn't require installation: it can be run directly from nix-community repository. The [Quickstart Guide](./docs/quickstart.md) documents how to run Disko in its simplest form when installing NixOS.
-TODO: link to generated module options
+For information on other use cases, including upgrading from an older version of **disko**, using **disko** without NixOS and downloading the module, see the [How To Guide](./docs/quickstart.md)
-### Examples
+For more detailed options, such as command line switches, see the [Reference Guide](./docs/reference.md)
-./examples
+To access sample configurations for commonly-used disk layouts, refer to the [examples](./examples) provided.
-### CLI
+## Sample Configuration and CLI command
+
+A simple disko configuration may look like this:
```
-$ 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
-
-You can use the NixOS module in one of the following ways:
-
-
- Flakes (Current recommendation)
-
-If you use nix flakes support:
-
-``` nix
-{
- inputs.disko.url = "github:nix-community/disko";
- inputs.disko.inputs.nixpkgs.follows = "nixpkgs";
-
- outputs = { self, nixpkgs, disko }: {
- # change `yourhostname` to your actual hostname
- nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
- # change to your system:
- system = "x86_64-linux";
- modules = [
- ./configuration.nix
- disko.nixosModules.disko
- ];
- };
- };
-}
-```
-
-
- niv
-
- First add it to [niv](https://github.com/nmattia/niv):
-
-```console
-$ niv add nix-community/disko
-```
-
- Then add the following to your configuration.nix in the `imports` list:
-
-```nix
-{
- imports = [ "${(import ./nix/sources.nix).disko}/modules/disko.nix" ];
-}
-```
-
-
- nix-channel
-
- As root run:
-
-```console
-$ nix-channel --add https://github.com/nix-community/disko/archive/master.tar.gz disko
-$ nix-channel --update
-```
-
- Then add the following to your configuration.nix in the `imports` list:
-
-```nix
-{
- imports = [ ];
-}
-```
-
-
- fetchTarball
-
- Add the following to your configuration.nix:
-
-``` nix
-{
- imports = [ "${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix" ];
+{ disks ? [ "/dev/vdb" ], ... }: {
+ disk = {
+ vdb = {
+ device = builtins.elemAt disks 0;
+ type = "disk";
+ content = {
+ type = "table";
+ format = "gpt";
+ partitions = [
+ {
+ type = "partition";
+ name = "ESP";
+ start = "1MiB";
+ end = "100MiB";
+ bootable = true;
+ content = {
+ type = "filesystem";
+ format = "vfat";
+ mountpoint = "/boot";
+ };
+ }
+ {
+ name = "root";
+ type = "partition";
+ start = "100MiB";
+ end = "100%";
+ part-type = "primary";
+ bootable = true;
+ content = {
+ type = "filesystem";
+ format = "ext4";
+ mountpoint = "/";
+ };
+ }
+ ];
+ };
+ };
+ };
}
```
- or with pinning:
+If you'd saved this configuration in /tmp/disko-config.nix , and wanted to create a disk named /dev/nvme0n1, you would run the following command to partition, format and mount the disk.
-```nix
-{
- imports = let
- # replace this with an actual commit id or tag
- commit = "f2783a8ef91624b375a3cf665c3af4ac60b7c278";
- in [
- "${builtins.fetchTarball {
- url = "https://github.com/nix-community/disko/archive/${commit}.tar.gz";
- # replace this with an actual hash
- sha256 = "0000000000000000000000000000000000000000000000000000";
- }}/module.nix"
- ];
-}
-```
-
+$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
-## Using the NixOS module
+## Related Tools
-```nix
-{
- # checkout the example folder for how to configure different disko layouts
- disko.devices = {
- disk.sda = {
- device = "/dev/sda";
- type = "disk";
- content = {
- type = "table";
- format = "gpt";
- partitions = [
- {
- name = "ESP";
- start = "1MiB";
- end = "100MiB";
- bootable = true;
- content = {
- type = "filesystem";
- format = "vfat";
- mountpoint = "/boot";
- };
- }
- {
- name = "root";
- start = "100MiB";
- end = "100%";
- part-type = "primary";
- bootable = true;
- content = {
- type = "filesystem";
- format = "ext4";
- mountpoint = "/";
- };
- }
- ];
- };
- };
- };
-}
-```
+This tool is used by [nixos-anywhere](https://github.com/numtide/nixos-anywhere), which carries out a fully-automated remote install of NixOS.
-this will configure `fileSystems` and other required NixOS options to boot the specified configuration.
+We also acknowledge https://github.com/NixOS/nixpart, the conceptual ancestor of this project.
-If you are on an installer, you probably want to disable `enableConfig`.
+## Licensing and Contribution details
-disko will create the scripts `disko-create` and `disko-mount` which can be used to create/mount the configured disk layout.
+This software is provided free under the [MIT Licence](https://opensource.org/licenses/MIT).
+
+If you would like to become a contributor, please see our [contribution guidelines.](https://github.com/numtide/docs/contribution-guidelines.md)
+
+---
+
+This project is supported by [Numtide](https://numtide.com/). 
+
+We are a team of independent freelancers that love open source. We help our customers make their project lifecycles more efficient by:
+
+- Providing and supporting useful tools such as this one
+- Building and deploying infrastructure, and offering dedicated DevOps support
+- Building their in-house Nix skills, and integrating Nix with their workflows
+- Developing additional features and tools
+- Carrying out custom research and development.
+
+[Contact us](https://numtide.com/contact) if you have a project in mind, or if you need help with any of our supported tools, including this one. We'd love to hear from you.
From ba26a1dcf33de6c806d17d1844f35340388bee3d Mon Sep 17 00:00:00 2001
From: JillThornhill <121565493+JillThornhill@users.noreply.github.com>
Date: Tue, 9 May 2023 16:48:05 +0200
Subject: [PATCH 2/6] Create HowTo.md
Moved some of the stuff from the original README in here so it's not lost; still needs some editing
---
docs/HowTo.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 152 insertions(+)
create mode 100644 docs/HowTo.md
diff --git a/docs/HowTo.md b/docs/HowTo.md
new file mode 100644
index 0000000..785e2ed
--- /dev/null
+++ b/docs/HowTo.md
@@ -0,0 +1,152 @@
+# How-to Guide: Disko
+
+## How to use Disko without NixOS
+
+TODO: Still to be documented
+
+## Upgrading From Older disko versions
+
+TODO: Include documentation here.
+
+For now, see the [upgrade guide](https://github.com/JillThornhill/disko/blob/master/docs/upgrade-guide.md)
+
+## Installing NixOS module
+
+You can use the NixOS module in one of the following ways:
+
+
+ Flakes (Current recommendation)
+
+If you use nix flakes support:
+
+``` nix
+{
+ inputs.disko.url = "github:nix-community/disko";
+ inputs.disko.inputs.nixpkgs.follows = "nixpkgs";
+
+ outputs = { self, nixpkgs, disko }: {
+ # change `yourhostname` to your actual hostname
+ nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
+ # change to your system:
+ system = "x86_64-linux";
+ modules = [
+ ./configuration.nix
+ disko.nixosModules.disko
+ ];
+ };
+ };
+}
+```
+
+
+ niv
+
+ First add it to [niv](https://github.com/nmattia/niv):
+
+```console
+$ niv add nix-community/disko
+```
+
+ Then add the following to your configuration.nix in the `imports` list:
+
+```nix
+{
+ imports = [ "${(import ./nix/sources.nix).disko}/modules/disko.nix" ];
+}
+```
+
+
+ nix-channel
+
+ As root run:
+
+```console
+$ nix-channel --add https://github.com/nix-community/disko/archive/master.tar.gz disko
+$ nix-channel --update
+```
+
+ Then add the following to your configuration.nix in the `imports` list:
+
+```nix
+{
+ imports = [ ];
+}
+```
+
+
+ fetchTarball
+
+ Add the following to your configuration.nix:
+
+``` nix
+{
+ imports = [ "${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix" ];
+}
+```
+
+ or with pinning:
+
+```nix
+{
+ imports = let
+ # replace this with an actual commit id or tag
+ commit = "f2783a8ef91624b375a3cf665c3af4ac60b7c278";
+ in [
+ "${builtins.fetchTarball {
+ url = "https://github.com/nix-community/disko/archive/${commit}.tar.gz";
+ # replace this with an actual hash
+ sha256 = "0000000000000000000000000000000000000000000000000000";
+ }}/module.nix"
+ ];
+}
+```
+
+
+## Using the NixOS module
+
+```nix
+{
+ # checkout the example folder for how to configure different disko layouts
+ disko.devices = {
+ disk.sda = {
+ device = "/dev/sda";
+ type = "disk";
+ content = {
+ type = "table";
+ format = "gpt";
+ partitions = [
+ {
+ name = "ESP";
+ start = "1MiB";
+ end = "100MiB";
+ bootable = true;
+ content = {
+ type = "filesystem";
+ format = "vfat";
+ mountpoint = "/boot";
+ };
+ }
+ {
+ name = "root";
+ start = "100MiB";
+ end = "100%";
+ part-type = "primary";
+ bootable = true;
+ content = {
+ type = "filesystem";
+ format = "ext4";
+ mountpoint = "/";
+ };
+ }
+ ];
+ };
+ };
+ };
+}
+```
+
+this will configure `fileSystems` and other required NixOS options to boot the specified configuration.
+
+If you are on an installer, you probably want to disable `enableConfig`.
+
+disko will create the scripts `disko-create` and `disko-mount` which can be used to create/mount the configured disk layout.
From bd18ca94bdbb4cd498f0906072e9d9c1bfd3f05d Mon Sep 17 00:00:00 2001
From: JillThornhill <121565493+JillThornhill@users.noreply.github.com>
Date: Tue, 9 May 2023 16:50:12 +0200
Subject: [PATCH 3/6] Create reference.md
Moved some stuff from original README in here; still needs some editing
---
docs/reference.md | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
create mode 100644 docs/reference.md
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 0000000..3c49a6b
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,32 @@
+# Reference Manual: disko
+
+## Module Options
+
+TODO: Still to be documented
+
+## # Reference Manual: disko
+
+## Command Line Options
+
+```
+$ 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
+```
+
+##
From a1d9321eb7633e659a2c87032a2070f9ad904009 Mon Sep 17 00:00:00 2001
From: Jill
Date: Sun, 4 Jun 2023 16:29:45 +0200
Subject: [PATCH 4/6] - Revamped Quickstart - Added document index and added
links to it to README etc - Created placeholders for System Requirements and
Support Matrix docs
---
docs/quickstart.md | 117 ++++++++++++++++++++++-----------------------
1 file changed, 56 insertions(+), 61 deletions(-)
diff --git a/docs/quickstart.md b/docs/quickstart.md
index d1483bc..d2916f6 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,121 +1,116 @@
-# Disko quickstart
+# Quickstart: disko
-This tutorial will guide you through the process of installing NixOS on a single
-disk system using Disko.
+This tutorial describes how to install NixOS on a single disk system using `disko`. You will also need to refer to the NixOS manual, which is available [here.](https://nixos.org/manual/nixos/stable/index.html#ex-config)
-1. Booting the installer
+Please note that `disko` will reformat the entire disk and overwrite any existing partitions. Dual booting with other operating systems is not supported.
-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.
+## Step 1: Choose a Disk Configuration
-2. The disk name
+Configurations for the most common disk layouts are provided in the [examples directory](https://github.com/nix-community/disko/tree/master/example) of the `disko` repository. Decide which of these layouts best suits your requirements. If you're not sure which layout to pick, use the [hybrid](https://github.com/nix-community/disko/blob/master/example/hybrid.nix) configuration. This layout is compatible with both BIOS and EFI systems.
-Identify the name of your system disk by using the lsblk command.
+Refer to the [reference manual](./reference) for more information about the sample layouts and how to build your own configuration.
+
+Once you've chosen your layout, you'll need to make a note of the URL to the raw file. To do this, open the file in Github. Immediately below the list of contributors, you will see a button labelled 'RAW' near the right hand side. Click this. The URL of the raw file will appear in the search bar of your browser. It will look something like this:
+
+```
+https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix
+```
+
+## Step 2: Boot the installer
+
+Download the NixOS ISO image 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. Boot the machine from this USB drive.
+
+## Step 3: Retrieve the disk name
+
+Identify the name of your system disk by using the ```lsblk``` command as follows:
```
$ lsblk
+```
+
+The output from this command will look something like this:
+
+```
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.
+In this example, an empty NVME SSD with 2TB space is shown with the disk name "nvme0n1". Make a note of the disk name as you will need it later.
+## Step 4: Copy the disk configuration to your machine
-3. Disk layout
+In Step 1, you chose a disk layout configuration from the [examples directory](https://github.com/nix-community/disko/tree/master/example), and made a note of its URL.
-Choose a disk layout from the [examples directory](https://github.com/nix-community/disko/tree/master/example)
+Your configuration needs to be saved on the new machine as /tmp/disko-config.nix. You can do this using the ```curl``` command to download from the url you noted above, using the `-o` option to save the file as disko-config.nix. Your commands would look like this if you had chosen the hybrid layout:
-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.
+```
+cd /tmp
+$ curl https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix -o disko-config.nix
+```
-4. Formatting
+## Step 5: Run disko to partition, format and mount your disks
-The following step will reformat your disk and mount it to `/mnt`. Replace `` with the name of your disk obtained in step 1.
+The following step will partition and format 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/" ]'
+$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/" ]'
```
-For example, if the disk name is `nvme0n1`:
+For example, if the disk name is `nvme0n1`, the command would be:
```
-$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
+$ sudo nix run github:nix-community/disko -- --mode disko /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:
+After the command has run, your file system should have been formatted and mounted. You can verify this by running the following command:
```
$ mount | grep /mnt
+```
+
+The output should look like this if your disk name is `nvme0n1`.
+
+```
/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. Rest of the NixOS installation:
+## Step 6: Complete the NixOS installation.
-Generate and modify the NixOS configuration.
+Your disks have now been formatted and mounted, and you are ready to complete the NixOS installation as described in the [NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-installation) - see the section headed "**Installing**", Steps 3 onwards. However, you will need to include the partitioning and formatting configurations that you copied into `/tmp/disko-config.nix` in your configuration, rather than allowing NixOS to generate information about your file systems. When you are configuring the system as per Step 4 of the manual, you should:
-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.
+a) Include the `no-filesystems` switch when using the `nixos-generate-config` command to generate an initial `configuration.nix`. You will be supplying the file system configuration details from `disko-config.nix`. Your CLI command to generate the configuration will be:
```
$ 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.
+This will create the file `configuration.nix` in `/mnt/etc/nixos`.
-Next move the disko configuration as well to /etc/nixos
+b) Move the `disko` configuration to /etc/nixos
```
$ mv /tmp/disko-config.nix /mnt/etc/nixos
```
-You should then edit /mnt/etc/nixos/configuration.nix to suit your needs
+c) You can now edit `configuration.nix` as per your requirements. This is described in Step 4 of the manual. For more information about configuring your system, refer to the NixOS manual. [Chapter 6, Configuration Syntax](https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax) describes the NixOS configuration syntax, and [Appendix A, Configuration Options](https://nixos.org/manual/nixos/stable/options.html) gives a list of available options. You can find also find a minimal example of a NixOS configuration in the manual: [Example: NixOS Configuration](https://nixos.org/manual/nixos/stable/index.html#ex-config).
-```
-$ 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:
+d) When editing `configuration.nix`, you will need to add the `disko` NixOS module and `disko-config.nix` to the imports section. This section will already include the file `./hardware-configuration.nix`, and you can add the new entries just below this. This section will now include:
```
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"
- (import ./disko-config.nix {
- disks = [ "/dev/" ]; # replace this with your disk name i.e. /dev/nvme0n1
- })
];
+ disko.devices = 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, then 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`:
+e) If you chose the hybrid-partition scheme, then choose `grub` as a bootloader, otherwise follow the recommendations in Step 4 of the **Installation** section of the NixOS manual. The following configuration for `grub` works for both EFI and BIOS systems. Add this to your configuration.nix, commenting out the existing lines that configure `systemd-boot`. The entries will look like this:
```
# ...
@@ -130,7 +125,7 @@ the existing lines about `systemd-boot`:
# ...
```
-Then finish the installation and reboot your machine
+f) Finish the installation and reboot your machine,
```
$ nixos-install
From 2e548efae379a75b022f37be0708ca323e3c5fa6 Mon Sep 17 00:00:00 2001
From: Jill
Date: Sun, 4 Jun 2023 16:45:48 +0200
Subject: [PATCH 5/6] Add INDEX.md, requirements.md and support_matrix.md
---
README.md | 6 ++++--
docs/INDEX.md | 13 +++++++++++++
docs/quickstart.md | 20 +++++++++++++-------
docs/requirements.md | 9 +++++++++
docs/supportmatrix.md | 9 +++++++++
5 files changed, 48 insertions(+), 9 deletions(-)
create mode 100644 docs/INDEX.md
create mode 100644 docs/requirements.md
create mode 100644 docs/supportmatrix.md
diff --git a/README.md b/README.md
index 9338584..798eb96 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,10 @@
# disko - Declarative disk partitioning
-
+
+
+
+[Documentation Index](./docs/INDEX.md)
NixOS is a Linux distribution where everything is described as code, with one exception: during installation, the disk partitioning and formatting are manual steps. **disko** aims to correct this sad 🤡 omission.
@@ -23,7 +26,6 @@ You can keep your configuration and re-use it for other installations, or for a
It can work with these in various configurations and orders, and supports recursive layouts.
-
## How to use disko
Disko doesn't require installation: it can be run directly from nix-community repository. The [Quickstart Guide](./docs/quickstart.md) documents how to run Disko in its simplest form when installing NixOS.
diff --git a/docs/INDEX.md b/docs/INDEX.md
new file mode 100644
index 0000000..5661b6a
--- /dev/null
+++ b/docs/INDEX.md
@@ -0,0 +1,13 @@
+# disko - Declarative disk partitioning
+
+
+
+## Table of Contents
+
+- [README](../README.md)
+- [Quickstart](./quickstart.md)
+- [System Requirements](./requirements.md)
+- [How to Guide](./HowTo.md)
+- [Support Matrix](./supportmatrix.md)
+- [Reference](./reference.md)
+- [Upgrade Guide](./upgrade-guide.md)
diff --git a/docs/quickstart.md b/docs/quickstart.md
index d2916f6..ac83a1a 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,10 +1,16 @@
-# Quickstart: disko
+# disko - Declarative disk partitioning
+
+
+
+[Documentation Index](./INDEX.md)
+
+## Quickstart Guide
This tutorial describes how to install NixOS on a single disk system using `disko`. You will also need to refer to the NixOS manual, which is available [here.](https://nixos.org/manual/nixos/stable/index.html#ex-config)
Please note that `disko` will reformat the entire disk and overwrite any existing partitions. Dual booting with other operating systems is not supported.
-## Step 1: Choose a Disk Configuration
+### Step 1: Choose a Disk Configuration
Configurations for the most common disk layouts are provided in the [examples directory](https://github.com/nix-community/disko/tree/master/example) of the `disko` repository. Decide which of these layouts best suits your requirements. If you're not sure which layout to pick, use the [hybrid](https://github.com/nix-community/disko/blob/master/example/hybrid.nix) configuration. This layout is compatible with both BIOS and EFI systems.
@@ -16,11 +22,11 @@ Once you've chosen your layout, you'll need to make a note of the URL to the raw
https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix
```
-## Step 2: Boot the installer
+### Step 2: Boot the installer
Download the NixOS ISO image 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. Boot the machine from this USB drive.
-## Step 3: Retrieve the disk name
+### Step 3: Retrieve the disk name
Identify the name of your system disk by using the ```lsblk``` command as follows:
@@ -37,7 +43,7 @@ nvme0n1 259:0 0 1,8T 0 disk
In this example, an empty NVME SSD with 2TB space is shown with the disk name "nvme0n1". Make a note of the disk name as you will need it later.
-## Step 4: Copy the disk configuration to your machine
+### Step 4: Copy the disk configuration to your machine
In Step 1, you chose a disk layout configuration from the [examples directory](https://github.com/nix-community/disko/tree/master/example), and made a note of its URL.
@@ -48,7 +54,7 @@ cd /tmp
$ curl https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix -o disko-config.nix
```
-## Step 5: Run disko to partition, format and mount your disks
+### Step 5: Run disko to partition, format and mount your disks
The following step will partition and format your disk, and mount it to `/mnt`. Replace `` with the name of your disk obtained in Step 1.
@@ -77,7 +83,7 @@ The output should look like this if your disk name is `nvme0n1`.
/dev/nvme0n1p2 on /mnt/boot type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro)
```
-## Step 6: Complete the NixOS installation.
+### Step 6: Complete the NixOS installation.
Your disks have now been formatted and mounted, and you are ready to complete the NixOS installation as described in the [NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-installation) - see the section headed "**Installing**", Steps 3 onwards. However, you will need to include the partitioning and formatting configurations that you copied into `/tmp/disko-config.nix` in your configuration, rather than allowing NixOS to generate information about your file systems. When you are configuring the system as per Step 4 of the manual, you should:
diff --git a/docs/requirements.md b/docs/requirements.md
new file mode 100644
index 0000000..9fffd93
--- /dev/null
+++ b/docs/requirements.md
@@ -0,0 +1,9 @@
+# disko - Declarative disk partitioning
+
+
+
+[Documentation Index](./INDEX.md)
+
+## System Requirements
+
+TODO: Populate this
diff --git a/docs/supportmatrix.md b/docs/supportmatrix.md
new file mode 100644
index 0000000..a3825d4
--- /dev/null
+++ b/docs/supportmatrix.md
@@ -0,0 +1,9 @@
+# disko - Declarative disk partitioning
+
+
+
+[Documentation Index](./INDEX.md)
+
+## Support Matrix
+
+TODO: Populate this
From 789e93d61c38ee4aa73750ccaaacbcf46d030bcd Mon Sep 17 00:00:00 2001
From: lassulus
Date: Mon, 5 Jun 2023 10:23:08 +0200
Subject: [PATCH 6/6] docs: minor fixups
---
README.md | 4 +++-
docs/HowTo.md | 4 ++--
docs/quickstart.md | 2 +-
docs/requirements.md | 4 ++--
docs/supportmatrix.md | 4 ++--
5 files changed, 10 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
index 798eb96..7747617 100644
--- a/README.md
+++ b/README.md
@@ -82,9 +82,11 @@ A simple disko configuration may look like this:
}
```
-If you'd saved this configuration in /tmp/disko-config.nix , and wanted to create a disk named /dev/nvme0n1, you would run the following command to partition, format and mount the disk.
+If you'd saved this configuration in /tmp/disko-config.nix, and wanted to create a disk named /dev/nvme0n1, you would run the following command to partition, format and mount the disk.
+```
$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
+```
## Related Tools
diff --git a/docs/HowTo.md b/docs/HowTo.md
index 785e2ed..aa755a5 100644
--- a/docs/HowTo.md
+++ b/docs/HowTo.md
@@ -40,7 +40,7 @@ If you use nix flakes support:
niv
-
+
First add it to [niv](https://github.com/nmattia/niv):
```console
@@ -91,7 +91,7 @@ $ nix-channel --update
imports = let
# replace this with an actual commit id or tag
commit = "f2783a8ef91624b375a3cf665c3af4ac60b7c278";
- in [
+ in [
"${builtins.fetchTarball {
url = "https://github.com/nix-community/disko/archive/${commit}.tar.gz";
# replace this with an actual hash
diff --git a/docs/quickstart.md b/docs/quickstart.md
index ac83a1a..40e7ae4 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,6 +1,6 @@
# disko - Declarative disk partitioning
-
+
[Documentation Index](./INDEX.md)
diff --git a/docs/requirements.md b/docs/requirements.md
index 9fffd93..93d8398 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -2,8 +2,8 @@
-[Documentation Index](./INDEX.md)
+[Documentation Index](./INDEX.md)
## System Requirements
-TODO: Populate this
+TODO: Populate this
diff --git a/docs/supportmatrix.md b/docs/supportmatrix.md
index a3825d4..53ee715 100644
--- a/docs/supportmatrix.md
+++ b/docs/supportmatrix.md
@@ -2,8 +2,8 @@
-[Documentation Index](./INDEX.md)
+[Documentation Index](./INDEX.md)
## Support Matrix
-TODO: Populate this
+TODO: Populate this