# 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 [npins](https://github.com/andir/npins) [^1]
- The same Nixpkgs is used for the system and all Nix commands
- This includes the Nixpkgs version, config and overlays

[^1]: Yes npins 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://git.push-f.com/config ~/config'
   cd ~/config/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. Rename the files to `$host-configuration.nix` and `$host-hardware-configuration.nix` where `$host` is the configured hostname.
   Add `# channel="..."` to the start of the `$host-configuration.nix` file where `...` is the key of a channel pinned in `npins/sources.json`.
   A new channel can be pinned with:

   ```
   nix-shell -p npins --run \
     'npins add --name nixos channel nixos-23.11'
   ```
4. Remove all stateful channels:
   ```
   sudo rm -v /nix/var/nix/profiles/per-user/*/channels*
   ```
5. Rebuild:
   ```
   sudo HOSTNAME=$host ./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:
  ```
  npins update nixos
  ```
- Upgrade to a newer release:
  ```
  npins add --name nixos --channel 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.