1 files changed, 76 insertions, 0 deletions
diff --git a/nixos/README.md b/nixos/README.md
new file mode 100644
index 0000000..5888527
--- /dev/null
+++ b/nixos/README.md
@@ -0,0 +1,76 @@
+# Sane stable stateless NixOS setup
+
+This is a fairly straightforward setup for making a NixOS system configuration stateless without relying on experimental Nix features.
+
+This means:
+- `nix-channel` is disabled
+- Nixpkgs is managed with [niv](https://github.com/nmattia/niv) [^1]
+- The same Nixpkgs is used for the system and all Nix commands
+- This includes the Nixpkgs version, config and overlays
+
+[^1]: Yes niv is a third-party tool, but it's essentially just a nice wrapper around `nix-prefetch-url` and co.
+
+## Usage
+
+We're assuming that you just installed NixOS by going through the [official installation docs](https://nixos.org/manual/nixos/stable/#sec-installation).
+
+### Setup
+
+1. Clone this repo to a local directory and enter it:
+   ```
+   nix-shell -p git --run \
+     'git clone https://github.com/infinisil/sane-stable-nixos nixos'
+   cd nixos
+   ```
+2. Add your initial NixOS configuration files, either
+   - Move your existing configuration files into it:
+     ```
+     sudo mv /etc/nixos/* .
+     ```
+   - Generate new ones:
+     ```
+     nixos-generate-config --dir .
+     ```
+3. Pin Nixpkgs to the [latest stable version](https://nixos.org/manual/nixos/stable/release-notes) using [niv](https://github.com/nmattia/niv):
+   ```
+   nix-shell -p niv --run \
+     'niv init --nixpkgs NixOS/nixpkgs --nixpkgs-branch nixos-23.11'
+   ```
+4. Remove all stateful channels:
+   ```
+   sudo rm -v /nix/var/nix/profiles/per-user/*/channels*
+   ```
+5. Rebuild:
+   ```
+   sudo ./rebuild switch
+   ```
+6. Log out and back in again.
+
+### Making changes
+
+Here are some changes you can make:
+- Change the NixOS configuration in `./configuration.nix`
+- Update the pinned Nixpkgs:
+  ```
+  niv update nixpkgs
+  ```
+- Upgrade to a newer release:
+  ```
+  niv update nixpkgs --branch nixos-23.11
+  ```
+- Change the Nixpkgs config by editing `nixpkgs/config.nix`
+- Add Nixpkgs overlays to `nixpkgs/overlays.nix`
+- Regenerate the hardware configuration:
+  ```
+  nixos-generate-configuration --dir .
+  ```
+
+To apply the changes, run
+```
+sudo ./rebuild switch
+```
+
+All options to `./rebuild` are forwarded to `nixos-rebuild`.
+
+After rebuilding, the changes are reflected in the system.
+Furthermore, all Nix commands on the system will also use the the same values.