From 3f59316065dd218009c019080a44460b38df1bdc Mon Sep 17 00:00:00 2001 From: derped Date: Sat, 12 Jul 2025 14:34:38 +0200 Subject: [PATCH] doc: Add a short introduction and basic installation/usage instructions. --- README.md | 252 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.org | 54 ------------ 2 files changed, 252 insertions(+), 54 deletions(-) create mode 100644 README.md delete mode 100644 README.org diff --git a/README.md b/README.md new file mode 100644 index 0000000..a470c73 --- /dev/null +++ b/README.md @@ -0,0 +1,252 @@ +# 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 = ""; + users = [ + { + name = ""; + 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 + ``` diff --git a/README.org b/README.org deleted file mode 100644 index a6cd8f1..0000000 --- a/README.org +++ /dev/null @@ -1,54 +0,0 @@ -#+LANGUAGE: en -#+AUTHOR: Baensch, Kevin -#+EMAIL: mailto://derped[at]ophanim[dot]de - -*THIS README IS A WIP IF YOU DON'T KNOW WHAT YOU ARE DOING YOU PROBABLY WONT GET IT TO RUN ON YOUR SYSTEM.* -* TODO Introduction -This is my [[https://nixos.org/][NixOS]] configuration, it provides an abstraction from the -already existing options on NixOS. To be more precise it is a -collection of preconfigured services and metapackages that can be -toggled and configured through a single NixOS submodule. - -It's flexible enough to manage *all* my machines (multiple Servers and -Desktops). - -Currently the following services are configured: -- Desktop - - i3 -- MySQL/MariaDB -- cups -- fail2ban -- nginx - - Nextcloud - - Gitea - - Hydra (works but could be better) -- openssh - -** TODO Getting Started/Setup Guide -- *WARNING:* :: I still change machine option names rather frequently - and whilst it works for me it may break for you. You - have been warned. -*** Nixpkgs Channels -/See [[https://nixos.org/channels/][NixOS Channels]]./ -This Project references 4 channels: -- nixos :: Your main channel, can be any NixOS channel of your choosing. -- nixos-stable :: Should point to the current NixOS/NixOS-small channel. -- nixos-unstable :: Should point to [[https://nixos.org/channels/nixos-unstable][nixos-unstable]] or [[https://nixos.org/channels/nixos-unstable-small][nixos-unstable-small]]. -- gitpkgs :: A copy of the current [[https://github.com/nixos/nixpkgs][nixpkgs git repo]] cloned into you system root. - -Currently these channels are only referenced in [[./pkgs/pkgsets.nix][pkgsets.nix]]. It can -be easily replaced and is therefore optional (but recommended). -#+begin_src shell -nix-channel --add https://nixos.org/channels/nixos-unstable nixos -nix-channel --add https://nixos.org/channels/nixos-19.09 nixos-stable -nix-channel --add https://nixos.org/channels/nixos-unstable nixos-unstable -nix-channel --update -git clone https://github.com/nixos/nixpkgs /nixpkgs -#+end_src - - -* TODO Submodule Documentation -- [TODO] Create a setup script. -All Submodules are defined in [[./options][options]]. -** machines -** copySysConf