From 2ae50cc68e42b9d790dfba26a8c42219e7ae8f6a Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <silvan.mosberger@tweag.io>
Date: Thu, 16 Nov 2023 07:30:27 +0100
Subject: import https://github.com/infinisil/sanix

I (Martin) squashed the commits up to the currently latest
(37b7f370e36f1a1e90f746e0a4f80582058f7d55).
---
 nixos/README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 nixos/README.md

(limited to 'nixos/README.md')

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.
-- 
cgit v1.2.3