Update README; add new host template

2024-05-10 12:53:17 -04:00 · 2024-05-10 12:53:17 -04:00 · 92a96ec86e
parent 990fb885e1
commit 92a96ec86e
4 changed files with 98 additions and 47 deletions
--- a/README.md
+++ b/README.md
@ -5,7 +5,7 @@ A full set of configuration files managed via NixOS. This project follows the ge
 > [!WARNING]
 > DO NOT DOWNLOAD AND RUN `nixos-rebuild` ON THIS REPOSITORY! These are my personal configuration files. I invite you to look through them, modify them, and take inspiration from them, but if you run `nixos-rebuild`, it _will completely overwrite your current system_!

-## Running
+## Using this repo

 ### Note on secrets management

@ -17,7 +17,7 @@ Initialize the submodule with:
 git submodule update --init --recursive
 ```

-### Installing and upgrading
+### First-time installation

 To apply the config for the first time (e.g. on a fresh install), run these commands, replacing `Shura` with the name of the host:

@ -31,83 +31,100 @@ sudo nixos-rebuild switch --flake .#Shura
 > [!NOTE]
 > This config installs a [Nix wrapper called nh](https://github.com/viperML/nh). Basic install/upgrade commands can be run using `nh`, but more advanced stuff should use `nixos-rebuild`.

-For subsequent builds, you can omit the hostname:
+### Running updates
+
+Periodically run `nh` to update the system. Use the `--update` flag to update `flake.lock` as part of the process. Note that for subsequent builds, you can omit the hostname:

 ```sh
-nh os switch
+nh os boot --update
 ```

-or
+This is the equivalent of running:

 ```sh 
 nix flake update
-sudo nixos-rebuild switch --flake .
+sudo nixos-rebuild boot --flake .
 ```

-`switch` replaces the running system immediately, or you can use `boot` to only apply the switch during the next reboot.
+There are a few different actions for handling the update:

-#### Remote builds
+- `switch` replaces the running system immediately.
+- `boot` switches to the new generation during the next reboot.
+- `build` creates and caches the update without applying it.
+- `test` creates the generation and switches to it, but doesn't add it to the bootloader.

-You can build any Nix or NixOS expression on a remote system before copying it over, as long as you have SSH access to the build target.
+#### Using Remote builds

-> [!NOTE]
-> Run this command without sudo, otherwise SSHing into `haven` won't work.
+You can build any Nix or NixOS expression on a remote system before copying it over, as long as the root user on the local system has SSH access to the build target.

-```sh
-nixos-rebuild boot --flake . --build-host haven
+To enable root builds on a host, add this to its config:
+
+```nix
+nix.distributedBuilds = true;
 ```

