nix-git/README.md

# NixOS

For each host (server, laptop, etc.), there is a subdirectory inside [hosts](hosts).

## NixOS installation

For beginners, NixOS can be installed with a graphical installer.

Getting the ISO:

* There is no official torrent as they are not needed due to CDN.
* ISO and checksum are available here: https://nixos.org/download#nixos-iso
* There are unofficial torrents. If the checksum is compared with the one from the official website, these can be used as well: https://github.com/AnimMouse/NixOS-ISO-Torrents/releases

During installation, select manual partitioning:

* One 512MB (or larger) Fat32 partition, mounted at `/boot`, "boot" flag enabled
* Another partition (e.g. BTRFS) covering the rest of the drive, mounted at `/`, encryption enabled

## Build and switch

* https://nixos.wiki/wiki/Nixos-rebuild

Build new config, activate it and make it default:

```shell
sudo nixos-rebuild -I nixos-config=hosts/$(hostname)/configuration.nix switch
```

Or activate during next boot:

```shell
sudo nixos-rebuild -I nixos-config=hosts/$(hostname)/configuration.nix boot
```

## System updates

* https://superuser.com/a/1604695

```shell
sudo nix-channel --update
```

```shell
niv update
```

Then run `nixos-rebuild switch`, see above.

## Garbage collection

* https://nixos.org/manual/nix/stable/package-management/garbage-collection.html
* https://discourse.nixos.org/t/why-doesnt-nix-collect-garbage-remove-old-generations-from-efi-menu/17592/4

For all profiles:

```shell
sudo nix-collect-garbage --delete-older-than 14d
```

Remove old generations from EFI:

```shell
sudo /run/current-system/bin/switch-to-configuration boot
```

## Install Home Manager with niv

niv:

> Easy dependency management for Nix projects.
>
> Nix is a very powerful tool for building code and setting up environments. niv complements it by making it easy to
> describe and update remote dependencies (URLs, GitHub repos, etc). It is a simple, practical alternative to Nix
> flakes.
>
> https://github.com/nmattia/niv

> Niv is an easy dependency management for Nix projects with package pinning.
>
> https://github.com/mikeroyal/NixOS-Guide

Home Manager:

> [Home Manager] allows declarative configuration of user specific (non-global) packages and dotfiles.
>
> To avoid breaking users' configurations, Home Manager is released in branches corresponding to NixOS releases (
> e.g. `release-23.05`).
>
> Home Manager provides both the channel-based setup and the flake-based one.
>
> https://github.com/nix-community/home-manager

Check your channel:

```shell
sudo nix-channel --list
#=> nixos https://nixos.org/channels/nixos-23.05
```

Use the corresponding branch:

```shell
niv add nix-community/home-manager -n home-manager -b release-23.05
```

## disko and nixos-anywhere

* Introductory presentation: https://pad.lassul.us/cccamp-workshop
* disko: https://github.com/nix-community/disko
* nixos-anywhere: https://github.com/numtide/nixos-anywhere/

```shell
# TODO (!)
```

## BTRFS Swap file

* https://nixos.wiki/wiki/Btrfs#Swap_file
* https://wiki.archlinux.org/title/btrfs#Swap_file

Summary:

* Create subvolume `@swap` directly below top-level subvolume.
* Mount at `/swap`
* Create swapfile: `sudo btrfs filesystem mkswapfile --size 8g --uuid clear /swap/swapfile`
* Regenerate hardware-configuration: `sudo nixos-generate-config --dir $(hostname)`
* Add `swapDevices = [ { device = "/swap/swapfile"; } ];` to hardware configuration and run `nixos-rebuild switch` (see above).

## Automount encrypted drive

* Generate and add keyfile to LUKS device
* luksOpen and mount drive, e.g. to `/mnt/data1`
* Re-generate hardware configuration:

```shell
sudo nixos-generate-config --dir hosts/$(hostname)
```

## GNOME extensions

* https://github.com/nix-community/home-manager/issues/284#issuecomment-531384656
* https://github.com/nix-community/home-manager/issues/284#issuecomment-1321199263
    * Search for packaged
      extensions: https://search.nixos.org/packages?channel=23.05&from=0&size=50&sort=relevance&type=packages&query=gnomeExtensions
    * One has to re-login after
      changes: https://github.com/nix-community/home-manager/issues/284#issuecomment-1328269433

```shell
# TODO
```

## Run an AppImage

* https://nixos.wiki/wiki/Appimage

```shell
# Note how your shell prefix changes.
nix-shell --packages appimage-run
```
```shell
# Inside the shell, you can run an AppImage:
appimage-run ~/Downloads/ubports-installer_0.10.0_linux_x86_64.AppImage
```

## General Notes

