Create HowTo.md

Moved some of the stuff from the original README in here so it's not lost; still needs some editing
2024-11-10 06:14:14 +00:00 · 2023-05-09 16:48:05 +02:00 · 2023-05-09 16:48:05 +02:00 · ba26a1dcf3
commit ba26a1dcf3
parent 15020a6395
1 changed files with 152 additions and 0 deletions
--- a/docs/HowTo.md
+++ 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:
+
+<details>
+  <summary>Flakes (Current recommendation)</summary>
+
+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
+      ];
+    };
+  };
+}
+```
+</details>
+<details>
+  <summary>niv</summary>
+  
+  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" ];
+}
+```
+</details>
+<details>
+  <summary>nix-channel</summary>
+
+  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 = [ <disko/modules/disko.nix> ];
+}
+```
+</details>
+<details>
+  <summary>fetchTarball</summary>
+
+  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"
+  ];
+}
+```
+</details>
+
+## 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.