nixos/README.md

# Yet Another NixOS Configuration

## Introduction

This is my [NixOS](https://nixos.org/) configuration, it provides an abstraction from the
already existing options on NixOS. To be more precise it is a
collection of pre-configured services and meta-packages that can be
toggled and configured through a single NixOS module.

It's flexible enough to manage *all* my machines (multiple server and
desktop configurations).

## Getting Started

The following instructions are for a fresh NixOS installation.

1. (Optional) **Partition Layout for Impermanence + Btrfs**

    1. Btrfs

        Format your `root` partition as Btrfs.
        Remember to add `"btrfs"` (and `"btrbk"` if you use impermanence) to `config.machine.services` in step 3.

    1. Impermanence

        > [!WARNING]
        > Many services are not yet configured for impermanence.
        > You will likely have to add your desired state to the [impermanence service](./services/impermanence.nix)

        For [impermanence](https://github.com/nix-community/impermanence) to work you will have to:

        Your system root (`/`) should be either a `tmpfs` mount or has to be [deleted during boot](https://github.com/nix-community/impermanence?tab=readme-ov-file#btrfs-subvolumes).

        Create at least the following folders (or subvolumes if you're using Btrfs) on your disk:

        - `/nix` for the nix store
        - `/persist` to store persistent folders to be mounted by impermanence
        - `/tmp` mainly because [nix builds use /tmp by default](https://github.com/NixOS/nixpkgs/issues/54707)
        - `/snapshots` to store snapshots if you are using `btrbk`

        Remember to add `"impermanence"` to `config.machine.services` in step 3.

1. **Generate your base configuration.**

    By either taking your existing configuration or following the [NixOS Installation Manual](https://nixos.org/manual/nixos/stable/#sec-installation-manual) until `nixos-generate-config`.

    You should have the files:

    - `configuration.nix`
    - `hardware-configuration.nix`

    Adjust the mounts inside your `hardware-configuration.nix` to fit your setup.
    Here is a configuration template assuming an encrypted Btrfs partition and impermanence:

    ```nix
    {
      nixpkgs,
      config,
      pkgs,
      modulesPath,
      nixos-hardware,
      ...
    }:

    {
      imports = [
        (modulesPath + "/installer/scan/not-detected.nix")
        # check https://github.com/NixOS/nixos-hardware or remove
        nixos-hardware.nixosModules.YOUR_DEVICE_HERE
      ];

      boot = {
        loader.systemd-boot = {
          enable = true;
        };
        loader.efi.canTouchEfiVariables = true;
        supportedFilesystems = [ "btrfs" ];
        # modify/add initrd and kernelModules to your needs
        initrd = {
          availableKernelModules = [ ];
          luks.devices."btrfs-crypt".device = "/dev/disk/by-uuid/DEVICE_UUID";
        };
        kernelModules = [ ];
      };

      fileSystems = {
        "/" = {
          device = "none";
          fsType = "tmpfs";
          options = [
            "defaults"
            "size=512M"
            "mode=755"
          ];
        };
        "/tmp" = {
          device = "/dev/mapper/btrfs-crypt";
          fsType = "btrfs";
          options = [
            "subvol=tmp"
            "noatime"
            "compress=zstd"
          ];
          neededForBoot = true;
        };
        "/persist" = {
          device = "/dev/mapper/btrfs-crypt";
          fsType = "btrfs";
          options = [
            "subvol=persist"
            "noatime"
            "compress=zstd"
          ];
          neededForBoot = true;
        };
        "/nix" = {
          device = "/dev/mapper/btrfs-crypt";
          fsType = "btrfs";
          options = [
            "subvol=nix"
            "noatime"
            "compress=zstd"
          ];
          neededForBoot = true;
        };
        "/snapshots" = {
          device = "/dev/mapper/btrfs-crypt";
          fsType = "btrfs";
          options = [
            "subvol=snapshots"
            "noatime"
            "compress=zstd"
          ];
          neededForBoot = false;
        };
        "/boot" = {
          device = "/dev/disk/by-uuid/546A-A3D1";
          fsType = "vfat";
          options = [
            "fmask=0022"
            "dmask=0022"
          ];
        };
      };

      # add hardware power policies and timezone
    }

    ```


1. **Define `options.nix` for your Machine**

    > [!NOTE]
    > This section needs to be expanded.
    > Ideally I just refine the machine module, implement generating docs and refer to there.

    ```nix
    _:

    {
      config.machine = {
        allowUnfree = true;
        hostName = "<hostname>";
        users = [
          {
            name = "<username>";
            isAdmin = true;
            pkgs = [];
            services = [];
          }
        ];
        conffiles = [
          "etcfiles"
          "etcvars"
          "fonts"
          "zsh"
        ];
        pkgs = [
          "base"
        ];
        services = [
          "desktop"
          "desktop::sway"
          "openssh"
          "pipewire"
          "tmux"
        ];
      };
    }
    ```

1. **Set up Sops.**

    Secret management throughout this project is handled with [sops-nix](https://github.com/Mic92/sops-nix).
    If you are unfamiliar with [sops](https://github.com/getsops/sops), read the [sops documentation](https://getsops.io/docs/)

    Adjust the `.sops.yaml` file to your needs.

    Generate your machine key in a persistent location (adjust if you are not using impermanence):

    ```bash
    mkdir -p /mnt/persist/var/lib/;
    cd /mnt/persist/var/lib/;
    # create a subvolume so the key is not included in snapshots
    btrfs subvolume create sops-nix;
    chmod 700 sops-nix;
    # make sure age is in your path
    age-keygen -o sops-nix/key.txt
    ```

    In your machine folder add the files:

    - sops.nix

        ```nix
        _:

        {
          sops = {
            defaultSopsFile = ./secrets.yaml;
            age = {
              keyFile = "/persist/var/lib/sops-nix/key.txt";
              generateKey = true;
            };
          };
        }
        ```

    - secrets.yaml

        You can get a rough overview of all sops secrets by grepping the repository for `sops.secrets`.
        Or you can list the required secrets for your current configuration by running the following command (adjust host name):

        ```bash
        nix eval  .\#nixosConfigurations.$(hostname).config.sops.secrets --json | jq 'keys'
        ```

        Edit your secrets by running (adjust the path to your key and `secrets.yaml`):

        ```bash
        SOPS_AGE_KEY_FILE="/mnt/persist/var/lib/sops-nix/key.txt" sops edit machines/$(hostname)/secrets.yaml
        ```

        A minimal secret configuration for a single user with the `openssh` service enabled may look like this:

        ```yaml
        users:
            MY_USER_NAME:
                password: PASSWORD_HASH_FROM_MKPASSWD
                publicKey: ssh-ed25519 PUB_KEY PUB_KEY_COMMENT
        ```