Merge pull request #232 from barrucadu/documentation

Add a documentation site

.github/workflows/ci.yaml

@@ -17,3 +17,19 @@ jobs:
           nix run .#fmt
           nix run .#lint
           git diff --exit-code
+      - name: Check mdbook-admonish changes are not committed
+        run: |
+          if grep -q "do not edit: managed by \`mdbook-admonish install\`" docs/book.toml; then
+            echo "remove generated mdbook-admonish lines from docs/books.toml" >&2
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v23
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+      - name: Check documentation site builds
+        run: nix run .#documentation

.github/workflows/deploy-documentation.yml

@@ -0,0 +1,51 @@
+name: Deploy documentation site
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Install nix
+        uses: cachix/install-nix-action@v23
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+      - name: Build
+        run: nix run .#documentation
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -0,0 +1 @@
+/_site

README.markdown

@@ -13,6 +13,8 @@ nix run .#fmt
 nix run .#lint
 ```
 
+See [the documentation](https://nixfiles.docs.barrucadu.co.uk).
+
 [NixOS]: https://nixos.org
 [flakes]: https://nixos.wiki/wiki/Flakes
 
@@ -65,212 +67,6 @@ default.
 
 [wiping `/` on boot]: https://grahamc.com/blog/erase-your-darlings
 
-### Hosts
-
-Currently I have 3 NixOS machines.  The naming convention is:
-
-- **Local machines:** beings (gods, people, etc) of the Cthulhu Mythos.
-- **Remote machines:** places of the Cthulhu Mythos.
-
-#### azathoth
-
-This is my desktop computer.
-
-It dual-boots Windows and NixOS, so it doesn’t run any services, as they won't
-be accessible half of the time.  I don't bother backing up either OS: everything
-I care about is in Syncthing, on GitHub, or on some other cloud service (eg,
-Steam).
-
-#### carcosa
-
-This is a VPS (hosted by Hetzner Cloud).
-
-It serves [barrucadu.co.uk][] and other services on it, such as [a bookdb
-instance][] and [my blog][].  Websites are served with Caddy, with certs from
-Let's Encrypt.
-
-It's set up in "erase your darlings" style, so most of the filesystem is wiped
-on boot and restored from the configuration, to ensure there's no accidentally
-unmanaged configuration or state hanging around.  However, it doesn't reboot
-automatically, because I also use this server for a persistent IRC connection.
-
-[barrucadu.co.uk]: https://www.barrucadu.co.uk/
-[a bookdb instance]: https://bookdb.barrucadu.co.uk/
-[my blog]: https://memo.barrucadu.co.uk/
-
-#### nyarlathotep
-
-This is my home server.
-
-It runs writable instances of the bookdb and bookmarks services, which have any
-updates copied across to carcosa hourly; it acts as a NAS; and it runs a few
-utility services, such as a dashboard of finance information from my hledger
-journal, and a script to automatically tag and organise new podcast episodes or
-CD rips which I copy over to it.
-
-Like carcosa, this host is set up in "erase your darlings" style but, unlike
-carcosa, it automatically reboots to install updates: so that takes effect
-significantly more frequently.
-
-
-Setting up a new host
----------------------
-
-See also [the NixOS installation instructions](https://nixos.org/manual/nixos/stable/index.html#ch-installation).
-
-1. Create & format partitions
-1. **Optional:** Configure wiping / on boot (pre-first-boot steps)
-1. Install NixOS with the standard installer
-1. Reboot into the installed system
-1. Clone this repo to `/etc/nixos`
-1. Move the generated configuration to `hosts/<hostname>/` and edit to fit repo conventions
-1. Add an entry for the host to `flake.nix`
-1. **Optional:** Add DNS records
-1. **Optional:** Configure secrets
-1. **Optional:** Configure wiping / on boot (post-first-boot steps)
-1. **Optional:** Configure backups
-1. **Optional:** Generate SSH key
-1. Build the new system configuration with `sudo nixos-rebuild switch --flake '.#<hostname>'`
-1. Reboot
-1. Commit, push, & merge
-
-### Optional: Configure wiping / on boot
-
-Before installing NixOS, create the `local` pool and datasets:
-
-```bash
-zpool create -o mountpoint=legacy -o autotrim=on local <device>
-
-zfs create -o mountpoint=legacy local/volatile
-zfs create -o mountpoint=legacy local/volatile/root
-
-zfs create -o mountpoint=legacy local/persistent
-zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/home
-zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/nix
-zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/persist
-zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true local/persistent/var-log
-```
-
-Take a snapshot of the empty root dataset:
-
-```bash
-zfs snapshot local/volatile/root@blank
-```
-
-Mount all the filesystems under `/mnt`:
-
-```bash
-mount -t zfs local/volatile/root /mnt
-
-mkdir /mnt/boot
-mkdir /mnt/home
-mkdir /mnt/nix
-mkdir /mnt/persist
-mkdir -p /mnt/var/log
-
-mount /dev/<boot device> /mnt/boot
-mount -t zfs local/persistent/home /mnt/home
-mount -t zfs local/persistent/nix /mnt/nix
-mount -t zfs local/persistent/persist /mnt/persist
-mount -t zfs local/persistent/var-log /mnt/var/log
-```
-
-Then run the installer, making sure to add ZFS details to the generated configuration:
-
-```nix
-networking.hostId = "<random 32-bit hex value>";
-boot.supportedFilesystems = [ "zfs" ];
-```
-
-**After first boot:** copy any needed files (eg, SSH host keys) to the
-appropriate place in `/persist`, add the user password to the secrets, and set
-up `nixfiles.eraseYourDarlings`:
-
-```nix
-nixfiles.eraseYourDarlings.enable = true;
-nixfiles.eraseYourDarlings.machineId = "<contents of /etc/machine-id>";
-nixfiles.eraseYourDarlings.barrucaduPasswordFile = config.sops.secrets."users/barrucadu".path;
-sops.secrets."users/barrucadu".neededForUsers = true;
-```
-
-### Optional: Add DNS records
-
-Add `A` / `AAAA` records to [the ops repo](https://github.com/barrucadu/ops) and
-apply the change via [Concourse](https://cd.barrucadu.dev/).
-
-### Optional: Configure secrets
-
-After first boot, generate an age public key from the host SSH key:
-
-```bash
-nix-shell -p ssh-to-age --run 'ssh-keyscan <hostname>.barrucadu.co.uk | ssh-to-age'
-```
-
-Add a new section with this key to `.sops.yaml`:
-
-```yaml
-creation_rules:
-  ...
-  - path_regex: hosts/<hostname>/secrets(/[^/]+)?\.yaml$
-    key_groups:
-      - age:
-          - *barrucadu
-          - '<key>'
-```
-
-Enable sops in the host configuration:
-
-```nix
-sops.defaultSopsFile = ./secrets.yaml;
-```
-
-### Optional: Configure backups
-
-All hosts which run any sort of service with data I care about should take
-automatic backups.
-
-Firstly, add the backup credentials to the secrets:
-
-```bash
-nix run .#secrets
-```
-
-Then enable backups in the host configuration:
-
-```nix
-nixfiles.backups.enable = true;
-nixfiles.backups.environmentFile = config.sops.secrets."nixfiles/backups/env".path;
-sops.secrets."nixfiles/backups/env" = { };
-```
-
-Most services define their own backup scripts.  For any other needs, write a
-custom script:
-
-```nix
-nixfiles.backups.scripts.<name> = ''
-  <script which copies files to backup to the current working directory>
-'';
-```
-
-### Optional: Generate SSH key
-
-Generate an ed25519 SSH key:
-
-```bash
-ssh-keygen -t ed25519
-```
-
-**If the host should be able to interact with GitHub:** add the public key to
-the GitHub user configuration *as an SSH key*.
-
-**If the host should be able to push commits to GitHub:** add
-the public key to the GitHub user configuration *as a signing key*, and also add
-it to [the allowed_signers
-file](https://github.com/barrucadu/dotfiles/blob/master/dot_config/git/allowed_signers.tmpl).
-
-**If the host should be able to connect to other machines:** add the public key
-to `shared/default.nix`.
-
 
 Tools
 -----

docs/.gitignore

@@ -0,0 +1,9 @@
+book
+
+# generated by the build script
+src/README.md
+src/hosts.md
+src/modules.md
+src/options.md
+src/packages.md
+mdbook-admonish.css

docs/book.toml

@@ -0,0 +1,17 @@
+[book]
+title = "nixfiles"
+authors = ["Michael Walker (barrucadu)"]
+description = "My NixOS configuration and assorted other crap, powered by flakes."
+language = "en"
+multilingual = false
+
+[build]
+create-missing = false
+
+[output.html]
+git-repository-url = "https://github.com/barrucadu/nixfiles"
+cname = "nixfiles.docs.barrucadu.co.uk"
+
+[preprocessor.admonish]
+on_failure = "bail"
+command = "mdbook-admonish"

docs/src/SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+- [README](./README.md)
+
+# Reference
+
+- [Hosts](./hosts.md)
+- [Modules](./modules.md)
+- [Options](./options.md)
+- [Packages](./packages.md)
+
+# Runbooks
+
+- [Set up a new host](./runbooks/set-up-a-new-host.md)