-You can also define build targets in a Nix config file. See Dimaga for an example.
+For hosts where `nix.distributedBuilds` is true, this repo automatically gives the local root user SSH access to an unprivileged user on the build systems. This is configured in `nix-secrets`, but the build systems are defined in [`modules/base/nix.nix`](https://github.com/8bitbuddhist/nix-configuration/blob/b816d821636f9d30be905af80fe578c25ce74b92/modules/base/nix.nix#L41).

-### Testing
+### Testing without modifying the system

-To quickly validate the configuration, create a dry build. This builds the config without actually adding it to the system:
+If you want to test without doing a whole build, or without modifying the current system, there are a couple additional tools to try.
+
+#### Dry builds
+
+To quickly validate your configuration, create a dry build. This analyzes your configuration to determine whether it'll actually build:

 ```zsh
 nixos-rebuild dry-build --flake .
 ```

-To preview changes in a virtual machine, use this command to create a virtual machine image (remove the .qcow2 image after a while, otherwise data persistence might mess things up):
+#### Virtual machines
+
+You can also build a virtual machine image to preview changes. The first command builds the VM, and the second runs it:

 ```zsh
 nixos-rebuild build-vm --flake .
+./result/bin/run-nixos-vm
 ```

-## Layout
+> [!NOTE]
+> Running the VM also creates a `.qcow2` file for data persistence. Remove this file after a while, otherwise data might persist between builds and muck things up.
+
+### Adding a host
+
+To add a new host:
+
+1. Create a new folder in `hosts/`.
+2. Copy `hosts/configuration.nix.template` into this folder and name it `default.nix`. 
+3. Run `nixos-hardware-configuration` on the host and copy its `hardware-configuration.nix` file here. You might also want to check the `configuration.nix` generated by this command to see if there's anything you should import into your host's `default.nix`.
+4. Configure `/hosts/<host>default.nix` however you'd like.
+5. Add the new host to `flake.nix`.
+5. Run `nix flake update` and `nixos-rebuild boot --flake .#<Hostname>`.
+
+## About this repository
+
+### Layout

 This config uses two systems: Flakes, and Home-manager.

 - Flakes are the entrypoint, via `flake.nix`. This is where you include Flake modules and define Flake-specific options.
 - Home-manager configs live in the `users/` folders. Each user gets its own `home-manager.nix` file too.
- Modules are stored in `modules`. All of these files are imported, and you enable the ones you want to use. For example, to install Flatpak, set `host.ui.flatpak.enable = true;`.
+- Modules are stored in `modules`. All of these files are automatically imported; you simply enable the ones you want to use, and disable the ones you don't. For example, to install Flatpak, set `host.ui.flatpak.enable = true;`.
    - After adding a new module, make sure to `git add` it.
    - Modules are automatically imported - see `autoimport.nix`.

-### Adding a host
-
-When adding a host:
-
-1. Create its config in `hosts/hostname/<hostname>.nix`. Add its `hardware-configuration.nix` here too.
-2. Reference a profile from `profiles/`. This sets up its base configuration.
-3. Include user accounts from `users`.
-4. Add any host-specific options, 
-5. Import it in `/hosts/default.nix`.
-6. Run `nixos-rebuild`.
-
-## Features
+### Features

 This Nix config features:

 - Flakes
 - Home Manager
- AMD and Intel hardware configurations
+- AMD, Intel, and Raspberry Pi hardware configurations
 - Workstation and server base system configurations
- GNOME Desktop environment and KDE integrations
+- GNOME desktop environment with KDE integrations
 - Boot splash screens via Plymouth
- Secure Boot
+- Secure Boot and TPM
 - Disk encryption via LUKS
- Custom packages and systemd services (Duplicacy)
+- Custom packages and systemd services (Duplicacy Web)
 - Flatpaks
- Per-user configurations
 - Default ZSH shell using Oh My ZSH
 - Secrets (in a janky hacky kinda way)
--- a/flake.lock
+++ b/flake.lock
@ -150,11 +150,11 @@
        ]
      },
      "locked": {
-        "lastModified": 1715077503,
-        "narHash": "sha256-AfHQshzLQfUqk/efMtdebHaQHqVntCMjhymQzVFLes0=",
+        "lastModified": 1715348159,
+        "narHash": "sha256-nP0PJZ3dR0ols1V+w+sYBki7JlSRFvFJ8J8B00Oa7BM=",
        "owner": "nix-community",
        "repo": "home-manager",
-        "rev": "6e277d9566de9976f47228dd8c580b97488734d4",
+        "rev": "223743313bab8b0b44a57eaf9573de9f69082b4d",
        "type": "github"
      },
      "original": {
@ -218,11 +218,11 @@
        ]
      },
      "locked": {
-        "lastModified": 1715202703,
-        "narHash": "sha256-khZE2rZ4MAVI51ZhQxZRTzl+ym8KVUYMfUrFbWUfgzE=",
+        "lastModified": 1715278311,
+        "narHash": "sha256-Z787hdZuwBhQCQOeOmln5j9cCKxDWql7tbF1ukKDFZU=",
        "ref": "refs/heads/main",
-        "rev": "d15ff50703ea83b595249eb3e67d2e668235d5a6",
-        "revCount": 73,
+        "rev": "c8ab1e79ba0140bc75731c75177242089506260b",
+        "revCount": 75,
        "type": "git",
        "url": "https://git.lix.systems/lix-project/nixos-module"
      },
@ -296,11 +296,11 @@
    },
    "nixpkgs_2": {
      "locked": {
-        "lastModified": 1715087517,
-        "narHash": "sha256-CLU5Tsg24Ke4+7sH8azHWXKd0CFd4mhLWfhYgUiDBpQ=",
+        "lastModified": 1715266358,
+        "narHash": "sha256-doPgfj+7FFe9rfzWo1siAV2mVCasW+Bh8I1cToAXEE4=",
        "owner": "NixOS",
        "repo": "nixpkgs",
-        "rev": "b211b392b8486ee79df6cdfb1157ad2133427a29",
+        "rev": "f1010e0469db743d14519a1efd37e23f8513d714",
        "type": "github"
      },
      "original": {
--- a/hosts/configuration.nix.template
+++ b/hosts/configuration.nix.template
@ -0,0 +1,34 @@
+# Template file for configuring a new host
+{
+  pkgs,
+  home-manager,
+  lib,
+  config,
+  ...
+}:
+{
+  # Generate hardware-configuration.nix by running this command on the host:
+  #   $ nixos-generate-config
+  imports = [ ./hardware-configuration.nix ];
+
+  system.stateVersion = "24.05";
+
+  host = {
+    role = "workstation";
+    apps = {
+      # Define applications here
+    };
+    services = {
+      # Define services here
+    };
+    users.aires = {
+      enable = true;
+      services.syncthing = {
+        enable = true;
+        autostart = true;
+      };
+    };
+  };
+
+  # Additional host-specific configuration options go here
+}
--- a/2
+++ b/2
@ -1 +1 @@
-Subproject commit 2b8e92fa817f6fa383ab1a6f8f51ac3952a838fb
+Subproject commit 87d466be5fcc11e4f3563bbbb409e69ff1455b19