From ac5df46bc04bbbc612db55e1491c1ecbbf08134b Mon Sep 17 00:00:00 2001
From: Chris <stofflees@gmail.com>
Date: Fri, 13 Mar 2026 19:32:32 +0000
Subject: [PATCH] Update README

---
 README.md                                   | 93 +++++++++++++++++++++
 hardware/station-hardware-configuration.nix | 16 +++-
 2 files changed, 106 insertions(+), 3 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..afe948e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# NixOS Configuration
+
+This repository contains the declarative NixOS configuration for my machines, utilizing Flakes, Home Manager, and Disko for dynamic, multi-host deployment.
+
+## Hardware Configuration Generation
+
+When setting up a new host, or updating an existing one, you'll need to generate a hardware-specific configuration file so NixOS knows what kernel modules and microcode to load for your exact components.
+
+To generate the hardware configuration, run the following command directly on the target machine:
+
+```bash
+# Replace 'hostname' with the name of your machine (e.g., 'station' or 'stationette')
+# We use 'nix shell' since the nixos-install-tools package doesn't have a default executable.
+sudo $(which nix) --extra-experimental-features "nix-command flakes" shell nixpkgs#nixos-install-tools -c nixos-generate-config --no-filesystems --show-hardware-config --dir . > hardware/<hostname>-hardware-configuration.nix
+```
+
+Ensure this file is tracked by git before attempting to evaluate or build the flake:
+
+```bash
+git add hardware/<hostname>-hardware-configuration.nix
+```
+
+## Installation
+
+This configuration uses [Disko](https://github.com/nix-community/disko) to manage declarative disk partitioning and formatting. The disk layouts are defined in `hardware/disko.nix`.
+
+> [!WARNING]
+> Running the Disko installation commands below will **completely erase** the target disks. Ensure you have backups of any important data before proceeding.
+
+### Method 1: Installing Directly from Gitea (Remote)
+
+You can install NixOS directly from this repository without needing to clone it manually first. Boot into a NixOS live USB, open a terminal, and run the following command.
+
+Replace `<hostname>` with your target machine (e.g., `stationette`) and `<disk>` with the target block device (e.g., `/dev/sda` or `/dev/nvme0n1`):
+
+```bash
+nix --extra-experimental-features "nix-command flakes" run github:nix-community/disko/latest#disko-install -- \
+  --flake git+https://labs.scarif.space/chris/nixos/#<hostname> \
+  --disk <hostname> \
+  --write-efi-boot-entries <disk>
+```
+
+#### Examples:
+**For `stationette`:**
+```bash
+nix --extra-experimental-features "nix-command flakes" run github:nix-community/disko/latest#disko-install -- \
+  --flake git+https://labs.scarif.space/chris/nixos/#stationette \
+  --disk stationette \
+  --write-efi-boot-entries /dev/sda
+```
+
+**For `station`:**
+```bash
+nix --extra-experimental-features "nix-command flakes" run github:nix-community/disko/latest#disko-install -- \
+  --flake git+https://labs.scarif.space/chris/nixos/#station \
+  --disk station \
+  --write-efi-boot-entries /dev/nvme0n1
+```
+
+### Method 2: Installing from a Local Clone
+
+If you prefer to clone the repository first so you can make manual adjustments (like generating the hardware configuration) before deploying:
+
+1. Boot into a NixOS live USB.
+2. Clone the repository:
+   ```bash
+   git clone https://labs.scarif.space/chris/nixos.git /mnt/etc/nixos
+   cd /mnt/etc/nixos
+   ```
+3. Generate your hardware configuration (if needed):
+   ```bash
+   nixos-generate-config --no-filesystems --show-hardware-config > hardware/<hostname>-hardware-configuration.nix
+   git add hardware/<hostname>-hardware-configuration.nix
+   ```
+4. Run the Disko installer using the local flake:
+   ```bash
+   nix --extra-experimental-features "nix-command flakes" run github:nix-community/disko/latest#disko-install -- \
+     --flake .#<hostname> \
+     --disk <hostname> \
+     --write-efi-boot-entries <disk>
+   ```
+
+*(Remember to replace `<hostname>` and `<disk>` with your specific machine's details, e.g., `.m#stationette` and `/dev/sda`)*.
+
+---
+
+### Rebuilding the System
+
+Once installed and booted into your new system, you can pull the latest changes and apply updates using standard NixOS rebuild commands:
+
+```bash
+sudo nixos-rebuild switch --flake .#<hostname>
+```
diff --git a/hardware/station-hardware-configuration.nix b/hardware/station-hardware-configuration.nix
index c665a4c..ca65dd6 100644
--- a/hardware/station-hardware-configuration.nix
+++ b/hardware/station-hardware-configuration.nix
@@ -1,8 +1,18 @@
+# Do not modify this file!  It was generated by ‘nixos-generate-config’
+# and may be overwritten by future invocations.  Please make changes
+# to /etc/nixos/configuration.nix instead.
 { config, lib, pkgs, modulesPath, ... }:
 
 {
-    imports = [ (modulesPath + "/installer/scan/not-detected.nix") ];
+  imports =
+    [ (modulesPath + "/installer/scan/not-detected.nix")
+    ];
 
-    nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
-    hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;
+  boot.initrd.availableKernelModules = [ "nvme" "xhci_pci" "ahci" "usbhid" "usb_storage" ];
+  boot.initrd.kernelModules = [ ];
+  boot.kernelModules = [ "kvm-amd" ];
+  boot.extraModulePackages = [ ];
+
+  nixpkgs.hostPlatform = lib.mkDefault "x86_64-linux";
+  hardware.cpu.amd.updateMicrocode = lib.mkDefault config.hardware.enableRedistributableFirmware;
 }