add documentation

This doesn't work yet for reasons that are not entirely clear to me:

    > nix run .#deploy.all --show-trace
    error: 'nixosConfigurations.all.type' is not a string but

sic!

    > nix build .#installers.all
    warning: Git tree '/home/vg/src/simple-nixos-fediverse' is dirty
    error:
           … while calling the 'derivationStrict' builtin

             at /builtin/derivation.nix:9:12: (source not available)

           … while evaluating derivation 'nixos-24.11.20240815.9286249-x86_64-linux.iso'
             whose name attribute is located at /nix/store/nqqkj0pwx2ymv8rxpw1m80zd4fxkvk0s-source/pkgs/stdenv/generic/make-derivation.nix:334:7

           … while evaluating attribute 'sources' of derivation 'nixos-24.11.20240815.9286249-x86_64-linux.iso'

             at /nix/store/nqqkj0pwx2ymv8rxpw1m80zd4fxkvk0s-source/nixos/lib/make-iso9660-image.nix:76:3:

               75|
               76|   sources = map (x: x.source) contents;
                 |   ^
               77|   targets = map (x: x.target) contents;

           (stack trace truncated; use '--show-trace' to show the full trace)

           error: Could not load a value as a module, because it is of type "flake", in file /nix/store/nqqkj0pwx2ymv8rxpw1m80zd4fxkvk0s-source/flake.nix.

???

README.md

