Update readme to better reflect current state

Fixes #7.
2021-01-27 21:55:04 +01:00 · 2021-01-27 21:55:04 +01:00 · 1a63539df8
parent 4664265bb0
commit 1a63539df8
1 changed files with 65 additions and 51 deletions
--- a/README.md
+++ b/README.md
@ -1,17 +1,39 @@
 # NixOS configuration

+## Structure
+
+ * `deploy.nix`: Configuration for deployment with
+   [krops](https://cgit.krebsco.de/krops/about/)
+ * `machines`: Machine-specific configuration
+   + `README.md`: Short overview of the hardware and usage of the machine
+   + `configuration.nix`: Main configuration
+   + `hardware-configuration.nix`: Hardware-specific configuration. It should
+     not depend on any modules or files from this repository, since it is used
+     for initial setup.
+ * `modules`: Custom modules. Many are activated by default, since I want them
+   on all systems.
+ * `pkgs`: My nixpkgs overlay
+ * `users/simon`: [home-manager](https://github.com/nix-community/home-manager)
+   configuration
+
+Secrets are managed with krops’s integrated support for
+[`pass`](https://www.passwordstore.org/). Permission management for them is
+implemented in `modules/secrets.nix`.
+
 ## How to install

-This guide describes how to install this configuration (or any NixOS
-configuration) with GPT and legacy (BIOS) boot.
+This guide describes how to install this configuration with GPT and BIOS boot.
+It is not a one-fits-all guide, but the base for what I use for interactive
+systems. Servers and specialised systems may need a different setup (e. g. swap
+with random luks passphrase and no LVM).

-If you do not have a wired connection, first set up wifi
+Set up wifi if no wired connection is available:

-    wpa_passphrase "SSID" "PSK" | sudo wpa_supplicant -B -i wlp4s0 -c/dev/stdin
+    wpa_passphrase "SSID" "PSK" | wpa_supplicant -B -i wlp4s0 -c/dev/stdin

-Create the partition table (enter the indented lines in the repl).
+Create the partition table (enter the indented lines in the repl):

-    sudo parted /dev/sdX
+    parted /dev/sdX
      mktable GPT
      mkpart primary 1MiB 2MiB
      mkpart primary 2MiB 500MiB
@ -20,69 +42,61 @@ Create the partition table (enter the indented lines in the repl).
      disk_toggle pmbr_boot
      quit

-Format encrypted partition and open it
+Format encrypted partition and open it:

-    sudo cryptsetup luksFormat /dev/sdX3
-    sudo cryptsetup luksOpen /dev/sdX3 HOSTNAME-pv
+    cryptsetup luksFormat --type luks2 /dev/sdX3
+    cryptsetup open --type luks2 /dev/sdX3 HOSTNAME-pv

-Create LVM (replace `8G` with desired swap size)
+Create LVM (replace `8G` with desired swap size):

-    sudo pvcreate /dev/mapper/HOSTNAME-pv
-    sudo vgcreate HOSTNAME-vg /dev/mapper/HOSTNAME-pv
-    sudo lvcreate -L 8G -n swap HOSTNAME-vg
-    sudo lvcreate -l '100%FREE' -n root HOSTNAME-vg
+    pvcreate /dev/mapper/HOSTNAME-pv
+    vgcreate HOSTNAME-vg /dev/mapper/HOSTNAME-pv
+    lvcreate -L 8G -n swap HOSTNAME-vg
+    lvcreate -l '100%FREE' -n root HOSTNAME-vg

 **Hint**: If you have to reboot to the installation system later because
 something went wrong and you need access to the LVM (but don’t know LVM), do
-the following after opening the luks partition: `sudo vgchange -ay`
+the following after opening the luks partition: `vgchange -ay`.

-Create filesystems
+Create filesystems:

-    sudo mkfs.ext2 /dev/sdX2
-    sudo mkfs.ext4 -L root /dev/HOSTNAME-vg/root
-    sudo mkswap -L swap /dev/HOSTNAME-vg/swap
+    mkfs.ext2 /dev/sdX2
+    mkfs.ext4 -L root /dev/HOSTNAME-vg/root
+    mkswap -L swap /dev/HOSTNAME-vg/swap

-Mount the file systems and activate swap
+Mount the file systems and activate swap:

-    sudo mount /dev/HOSTNAME-vg/root /mnt
-    sudo mkdir /mnt/boot
-    sudo mount /dev/sdX2 /mnt/boot
-    sudo swapon /dev/HOSTNAME-vg/swap
-
-Create the configuration (see [below](#how-to-add-new-device)) and copy this
-repository to your new home directory (e.g. `/mnt/home/simon/nixos`).
-
-Add a symlink as the global configuration
-
-    sudo mkdir -p /mnt/etc/nixos/
-    sudo ln -s ../../home/simon/nixos/machines/nunotaba/configuration.nix /mnt/etc/nixos/configuration.nix
+    mount /dev/HOSTNAME-vg/root /mnt
+    mkdir /mnt/boot
+    mount /dev/sdX2 /mnt/boot
+    swapon /dev/HOSTNAME-vg/swap

 Generate hardware configuration and copy hardware configuration to machine
-configuration
+configuration (skip this step if you already have a hardware-configuration for
+this machine):

-    sudo nixos-generate-config --root /mnt/
-    sudo mv /mnt/etc/nixos/hardware-configuration.nix /mnt/home/simon/nixos/machines/nunotaba/hardware-configuration.nix
-    sudo ln -s ../../home/simon/nixos/machines/nunotaba/hardware-configuration.nix /mnt/etc/nixos/hardware-configuration.nix
+    nixos-generate-config --root /mnt/

-Install NixOS
-    sudo nixos-install --no-root-passwd
+Modify the hardware configuration as needed. Fill in the `FIXME` fields of
+`machines/installation/configuration.nix` and copy it to
+`/mnt/etc/nixos/configuration.nix`.

-Enter the target as a container and set a user password
+Install NixOS:

-    sudo cp /etc/resolv.conf /mnt/etc/ # see https://github.com/NixOS/nixpkgs/issues/39665
-    nixos-enter
-    passwd simon
-    ^D # nixos-enter
-    sudo rm /mnt/etc/resolv.conf
-    reboot
+    nixos-install

-## How to add new device
+Add the krops sentinel file:

- * Copy the config from the device that is similar to the new one
- * Import profiles/modules you want
- * Change settings in `configuration.nix`
- * Change secrets
+    mkdir -p /mnt/var/src
+    touch /mnt/var/src/.populate
+
+After the successful instalation, reboot use `deploy HOSTNAME` on another
+system to deploy the new system using krops, after adding the
+`configuration.nix` and entry in `machines/default.nix` for the machine.

 ## License

-[MIT License](LICENSE)
+As nixpkgs, this repository is licensed under the [MIT License](LICENSE). This
+only applies to the nix expressions, not the built system or package closure.
+Patches may also be licensed differently, since they may be derivative works of
+the packages to which they apply.