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] 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.