From 396d85750cae927825787b89199fc6b028f5c724 Mon Sep 17 00:00:00 2001
From: Daniel Langbein <daniel@systemli.org>
Date: Mon, 18 Sep 2023 16:36:13 +0200
Subject: [PATCH] update README

---
 README.md | 44 ++++++++++++++++++++++++--------------------
 1 file changed, 24 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index c87aba5..ae7d5bf 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,11 @@ sudo nix-channel --update && niv update
 
 To apply the updates, continue with "Build and switch".
 
-### Build and switch
+### Build and switch: Using Colmena
+
+See section "Colmena: Deployment and secret management" to build and apply updates.
+
+### Build and switch: Manually
 
 * https://nixos.wiki/wiki/Nixos-rebuild
 * https://discourse.nixos.org/t/how-to-get-this-pending-updates-notification-in-gnome/16344/3
@@ -96,7 +100,7 @@ Remove old generations from EFI:
 sudo /run/current-system/bin/switch-to-configuration boot
 ```
 
-## Dependency management with niv
+## niv: Dependency management
 
 * https://nix.dev/tutorials/first-steps/towards-reproducibility-pinning-nixpkgs#dependency-management-with-niv
 
@@ -180,7 +184,7 @@ niv add nix-community/home-manager -n home-manager -b release-23.05
 niv add nix-community/NUR -n NUR
 ```
 
-## disko and nixos-anywhere
+## disko and nixos-anywhere: Remote installation
 
 * Introductory presentation: https://pad.lassul.us/cccamp-workshop
 * disko: https://github.com/nix-community/disko
@@ -190,7 +194,7 @@ niv add nix-community/NUR -n NUR
 # TODO (!)
 ```
 
-## Deployment and secrets
+## Colmena: Deployment and secret management
 
 * https://github.com/zhaofengli/colmena#colmena
 
@@ -224,7 +228,7 @@ Filtering:
 - You can filter hosts by tags with `--on @tag-a,@tag-b`.
 - You can use globs in tag matching as well: `colmena apply --on '@infra-*'`
 
-## BTRFS Swap file
+## BTRFS swap file
 
 * https://nixos.wiki/wiki/Btrfs#Swap_file
 * https://wiki.archlinux.org/title/btrfs#Swap_file
@@ -273,21 +277,6 @@ nix-shell --packages appimage-run
 appimage-run ~/Downloads/ubports-installer_0.10.0_linux_x86_64.AppImage
 ```
 
-## System information
-
-```shell
-nix-info -m
-```
-```
- - system: `"x86_64-linux"`
- - host os: `Linux 6.1.51, NixOS, 23.05 (Stoat), 23.05.3242.da5adce0ffaf`
- - multi-user?: `yes`
- - sandbox: `yes`
- - version: `nix-env (Nix) 2.13.5`
- - channels(root): `"nixos-23.05"`
- - nixpkgs: `/nix/var/nix/profiles/per-user/root/channels/nixos`
-```
-
 ## General Notes
 
 * There is controversy about flakes, rather use channels (e.g. with niv)
@@ -309,6 +298,21 @@ Papers about Nix:
 * 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
 
+### System information
+
+```shell
+nix-info -m
+```
+```
+ - system: `"x86_64-linux"`
+ - host os: `Linux 6.1.51, NixOS, 23.05 (Stoat), 23.05.3242.da5adce0ffaf`
+ - multi-user?: `yes`
+ - sandbox: `yes`
+ - version: `nix-env (Nix) 2.13.5`
+ - channels(root): `"nixos-23.05"`
+ - nixpkgs: `/nix/var/nix/profiles/per-user/root/channels/nixos`
+```
+
 ### Search for packages
 
 * https://search.nixos.org/packages?channel=23.05