@@ -47,6 +47,27 @@ NOTE: it sometimes takes a while for the services to start up, and in the meanti
     pixelfed-manage user:create --name=test --username=test --email=test@test.com --password=testtest --confirm_email=1
     ```
 
+# Building an installer image
+
+Build an installer image for the desired configuration, e.g. for `peertube`:
+
+```bash
+nix build .#installers.peertube
+```
+
+Upload the image in `./result` to Proxmox when creating a VM.
+Booting the image will format the disk and install NixOS with the desired configuration.
+
+# Deploying an updated machine configuration
+
+> TODO: There is currently no way to specify an actual target machine by name.
+
+Assuming you have SSH configuration with access to the remote `root` user stored for a machine called e.g. `peertube`, deploy the configuration by the same name:
+
+```bash
+nix run .#deploy.peertube
+```
+
 ## debugging notes
 
 - it is sometimes useful to `cat result/bin/run-nixos-vm` to see what's really going on (e.g. which ports are getting forwarded)

deploy.nix

@@ -0,0 +1,13 @@
+{ writeShellApplication }:
+name: config:
+writeShellApplication {
+  name = "deploy";
+  text = ''
+    result="$(nix build ${./.}#nixosConfigurations.${name} --eval-store auto --store ssh-ng://${name})"
+    # shellcheck disable=SC2087
+    ssh ${name} << EOF
+    nix-env -p /nix/var/nix/profiles/system --set "$result"
+    "$result"/bin/switch-to-configuration switch
+    EOF
+  '';
+}

flake.lock

@@ -1,6 +1,40 @@
 {
   "nodes": {
+    "disko": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1727249977,
+        "narHash": "sha256-lAqOCDI4B6hA+t+KHSm/Go8hQF/Ob5sgXaIRtMAnMKw=",
+        "owner": "nix-community",
+        "repo": "disko",
+        "rev": "c1c472f4cd91e4b0703e02810a8c7ed30186b6fa",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "disko",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
+      "locked": {
+        "lastModified": 1725194671,
+        "narHash": "sha256-tLGCFEFTB5TaOKkpfw3iYT9dnk4awTP/q4w+ROpMfuw=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "b833ff01a0d694b910daca6e2ff4a3f26dee478c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
       "locked": {
         "lastModified": 1723726852,
         "narHash": "sha256-lRzlx4fPRtzA+dgz9Rh4WK5yAW3TsAXx335DQqxY2XY=",
@@ -18,7 +52,8 @@
     },
     "root": {
       "inputs": {
-        "nixpkgs": "nixpkgs"
+        "disko": "disko",
+        "nixpkgs": "nixpkgs_2"
       }
     }
   },

flake.nix

@@ -3,19 +3,23 @@
 
   inputs = {
     nixpkgs.url = "github:radvendii/nixpkgs/nixos_rebuild_tests";
+    disko.url = "github:nix-community/disko";
   };
 
-  outputs = { self, nixpkgs }:
+  outputs = { self, nixpkgs, disko, ... }:
   let
     system = "x86_64-linux";
     pkgs = nixpkgs.legacyPackages.${system};
   in {
 
     nixosModules = {
+
       ## Fediversity modules
       fediversity = import ./fediversity;
 
       ## VM-specific modules
+      inherit (disko.nixosModules) disko;
+      disk-layout = import ./vm/disk-layout.nix;
       interactive-vm = import ./vm/interactive-vm.nix;
       mastodon-vm = import ./vm/mastodon-vm.nix;
       peertube-vm = import ./vm/peertube-vm.nix;
@@ -25,22 +29,42 @@
     nixosConfigurations = {
       mastodon = nixpkgs.lib.nixosSystem {
         inherit system;
-        modules = with self.nixosModules; [ fediversity interactive-vm mastodon-vm ];
+        modules = with self.nixosModules; [
+          disko
+          disk-layout
+          fediversity
+          interactive-vm
+          mastodon-vm
+        ];
       };
 
       peertube = nixpkgs.lib.nixosSystem {
         inherit system;
-        modules = with self.nixosModules; [ fediversity interactive-vm peertube-vm ];
+        modules = with self.nixosModules; [
+          disko
+          disk-layout
+          fediversity
+          interactive-vm
+          peertube-vm
+        ];
       };
 
       pixelfed = nixpkgs.lib.nixosSystem {
         inherit system;
-        modules = with self.nixosModules; [ fediversity interactive-vm pixelfed-vm ];
+        modules = with self.nixosModules; [
+          disko
+          disk-layout
+          fediversity
+          interactive-vm
+          pixelfed-vm
+        ];
       };
 
       all = nixpkgs.lib.nixosSystem {
         inherit system;
         modules = with self.nixosModules; [
+          disko
+          disk-layout
           fediversity
           interactive-vm
           peertube-vm
@@ -50,13 +74,29 @@
       };
     };
 
+    # build with
+    #     nix build .#installers.<config>
+    installers =
+      let
+        installer = (import ./installer.nix) nixpkgs;
+      in
+      nixpkgs.lib.mapAttrs (_: config: installer config) self.nixosConfigurations;
+
+    # run with
+    #     nix run .#deploy.<machine>
+    deploy =
+      let
+        deployCommand = (pkgs.callPackage ./deploy.nix {});
+      in
+      nixpkgs.lib.mapAttrs (name: config: deployCommand name config) self.nixosConfigurations;
+
     checks.${system} = {
       mastodon-garage = import ./tests/mastodon-garage.nix { inherit pkgs self; };
       pixelfed-garage = import ./tests/pixelfed-garage.nix { inherit pkgs self; };
     };
 
     devShells.${system}.default = pkgs.mkShell {
-      inputs = with pkgs; [
+      packages = with pkgs; [
         nil
       ];
     };

installer.nix

@@ -0,0 +1,29 @@
+/**
+  Convert a NixOS configuration to one for a minimal installer ISO
+
+  WARNING: Running this installer will format the target disk!
+*/
+nixpkgs: machine:
+  let
+    installer = { config, pkgs, ... }:
+      let
+        bootstrap = pkgs.writeShellApplication {
+          name = "bootstrap";
+          runtimeInputs = with pkgs; [ nixos-install-tools ];
+          text = ''
+            ${machine.config.system.build.diskoScript}
+            nixos-install --no-root-password --no-channel-copy --system ${machine.config.system.build.toplevel}
+          '';
+        };
+      in
+      {
+        imports = [
+          "${nixpkgs}/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix"
+        ];
+        nixpkgs.hostPlatform = "x86_64-linux";
+        programs.bash.loginShellInit = ''
+          ${nixpkgs.lib.getBin bootstrap}
+        '';
+      };
+  in
+  (nixpkgs.lib.nixosSystem { modules =  [installer];}).config.system.build.isoImage

shell.nix

@@ -0,0 +1,31 @@
+{ ... }:
+{
+  disko.devices.disk.main = {
+    device = "/dev/sda";
+    type = "disk";
+    content = {
+      type = "gpt";
+      partitions = {
+        ESP = {
+          priority = 1;
+          size = "500M";
+          type = "EF00";
+          content = {
+            type = "filesystem";
+            format = "vfat";
+            mountpoint = "/boot";
+          };
+        };
+        root = {
+          priority = 2;
+          size = "100%";
+          content = {
+            type = "filesystem";
+            format = "ext4";
+            mountpoint = "/";
+          };
+        };
+      };
+    };
+  };
+}

vm/disk-layout.nix

@@ -0,0 +1,36 @@
+{ ... }:
+{
+  disko.devices.disk.main = {
+    device = "/dev/sda";
+    type = "disk";
+    content = {
+      type = "gpt";
+      partitions = {
+        MBR = {
+          priority = 0;
+          size = "1M";
+          type = "EF02";
+        };
+        ESP = {
+          priority = 1;
+          size = "500M";
+          type = "EF00";
+          content = {
+            type = "filesystem";
+            format = "vfat";
+            mountpoint = "/boot";
+          };
+        };
+        root = {
+          priority = 2;
+          size = "100%";
+          content = {
+            type = "filesystem";
+            format = "ext4";
+            mountpoint = "/";
+          };
+        };
+      };
+    };
+  };
+}