* There is controversy about flakes, rather use channels (e.g. with niv)
* Prins, P., Suresh, J. and Dolstra, E., "Nix fixes dependency hell on all Linux distributions," [Archived](https://web.archive.org/web/20081226010942/http://www.linux.com/feature/155922) December 26, 2008, at the Wayback Machine linux.com, December 22, 2008

### Nix Pills

* https://nixos.org/guides/nix-pills/pr01

It provides a tutorial introduction into the Nix package manager and Nixpkgs package collection, in the form of short
chapters called 'pills'.

### Papers

Papers about Nix:

* The Purely Functional Software Deployment Model (2006). http://nixos.org/~eelco/pubs/phd-thesis.pdf, https://edolstra.github.io/pubs/phd-thesis.pdf, https://github.com/edolstra/edolstra.github.io/blob/master/pubs/phd-thesis.pdf
  * May 2023: Some insights from the thesis in short form. https://jonathanlorimer.dev/posts/nix-thesis.html
* NixOS: A Purely Functional Linux Distribution (2008): https://github.com/edolstra/edolstra.github.io/blob/master/pubs/nixos-icfp2008-final.pdf, https://github.com/edolstra/edolstra.github.io/blob/master/pubs/nixos-jfp-final.pdf
* Nix: A Safe and Policy-Free System for Software Deployment (2004): https://edolstra.github.io/pubs/nspfssd-lisa2004-final.pdf

### Search for packages

* https://search.nixos.org/packages?channel=23.05

### Search for options

* https://search.nixos.org/options?channel=23.05
    * Or `man configuration.nix`
* https://mipmip.github.io/home-manager-option-search
    * Or `man home-configuration.nix`

### Search wich package owns a file

```shell
# Note how your shell prefix changes.
nix-shell --packages nix-index
```
```shell
# Inside the shell:

# Either build the index manually (requires >8GB RAM)
nix-index
# Or download weekly build:
mkdir -p ~/.cache/nix-index/ && wget -q -N https://github.com/nix-community/nix-index-database/releases/latest/download/index-x86_64-linux -O ~/.cache/nix-index/files

# Then search for a file
nix-locate -w '/bash'
```

### List files of package

* https://discourse.nixos.org/t/list-files-of-package/25830/2?u=langfingaz

Example for `nano`:

```shell
find $(nix-build '<nixpkgs>' -A nano --no-link)
```

Excerpt of the result:

```
/nix/store/jqvxmx65mfinbsm6db9kmcqmphl44xhp-nano-7.2/share/nano
/nix/store/jqvxmx65mfinbsm6db9kmcqmphl44xhp-nano-7.2/share/nano/asm.nanorc
/nix/store/jqvxmx65mfinbsm6db9kmcqmphl44xhp-nano-7.2/share/nano/autoconf.nanorc
```

### NixOS configuration debugging

* https://nixos.wiki/wiki/Nix_command/repl

Evaluating parts of the configuration.

First, start `nix repl`:

```shell
nix repl --file '<nixpkgs/nixos>' -I nixos-config=hosts/$(hostname)/configuration.nix
```

Example: `config.home-manager`

```shell
config.home-manager.
# Press `TAB`
#=> config.home-manager.backupFileExtension  config.home-manager.useUserPackages
#=> config.home-manager.extraSpecialArgs     config.home-manager.users
#=> config.home-manager.sharedModules        config.home-manager.verbose
#=> config.home-manager.useGlobalPkgs
```

Example: The `home` variable:

```shell
config.home-manager.users.yoda.home
```

Example: The value of one config option

```shell
# The following option is set to `"${config.xdg.dataHome}/.histfile";`
# where `config` is the Home Manager configuration.

config.home-manager.users.yoda.programs.zsh.history.path
#=> "/home/yoda/.local/share/.histfile"
```

### Evaluate NixOS configuration to JSON

See also section "NixOS Configuration Debugging"!

TODO: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-show-config.html

* https://discourse.nixos.org/t/can-i-run-nix-instantiate-eval-strict-on-my-configuration-nix/7105/4

This evaluates `configuration.nix` (single module):

```shell
NIXPKGS_ALLOW_UNFREE=1 nix-instantiate --strict --json --eval -E '
import ./hosts/yodaTab/configuration.nix  {
  config = {};
  pkgs = import <nixpkgs> {};
  lib = import <nixpkgs/lib>;
}
' > evaluated-config.json
```

Then open [evaluated-config.json](evaluated-config.json).

### References

Some references to websites that helped me create this repository:

* https://github.com/Misterio77/nix-starter-configs
* https://github.com/mikeroyal/NixOS-Guide#getting-started

## TODOs

* FDE remote SSH unlock: https://nixos.wiki/wiki/Remote_LUKS_Unlocking, https://wiki.archlinux.org/title/Dm-crypt/Specialties#Remote_unlocking_of_root_(or_other)_partition
* Yubikey FDE: https://github.com/georgewhewell/nixos-host/blob/master/profiles/luks-yubi.nix
* Impermanence, opt-in to
  persistence: https://github.com/Misterio77/nix-starter-configs/tree/main#try-opt-in-persistance
* nix-shell / lorri
  * https://ghedam.at/15978/an-introduction-to-nix-shell
    * docker-compose.yml for services and nix-shell to run the code