docs: document hardware generation flags

Author: Mic92

docs/quickstart.md

@@ -47,33 +47,10 @@ into a new directory. This example is tailored for a virtual machine setup
 similar to one on [Hetzner Cloud](https://www.hetzner.com/cloud), so you might
 need to adapt it for your setup.
 
-**Hardware-Specific Configuration**: If you're not using a virtual machine,
-you'll need to generate a custom hardware configuration with
-`nixos-generate-config`.
-
 If you already have a flake, you can use it by adding
 [disko configuration](https://github.com/nix-community/disko?tab=readme-ov-file#how-to-use-disko)
 to it.
 
-#### Get `nixos-generate-config` onto the Target Machine
-
-1. **Option 1**: If NixOS is not installed, boot into an installer without first
-   installing NixOS.
-2. **Option 2**: Use the kexec tarball method, as described
-   [here](https://github.com/nix-community/nixos-images#kexec-tarballs).
-
-#### Generate Configuration
-
-Run the following command on the target machine:
-
-```bash
-nixos-generate-config --no-filesystems --dir /mnt/etc/nixos
-```
-
-This creates the necessary configuration files under `/mnt/etc/nixos/`, which
-you can then customize as needed and copy them to your local machine in order to
-include them in your flake.
-
 ### 3. Configure your SSH key
 
 If you cloned
@@ -128,6 +105,11 @@ and add `--env-password` to the `nixos-anywhere` command.
 
 ### 7. (Optional) Test your NixOS and Disko configuration
 
+Skip this step and continue with Step 8, if you don't have a hardware
+configuration (hardware-configuration.nix or facter.json) generated yet or make
+sure you don't import non-existing hardware-configuration.nix or facter.json
+during running the vm test.
+
 The following command will automatically test your nixos configuration and run
 disko inside a virtual machine, where
 
@@ -142,7 +124,74 @@ disko inside a virtual machine, where
 nix run github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> --vm-test
 ```
 
-### 8. Run it
+### 8. Prepare Hardware Configuration
+
+If you're not using a virtual machine, it's recommended to allow
+`nixos-anywhere` to generate a hardware configuration during installation. This
+ensures that essential drivers, such as those required for disk detection, are
+properly configured.
+
+To enable `nixos-anywhere` to integrate its generated configuration into your
+NixOS setup, you need to include an import for the hardware configuration
+beforehand.
+
+Here’s an example:
+
+```diff
+ nixosConfigurations.generic = nixpkgs.lib.nixosSystem {
+   system = "x86_64-linux";
+   modules = [
+     disko.nixosModules.disko
+     ./configuration.nix
++    ./hardware-configuration.nix
+   ];
+ };
+```
+
+When running `nixos-anywhere`, this file is automatically generated by including
+the following flags in your command:
+`--generate-hardware-config nixos-generate-config ./hardware-configuration.nix`.
+The second flag, `./hardware-configuration.nix`, specifies where
+`nixos-generate-config` will store the configuration. Adjust this path to
+reflect the location where you want the `hardware-configuration.nix` for this
+machine to be saved.
+
+#### 8.1 nixos-facter
+
+As an alternative to `nixos-generate-config`, you can use the experimental
+[nixos-facter](https://github.com/numtide/nixos-facter) command, which offers
+more comprehensive hardware reports and advanced configuration options.
+
+To use `nixos-facter`, add the following to your flake inputs:
+
+```diff
+ {
++ inputs.nixos-facter-modules.url = "github:numtide/nixos-facter-modules";
+ }
+```
+
+Next, import the module into your configuration and specify `facter.json` as the
+path where the hardware report will be saved:
+
+```diff
+ nixosConfigurations.generic-nixos-facter = nixpkgs.lib.nixosSystem {
+   system = "x86_64-linux";
+   modules = [
+     disko.nixosModules.disko
+     ./configuration.nix
++    nixos-facter-modules.nixosModules.facter
++    { config.facter.reportPath = ./facter.json }
+   ];
+ };
+```
+
+To generate the configuration for `nixos-facter` with `nixos-anywhere`, use the
+following flags: `--generate-hardware-config nixos-facter ./facter.json`. The
+second flag, `./facter.json`, specifies where `nixos-generate-config` will store
+the hardware report. Adjust this path to suit the location where you want the
+`facter.json` to be saved.
+
+### 9. Run it
 
 You can now run **nixos-anywhere** from the command line as shown below, where:
 
@@ -167,6 +216,22 @@ named `/home/mydir/test` and the IP address of your target machine is
 nix run github:nix-community/nixos-anywhere -- --flake /home/mydir/test#hetzner-cloud [email protected]
 ```
 
+If you also need to generate hardware configuration amend flags for
+nixos-generate-config:
+
+```
+nix run --generate-hardware-config nixos-generate-config ./hardware-configuration.nix github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
+```
+
+Or these flags if you are using nixos-facter instead:
+
+```
+nix run --generate-hardware-config nixos-facter ./facter.json github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
+```
+
+Adjust the location of `./hardware-configuration.nix` and `./facter.json`
+accordingly.
+
 **nixos-anywhere** will then run, showing various output messages at each stage.
 It may take some time to complete, depending on Internet speeds. It should
 finish by showing the messages below before returning to the command prompt.