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