README.md

@@ -91,6 +91,91 @@ If the hostname is not correct, or you don't want to clone this flake you can al
 
 In any case, to switch the system configuration you will need to have root privileges on the target machine.
 
+## Installing a new machine
+
+You have written a configuration and now want to deploy it as a new machine. You need to get the build configuration on the
+`nixos-installer` machine (regarding this machine see issue [#10]). You can either use either any of the
+versions above, or just continue then the machine will build the configuration implicitly.
+
+### Disk layout
+
+You will need to assemble the disk layout manually, we assume you do it below `/mnt` as the nixos-install tools
+assume this as the default location (they have an option to change that consider their `--help` pages).
+
+This repository loads some default configuration that expects certain things. Your hardware configuration of that machine should
+reflect those.
+
+- `"/"` is a tmpfs
+- `"/persist"` is the place where we keep data that can not be regenerated at any boot, so this should be a permanent disk
+- `"/nix"` the place the nixstore resides, needed to boot the machine should also be persistent
+- `"/boot"` the place for bootloader configuration and kernel also persistent
+- any additional data paths for your machine specific needs. Choose filesystems accordingly.
+
+My recommendation is to put `"/persist"` and `"/nix"` on a joint btrfs as subvolumes and `"/boot"` on separate disks (because grub
+will give you a hard time if you do it as a subvolume or bind mount (even though that should be possible but is an upstream problem)).
+For how to configure additional persistent data
+to be stored in `"/persist"` look at the impermanence section as soon it is merged. Before this look at issue [#9].
+I do not recommend this for actual high access application data like databases mailboxes and things like it. You should
+think about this as data that if lost can be regenerated with only little problems and read/written only a few times
+during setup. (Like the server ssh keys for example). The configuration also setups some paths for `"/persist"` automatically,
+again look at the impermanence sections.
+
+#### File system uuids
+
+You might end with a bit of a chicken/egg problem regarding filesystem uuids. See you need to set them in your system configuration.
+There are two ways around that. Either generate the filesystems read out the uuids, and push them into the repository holding
+the configuration you want to build, or generate the uuids first, have them in your configuration and set them upon filesystem creation. Most
+`mkfs` utilities have an option for that.
+
+### Installing
+
+Just run
+```
+nixos-install --flake 'git+https://gitea.mathebau.de/Fachschaft/nixConfig?ref=<branchname>#<name>'
+```
+where `<branchname>` is the branch you install from and `<name>` is the name of the configuration you build.
+If the build system is already in the nix store this will start the installation, else it will first attempt to build
+it. That should be the whole installation process, just reboot. The machine should be fully setup. No additional user
+or service setup, after the reboot.
+
+
+## How to write a new machine configuration
+At best you take a first look at already existing configurations. But here are a few guidelines.
+Make a new folder in `/nixos/machines`. The name of the folder should match the hostname of your
+machine. The only technically required file in there is `configuration.nix`. So create it.
+
+A good skeleton is probably:
+```
+flake-inputs:
+{config, pkgs, lib, ... }: {
+
+imports = [
+  ./hardware-configuration.nix
+  ../../roles
+  ./network.nix
+
+  <your additional imports here>
+
+  ];
+
+  <your system config here>
+  networking.hostname = "<your hostname>"; # this will hopefully disappear if I have time to refactor this.
+  system.stateVersion = "<state version at time of install>";
+}
+```
+the import of `../../roles` loads all the nice default setup that all these machines have in common. There the
+impermanence configuration is loaded as well as ssh, sops, shared user configuration and much more.
+The other two imports are suggestions how you should organize your configuration but not enforced by anything.
+In your hardware
+configuration you should basically only write you filesystem layout and your hostPlatform. The bootloading stuff
+is already taken care of by `../../roles`.
+
+As of moment of writing `network.nix` should contain ip, nameserver and default gateway setup. As parts of
+this is constant across all systems this will undergo refactor soon.
+
+I would recommend to split your configuration into small files you import. If this is something machine specific (like
+tied to your ip address hostname) put it into the machine directory. If it is not put it into `/nixos/roles/` if it
+is not but has options to set put it in `/nixos/modules`.
 
 ## How this flake is organized