From 1fc4739ee33b732f87f9d0bd38e5bf8fb71c4cf1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Fri, 5 Apr 2024 13:08:32 +0200
Subject: [PATCH 01/13] improve starter template

---
 templates/new-clan/flake.nix         | 39 ++++++++++++++++++++++++++++
 templates/new-clan/modules/disko.nix | 36 +++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 templates/new-clan/modules/disko.nix

diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix
index 2f34b17c1..315a88dd5 100644
--- a/templates/new-clan/flake.nix
+++ b/templates/new-clan/flake.nix
@@ -11,6 +11,45 @@
       clan = clan-core.lib.buildClan {
         directory = self;
         clanName = "__CHANGE_ME__";
+        machines = {
+          machine1 = {
+            nixpkgs.hostPlatform = system;
+            imports = [
+              # TODO: boot into the installer
+              # remote> nixos-generate-config --root /tmp/config --no-filesystems
+              # local> mkdir -p ./machines/machine1
+              # local> scp -r root@machine1:/tmp/config ./machines/machine1
+              # local> Edit ./machines/machine1/configuration.nix to your liking
+              ./modules/disko.nix
+              clan-core.clanModules.sshd
+              {
+                # Set this for clan commands use ssh i.e. `clan machines update`
+                clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
+                # remote> lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
+
+                config.disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
+
+                clan.networking.zerotier.controller.enable = true;
+              }
+            ];
+          };
+          machine2 = {
+            nixpkgs.hostPlatform = system;
+            imports = [
+              # ./machines/machine2/configuration.nix
+              ./modules/disko.nix
+              clan-core.clanModules.sshd
+              {
+                # Set this for clan commands use ssh i.e. `clan machines update`
+                clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
+
+                config.disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
+                # local> clan facts generate
+                clan.networking.zerotier.networkId = builtins.readFile ./machines/machine1/facts/zerotier-network-id;
+              }
+            ];
+          };
+        };
       };
     in
     {
diff --git a/templates/new-clan/modules/disko.nix b/templates/new-clan/modules/disko.nix
new file mode 100644
index 000000000..ba8700b69
--- /dev/null
+++ b/templates/new-clan/modules/disko.nix
@@ -0,0 +1,36 @@
+{
+  config.disko.devices = {
+    disk = {
+      main = {
+        type = "disk";
+        device = throw "Change this to your disk device";
+        content = {
+          type = "gpt";
+          partitions = {
+            boot = {
+              size = "1M";
+              type = "EF02"; # for grub MBR
+            };
+            ESP = {
+              size = "512M";
+              type = "EF00";
+              content = {
+                type = "filesystem";
+                format = "vfat";
+                mountpoint = "/boot";
+              };
+            };
+            root = {
+              size = "100%";
+              content = {
+                type = "filesystem";
+                format = "ext4";
+                mountpoint = "/";
+              };
+            };
+          };
+        };
+      };
+    };
+  };
+}

From f2ff815aa74aacea43851c05562a81fe318a4a01 Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Fri, 5 Apr 2024 16:25:05 +0200
Subject: [PATCH 02/13] Add machines/my-machine/settings.json

---
 machines/my-machine/settings.json | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 machines/my-machine/settings.json

diff --git a/machines/my-machine/settings.json b/machines/my-machine/settings.json
new file mode 100644
index 000000000..9e26dfeeb
--- /dev/null
+++ b/machines/my-machine/settings.json
@@ -0,0 +1 @@
+{}
\ No newline at end of file

From 2e29c031ef8db46d970046faff48ab5349b22085 Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Fri, 5 Apr 2024 18:03:14 +0200
Subject: [PATCH 03/13] Improved docs

---
 docs/admins/machines.md           |  32 +++--
 docs/admins/migrate.md            | 181 +++++++++++++++++++++++++
 docs/admins/quickstart.md         | 215 +++++-------------------------
 machines/my-machine/settings.json |   1 -
 4 files changed, 226 insertions(+), 203 deletions(-)
 create mode 100644 docs/admins/migrate.md
 delete mode 100644 machines/my-machine/settings.json

diff --git a/docs/admins/machines.md b/docs/admins/machines.md
index b0de192fb..0bedf297a 100644
--- a/docs/admins/machines.md
+++ b/docs/admins/machines.md
@@ -1,28 +1,26 @@
-# Managing NixOS Machines
+# Managing NixOS Machines with Clan
 
-## Add Your First Machine
+Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
 
-To start managing a new machine, use the following commands to create and then list your machines:
+## Adding Your First Machine
 
-```shellSession
-$ clan machines create my-machine
-$ clan machines list
-my-machine
-```
+Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
 
-## Configure Your Machine
+1. **Create Your Machine**: Generate a new machine configuration using the Clan CLI with the command below:
+
+    ```bash
+    clan machines create my-machine
+    ```
+
+2. **List Available Machines**: Verify the successful addition of your new machine and view any existing machines in your configuration:
+
+    ```bash
+    clan machines list
+    ```
 
-In the example below, we demonstrate how to add a new user named `my-user` and set a password. This user will be configured to log in to the machine `my-machine`.
 
-### Creating a New User
 
-```shellSession
-# Add a new user
-$ clan config --machine my-machine users.users.my-user.isNormalUser true
 
-# Set a password for the user
-$ clan config --machine my-machine users.users.my-user.initialHashedPassword $(mkpasswd)
-```
 
 _Note: The `$(mkpasswd)` command generates a hashed password. Ensure you have the `mkpasswd` utility installed or use an alternative method to generate a secure hashed password._
 
diff --git a/docs/admins/migrate.md b/docs/admins/migrate.md
new file mode 100644
index 000000000..96ee4612d
--- /dev/null
+++ b/docs/admins/migrate.md
@@ -0,0 +1,181 @@
+## **Migrating Existing NixOS Configuration Flake to Clan Core**
+
+Transitioning your existing setup to Clan Core is straightforward with these detailed steps. Follow this guide to ensure a smooth migration.
+
+
+### Before You Begin
+
+1. **Backup Your Current Configuration**: Start by creating a backup of your existing NixOS configuration. This step is crucial as it ensures you have the option to revert to your original setup if necessary.
+
+   ```shellSession
+   cp -r /etc/nixos ~/nixos-backup
+   ```
+
+2. **Initialize flake.nix**: If you haven't yet adopted Nix Flakes in your project, follow these steps to initialize a new `flake.nix` file in your project directory:
+
+   1. **Generate a Trivial flake.nix File**: This creates a basic `flake.nix` file that you can later customize for your project.
+
+      ```bash
+      cd /etc/nixos && nix flake init -t github:NixOS/templates#trivial
+      ```
+
+   2. **Initialize a Git Repository (if necessary)**: If your project isn't already version-controlled with Git, now is a good time to start. This step initializes a new Git repository in your current directory.
+
+      ```bash
+      git init
+      ```
+
+   3. **Add Files to the Repository**: Add your project files to the Git repository. This step is essential for nix flakes as it will ignore files not inside the git repo. 
+
+      ```bash
+      git add .
+      ```
+
+1. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
+
+   ```nix
+   inputs.clan-core = {
+     url = "git+https://git.clan.lol/clan/clan-core";
+     inputs.nixpkgs.follows = "nixpkgs"; # Only if your configuration uses nixpkgs stable.
+   };
+   ```
+
+   Ensure to replace the placeholder URL with the actual Git repository URL for Clan Core. The `inputs.nixpkgs.follows` line indicates that your flake should use the same `nixpkgs` input as your main flake configuration.
+
+2. **Update Outputs**: Modify the `outputs` section of your `flake.nix` to accommodate Clan Core's provisioning method:
+
+   ```diff
+   -  outputs = { self, nixpkgs }: {
+   +  outputs = { self, nixpkgs, clan-core }:
+   ```
+
+3. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
+
+   - Previously:
+
+     ```nix
+     outputs = { self, nixpkgs }: {
+      nixosConfigurations.example-desktop = nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+        modules = [ ./configuration.nix ];
+      };
+     }
+     ```
+
+   - With Clan Core:
+
+     ```nix
+     outputs = { self, nixpkgs, clan-core }:
+      let clan = clan-core.lib.buildClan {
+        directory = self; # Point this to the repository root.
+        clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
+        machines = {
+          example-desktop = {
+            nixpkgs.hostPlatform = "x86_64-linux";
+            imports = [ ./configuration.nix ];
+          };
+        };
+      };
+     in { inherit (clan) nixosConfigurations clanInternals; };
+     ```
+
+4. **Rebuild and Switch**: Apply your updated configuration:
+
+   ```shellSession
+   sudo nixos-rebuild switch --flake /etc/nixos
+   ```
+
+   This rebuilds your system configuration and switches to it. The `--flake .` argument specifies that the current directory's flake should be used.
+
+5. **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
+
+6. **Reboot**: If the build is successful and no issues are detected, reboot your system:
+
+   ```shellSession
+   sudo reboot
+   ```
+
+7. **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
+
+
+## What's next
+
+After creating your flake, you can check out how to add [new machines](./machines.md)
+
+---
+
+
+## Integrating Clan with Flakes using Flake-Parts
+
+Clan supports integration with the Nix ecosystem through its flake module, making it compatible with [flake.parts](https://flake.parts/),
+a tool for modular Nix flakes composition.
+Here's how to set up Clan using flakes and flake-parts.
+
+### 1. Update Your Flake Inputs
+
+To begin, you'll need to add `clan-core` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
+
+
+
+```nix
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
+  inputs.flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
+
+  # Newly added
+  inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
+  inputs.clan-core.inputs.nixpkgs.follows = "nixpkgs";
+  inputs.clan-core.inputs.flake-parts.follows = "flake-parts";
+```
+
+### 2. Import Clan-Core Flake Module
+
+After updating your flake inputs, the next step is to import the `clan-core` flake module into your project. This allows you to utilize Clan functionalities within your Nix project. Update your `flake.nix` file as shown below:
+
+```nix
+  outputs =
+    inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } (
+      {
+        imports = [
+          inputs.clan-core.flakeModules.default
+        ];
+      }
+    );
+```
+
+### 3. Configure Clan Settings and Define Machines
+
+Lastly, define your Clan configuration settings, including a unique clan name and the machines you want to manage with Clan.
+This is where you specify the characteristics of each machine,
+such as the platform and specific Nix configurations. Update your `flake.nix` like this:
+
+```nix
+  outputs =
+    inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } (
+      {
+        imports = [
+          inputs.clan-core.flakeModules.default
+        ];
+        clan = {
+          clanName = "NEEDS_TO_BE_UNIQUE"; # Please replace this with a unique name for your clan.
+          directory = inputs.self;
+          machines = {
+            example-desktop = {
+              nixpkgs.hostPlatform = "x86_64-linux";
+              imports = [ ./configuration.nix ];
+            };
+          };
+        };
+      }
+    );
+```
+
+For detailed information about configuring `flake-parts` and the available options within Clan,
+refer to the Clan module documentation located [here](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix).
+
+### **Next Steps**
+With your flake created, explore how to add new machines by reviewing the documentation provided [here](./machines.md).
+
+---
\ No newline at end of file
diff --git a/docs/admins/quickstart.md b/docs/admins/quickstart.md
index df04d8618..c66a0ba1c 100644
--- a/docs/admins/quickstart.md
+++ b/docs/admins/quickstart.md
@@ -1,200 +1,45 @@
-# Initializing a New Clan Project
+# **Quick Start Guide to Initializing a New Clan Project**
 
-## Create a new flake
+This guide will lead you through initiating a new Clan project
 
-1. To start a new project, execute the following command to add the clan cli to your shell:
+## **Overview**
 
-```shellSession
-$ nix shell git+https://git.clan.lol/clan/clan-core
-```
+Dive into our structured guide tailored to meet your needs:
 
-2. Then use the following commands to initialize a new clan-flake:
-
-```shellSession
-$ clan flakes create my-clan
-```
-
-This action will generate two primary files: `flake.nix` and `.clan-flake`.
-
-```shellSession
-$ ls -la
-drwx------ joerg users   5 B  a minute ago   ./
-drwxrwxrwt root  root  139 B  12 seconds ago ../
-.rw-r--r-- joerg users  77 B  a minute ago   .clan-flake
-.rw-r--r-- joerg users 4.8 KB a minute ago   flake.lock
-.rw-r--r-- joerg users 242 B  a minute ago   flake.nix
-```
-
-### Understanding the .clan-flake Marker File
-
-The `.clan-flake` marker file serves an optional purpose: it helps the `clan-cli` utility locate the project's root directory.
-If `.clan-flake` is missing, `clan-cli` will instead search for other indicators like `.git`, `.hg`, `.svn`, or `flake.nix` to identify the project root.
-
-## What's next
-
-After creating your flake, you can check out how to add [new machines](./machines.md)
+- [**Starting with a New Clan Project**](#starting-with-a-new-clan-project): Kickstart your journey with Clan by setting up a new project from the ground up.
+- [**Migrating Existing Flake Configuration**](migrate.md#migrating-existing-nixos-configuration-flake): Transition your existing flake-based Nix configuration to harness the power of Clan Core.
+- [**Integrating Clan using Flake-Parts**](./migrate.md#integrating-clan-with-flakes-using-flake-parts): Enhance your Clan experience by integrating it with Flake-Parts.
 
 ---
 
-# Migrating Existing NixOS Configuration Flake
+## **Starting with a New Clan Project**
 
-#### Before You Begin
+Embark on your Clan adventure with these initial steps:
 
-1. **Backup Your Current Configuration**: Always start by making a backup of your current NixOS configuration to ensure you can revert if needed.
+### **Step 1: Add Clan CLI to Your Shell**
+Incorporate the Clan CLI into your development workflow with this simple command:
+```shell
+nix shell git+https://git.clan.lol/clan/clan-core
+```
 
-   ```shellSession
-   $ cp -r /etc/nixos ~/nixos-backup
-   ```
+### **Step 2: Initialize Your Project**
+Set the foundation of your Clan project by initializing it as follows:
+```shell
+clan flakes create my-clan
+```
+This command crafts the essential `flake.nix` and `.clan-flake` files for your project.
 
-2. **Update Flake Inputs**: Add a new input for the `clan-core` dependency:
+### **Step 3: Verify the Project Structure**
+Ensure the creation of your project files with a quick directory listing:
+```shell
+cd my-clan && ls -la
+```
+Look for `.clan-flake`, `flake.lock`, and `flake.nix` among your files to confirm successful setup.
 
-   ```nix
-   inputs.clan-core = {
-     url = "git+https://git.clan.lol/clan/clan-core";
-     # Don't do this if your machines are on nixpkgs stable.
-     inputs.nixpkgs.follows = "nixpkgs";
-   };
-   ```
+### **Understanding `.clan-flake`**
+The `.clan-flake` file, while optional, is instrumental in helping the Clan CLI identify your project's root directory, easing project management.
 
-   - `url`: Specifies the Git repository URL for Clan Core.
-   - `inputs.nixpkgs.follows`: Tells Nix to use the same `nixpkgs` input as your main input (in this case, it follows `nixpkgs`).
-
-3. **Update Outputs**: Then modify the `outputs` section of your `flake.nix` to adapt to Clan Core's new provisioning method. The key changes are as follows:
-
-   Add `clan-core` to the output
-
-   ```diff
-   -  outputs = { self, nixpkgs,  }:
-   +  outputs = { self, nixpkgs, clan-core }:
-   ```
-
-   Previous configuration:
-
-   ```nix
-   {
-     nixosConfigurations.example-desktop = nixpkgs.lib.nixosSystem {
-       system = "x86_64-linux";
-       modules = [
-           ./configuration.nix
-       ];
-       [...]
-     };
-   }
-   ```
-
-   After change:
-
-   ```nix
-   let clan = clan-core.lib.buildClan {
-     # this needs to point at the repository root
-     directory = self;
-     specialArgs = {};
-     clanName = "NEEDS_TO_BE_UNIQUE"; # TODO: Changeme
-     machines = {
-       example-desktop = {
-         nixpkgs.hostPlatform = "x86_64-linux";
-         imports = [ ./configuration.nix ];
-       };
-     };
-   };
-   in { inherit (clan) nixosConfigurations clanInternals; }
-   ```
-
-   - `nixosConfigurations`: Defines NixOS configurations, using Clan Core’s `buildClan` function to manage the machines.
-   - Inside `machines`, a new machine configuration is defined (in this case, `example-desktop`).
-   - Inside `example-desktop` which is the target machine hostname, `nixpkgs.hostPlatform` specifies the host platform as `x86_64-linux`.
-   - `clanInternals`: Is required to enable evaluation of the secret generation/upload script on every architecture
-   - `clanName`: Is required and needs to be globally unique, as else we have a cLAN name clash
-
-4. **Rebuild and Switch**: Rebuild your NixOS configuration using the updated flake:
-
-   ```shellSession
-   $ sudo nixos-rebuild switch --flake .
-   ```
-
-   - This command rebuilds and switches to the new configuration. Make sure to include the `--flake .` argument to use the current directory as the flake source.
-
-5. **Test Configuration**: Before rebooting, verify that your new configuration builds without errors or warnings.
-
-6. **Reboot**: If everything is fine, you can reboot your system to apply the changes:
-
-   ```shellSession
-   $ sudo reboot
-   ```
-
-7. **Verify**: After the reboot, confirm that your system is running with the new configuration, and all services and applications are functioning as expected.
-
-By following these steps, you've successfully migrated your NixOS Flake configuration to include the `clan-core` input and adapted the `outputs` section to work with Clan Core's new machine provisioning method.
-
-## What's next
-
-After creating your flake, you can check out how to add [new machines](./machines.md)
+### **Next Steps**
+Ready to expand? Explore how to add new machines to your project with the helpful documentation [here](./machines.md).
 
 ---
-
-# Integrating Clan with Flakes using Flake-Parts
-
-Clan supports integration with the Nix ecosystem through its flake module, making it compatible with [flake.parts](https://flake.parts/),
-a tool for modular Nix flakes composition.
-Here's how to set up Clan using flakes and flake-parts.
-
-### 1. Update Your Flake Inputs
-
-To begin, you'll need to add `clan-core` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
-
-```diff
-  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
-  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
-  inputs.flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
-
-+ inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
-+ inputs.clan-core.inputs.nixpkgs.follows = "nixpkgs";
-+ inputs.clan-core.inputs.flake-parts.follows = "flake-parts";
-```
-
-### 2. Import Clan-Core Flake Module
-
-After updating your flake inputs, the next step is to import the `clan-core` flake module into your project. This allows you to utilize Clan functionalities within your Nix project. Update your `flake.nix` file as shown below:
-
-```nix
-  outputs =
-    inputs@{ flake-parts, ... }:
-    flake-parts.lib.mkFlake { inherit inputs; } (
-      {
-        imports = [
-          inputs.clan-core.flakeModules.default
-        ];
-      }
-    );
-```
-
-### 3. Configure Clan Settings and Define Machines
-
-Lastly, define your Clan configuration settings, including a unique clan name and the machines you want to manage with Clan.
-This is where you specify the characteristics of each machine,
-such as the platform and specific Nix configurations. Update your `flake.nix` like this:
-
-```nix
-  outputs =
-    inputs@{ flake-parts, ... }:
-    flake-parts.lib.mkFlake { inherit inputs; } (
-      {
-        imports = [
-          inputs.clan-core.flakeModules.default
-        ];
-        clan = {
-          clanName = "NEEDS_TO_BE_UNIQUE"; # Please replace this with a unique name for your clan.
-          directory = inputs.self;
-          machines = {
-            example-desktop = {
-              nixpkgs.hostPlatform = "x86_64-linux";
-              imports = [ ./configuration.nix ];
-            };
-          };
-        };
-      }
-    );
-```
-
-For detailed information about configuring `flake-parts` and the available options within Clan,
-refer to the Clan module documentation located [here](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix).
diff --git a/machines/my-machine/settings.json b/machines/my-machine/settings.json
deleted file mode 100644
index 9e26dfeeb..000000000
--- a/machines/my-machine/settings.json
+++ /dev/null
@@ -1 +0,0 @@
-{}
\ No newline at end of file

From e68eba914e7acd394501e53cb854693d75b8507f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Fri, 5 Apr 2024 13:08:32 +0200
Subject: [PATCH 04/13] improve starter template

---
 templates/new-clan/flake.nix         | 39 ++++++++++++++++++++++++++++
 templates/new-clan/modules/disko.nix | 36 +++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 templates/new-clan/modules/disko.nix

diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix
index 2f34b17c1..315a88dd5 100644
--- a/templates/new-clan/flake.nix
+++ b/templates/new-clan/flake.nix
@@ -11,6 +11,45 @@
       clan = clan-core.lib.buildClan {
         directory = self;
         clanName = "__CHANGE_ME__";
+        machines = {
+          machine1 = {
+            nixpkgs.hostPlatform = system;
+            imports = [
+              # TODO: boot into the installer
+              # remote> nixos-generate-config --root /tmp/config --no-filesystems
+              # local> mkdir -p ./machines/machine1
+              # local> scp -r root@machine1:/tmp/config ./machines/machine1
+              # local> Edit ./machines/machine1/configuration.nix to your liking
+              ./modules/disko.nix
+              clan-core.clanModules.sshd
+              {
+                # Set this for clan commands use ssh i.e. `clan machines update`
+                clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
+                # remote> lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
+
+                config.disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
+
+                clan.networking.zerotier.controller.enable = true;
+              }
+            ];
+          };
+          machine2 = {
+            nixpkgs.hostPlatform = system;
+            imports = [
+              # ./machines/machine2/configuration.nix
+              ./modules/disko.nix
+              clan-core.clanModules.sshd
+              {
+                # Set this for clan commands use ssh i.e. `clan machines update`
+                clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
+
+                config.disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
+                # local> clan facts generate
+                clan.networking.zerotier.networkId = builtins.readFile ./machines/machine1/facts/zerotier-network-id;
+              }
+            ];
+          };
+        };
       };
     in
     {
diff --git a/templates/new-clan/modules/disko.nix b/templates/new-clan/modules/disko.nix
new file mode 100644
index 000000000..ba8700b69
--- /dev/null
+++ b/templates/new-clan/modules/disko.nix
@@ -0,0 +1,36 @@
+{
+  config.disko.devices = {
+    disk = {
+      main = {
+        type = "disk";
+        device = throw "Change this to your disk device";
+        content = {
+          type = "gpt";
+          partitions = {
+            boot = {
+              size = "1M";
+              type = "EF02"; # for grub MBR
+            };
+            ESP = {
+              size = "512M";
+              type = "EF00";
+              content = {
+                type = "filesystem";
+                format = "vfat";
+                mountpoint = "/boot";
+              };
+            };
+            root = {
+              size = "100%";
+              content = {
+                type = "filesystem";
+                format = "ext4";
+                mountpoint = "/";
+              };
+            };
+          };
+        };
+      };
+    };
+  };
+}

From a52011658406bc01ef8804befc99e51e8122d187 Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Sat, 6 Apr 2024 11:54:34 +0200
Subject: [PATCH 05/13] Improve documentation

---
 docs/admins/machines.md                       | 31 ---------
 docs/admins/migrate.md                        | 69 +++++++++++++------
 pkgs/clan-cli/clan_cli/flakes/create.py       |  2 +-
 templates/new-clan/flake.nix                  |  8 ++-
 .../new-clan/machines/jon/configuration.nix   |  4 ++
 .../new-clan/machines/sara/configuration.nix  |  4 ++
 6 files changed, 62 insertions(+), 56 deletions(-)
 create mode 100644 templates/new-clan/machines/jon/configuration.nix
 create mode 100644 templates/new-clan/machines/sara/configuration.nix

diff --git a/docs/admins/machines.md b/docs/admins/machines.md
index 0bedf297a..3d986d870 100644
--- a/docs/admins/machines.md
+++ b/docs/admins/machines.md
@@ -2,37 +2,6 @@
 
 Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
 
-## Adding Your First Machine
-
-Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
-
-1. **Create Your Machine**: Generate a new machine configuration using the Clan CLI with the command below:
-
-    ```bash
-    clan machines create my-machine
-    ```
-
-2. **List Available Machines**: Verify the successful addition of your new machine and view any existing machines in your configuration:
-
-    ```bash
-    clan machines list
-    ```
-
-
-
-
-
-_Note: The `$(mkpasswd)` command generates a hashed password. Ensure you have the `mkpasswd` utility installed or use an alternative method to generate a secure hashed password._
-
-## Test Your Machine Configuration Inside a VM
-
-Before deploying your configuration to a live environment, you can run a virtual machine (VM) to test the settings:
-
-```shellSession
-$ clan vms run my-machine
-```
-
-This command run a VM based on the configuration of `my-machine`, allowing you to verify changes in a controlled environment.
 
 ## Installing a New Machine
 
diff --git a/docs/admins/migrate.md b/docs/admins/migrate.md
index 96ee4612d..24db42841 100644
--- a/docs/admins/migrate.md
+++ b/docs/admins/migrate.md
@@ -31,35 +31,51 @@ Transitioning your existing setup to Clan Core is straightforward with these det
       git add .
       ```
 
-1. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
+
+3. **Create Machines Directory**: Create a machines directory where you put all machine specific nix configs like the configuration.nix
+    1. Create the machines directory in your git root example: `/etc/nixos/machines/`
+        ```bash
+        mkdir machines
+        ```
+
+    2. Inside the machines directory create a directory named after the hostname of the machine you want to manage with clan.
+        ```bash
+        mkdir machines/jons-desktop
+        ```
+
+    3. Move your `configuration.nix` and included files into  `machines/jons-desktop`
+        ```bash
+        mv configuration.nix machines/jons-desktop/configuration.nix 
+        ```
+
+    4. Git add your new machines folder
+        ```bash
+        git add machines
+        ```
+
+4. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
 
    ```nix
    inputs.clan-core = {
      url = "git+https://git.clan.lol/clan/clan-core";
-     inputs.nixpkgs.follows = "nixpkgs"; # Only if your configuration uses nixpkgs stable.
+     inputs.nixpkgs.follows = "nixpkgs"; # Only if your configuration uses nixpkgs unstable.
    };
    ```
 
    Ensure to replace the placeholder URL with the actual Git repository URL for Clan Core. The `inputs.nixpkgs.follows` line indicates that your flake should use the same `nixpkgs` input as your main flake configuration.
 
-2. **Update Outputs**: Modify the `outputs` section of your `flake.nix` to accommodate Clan Core's provisioning method:
 
-   ```diff
-   -  outputs = { self, nixpkgs }: {
-   +  outputs = { self, nixpkgs, clan-core }:
-   ```
-
-3. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
+5. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
 
    - Previously:
 
      ```nix
      outputs = { self, nixpkgs }: {
-      nixosConfigurations.example-desktop = nixpkgs.lib.nixosSystem {
+      nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
         system = "x86_64-linux";
         modules = [ ./configuration.nix ];
       };
-     }
+     };
      ```
 
    - With Clan Core:
@@ -70,37 +86,48 @@ Transitioning your existing setup to Clan Core is straightforward with these det
         directory = self; # Point this to the repository root.
         clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
         machines = {
-          example-desktop = {
+          jons-desktop = {
             nixpkgs.hostPlatform = "x86_64-linux";
-            imports = [ ./configuration.nix ];
+            imports = [
+              clan-core.clanModules.sshd ## Add openssh server for clan management
+              ./machines/jons-desktop/configuration.nix
+            ];
           };
         };
       };
      in { inherit (clan) nixosConfigurations clanInternals; };
      ```
 
-4. **Rebuild and Switch**: Apply your updated configuration:
+
+
+6. **Rebuild and Switch**: Apply your updated configuration:
 
    ```shellSession
    sudo nixos-rebuild switch --flake /etc/nixos
    ```
 
-   This rebuilds your system configuration and switches to it. The `--flake .` argument specifies that the current directory's flake should be used.
+   This rebuilds your system configuration and switches to it. The `--flake /etc/nixos` argument specifies that the `/etc/nixos` directory's flake should be used.
 
-5. **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
+7. **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
 
-6. **Reboot**: If the build is successful and no issues are detected, reboot your system:
+8. **Reboot**: If the build is successful and no issues are detected, reboot your system:
 
    ```shellSession
    sudo reboot
    ```
 
-7. **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
+9. **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
+
+
+# TODO:
+* How do I use clan machines install to setup my current machine?
+* I probably need the clan-core sshd module for that?
+* We need to tell them that configuration.nix of a machine NEEDS to be under the directory CLAN_ROOT/machines/<machine-name> I think?
 
 
 ## What's next
 
-After creating your flake, you can check out how to add [new machines](./machines.md)
+After creating your clan checkout [managing machines](./machines.md)
 
 ---
 
@@ -159,10 +186,10 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
           inputs.clan-core.flakeModules.default
         ];
         clan = {
-          clanName = "NEEDS_TO_BE_UNIQUE"; # Please replace this with a unique name for your clan.
+          clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
           directory = inputs.self;
           machines = {
-            example-desktop = {
+            jons-desktop = {
               nixpkgs.hostPlatform = "x86_64-linux";
               imports = [ ./configuration.nix ];
             };
diff --git a/pkgs/clan-cli/clan_cli/flakes/create.py b/pkgs/clan-cli/clan_cli/flakes/create.py
index bfd219613..a7f8ca203 100644
--- a/pkgs/clan-cli/clan_cli/flakes/create.py
+++ b/pkgs/clan-cli/clan_cli/flakes/create.py
@@ -6,7 +6,7 @@ from ..cmd import CmdOut, run
 from ..errors import ClanError
 from ..nix import nix_command, nix_shell
 
-DEFAULT_URL: str = "git+https://git.clan.lol/clan/clan-core?new-clan"
+DEFAULT_URL: str = "git+https://git.clan.lol/clan/clan-core"
 
 
 def create_flake(directory: Path, url: str) -> dict[str, CmdOut]:
diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix
index 315a88dd5..879e4aaa0 100644
--- a/templates/new-clan/flake.nix
+++ b/templates/new-clan/flake.nix
@@ -10,9 +10,9 @@
       pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
       clan = clan-core.lib.buildClan {
         directory = self;
-        clanName = "__CHANGE_ME__";
+        clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
         machines = {
-          machine1 = {
+          jon = {
             nixpkgs.hostPlatform = system;
             imports = [
               # TODO: boot into the installer
@@ -21,6 +21,7 @@
               # local> scp -r root@machine1:/tmp/config ./machines/machine1
               # local> Edit ./machines/machine1/configuration.nix to your liking
               ./modules/disko.nix
+              ./machines/jon/configuration.nix
               clan-core.clanModules.sshd
               {
                 # Set this for clan commands use ssh i.e. `clan machines update`
@@ -33,11 +34,12 @@
               }
             ];
           };
-          machine2 = {
+          sara = {
             nixpkgs.hostPlatform = system;
             imports = [
               # ./machines/machine2/configuration.nix
               ./modules/disko.nix
+              ./machines/sara/configuration.nix
               clan-core.clanModules.sshd
               {
                 # Set this for clan commands use ssh i.e. `clan machines update`
diff --git a/templates/new-clan/machines/jon/configuration.nix b/templates/new-clan/machines/jon/configuration.nix
new file mode 100644
index 000000000..4f4aa69b7
--- /dev/null
+++ b/templates/new-clan/machines/jon/configuration.nix
@@ -0,0 +1,4 @@
+{config, clan, lib, pkgs, ...}:
+{
+
+}
\ No newline at end of file
diff --git a/templates/new-clan/machines/sara/configuration.nix b/templates/new-clan/machines/sara/configuration.nix
new file mode 100644
index 000000000..4f4aa69b7
--- /dev/null
+++ b/templates/new-clan/machines/sara/configuration.nix
@@ -0,0 +1,4 @@
+{config, clan, lib, pkgs, ...}:
+{
+
+}
\ No newline at end of file

From 6d8d21196876f424a470ff7aa24efa32587c83f9 Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Sat, 6 Apr 2024 12:34:49 +0200
Subject: [PATCH 06/13] Improve documentation

---
 docs/admins/migrate.md                             | 9 +++++++--
 templates/new-clan/flake.nix                       | 1 +
 templates/new-clan/machines/jon/configuration.nix  | 4 ++--
 templates/new-clan/machines/sara/configuration.nix | 4 ++--
 4 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/admins/migrate.md b/docs/admins/migrate.md
index 24db42841..41edc66da 100644
--- a/docs/admins/migrate.md
+++ b/docs/admins/migrate.md
@@ -83,13 +83,14 @@ Transitioning your existing setup to Clan Core is straightforward with these det
      ```nix
      outputs = { self, nixpkgs, clan-core }:
       let clan = clan-core.lib.buildClan {
+        specialArgs = { }; # Add arguments to every nix import in here
         directory = self; # Point this to the repository root.
         clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
         machines = {
           jons-desktop = {
             nixpkgs.hostPlatform = "x86_64-linux";
             imports = [
-              clan-core.clanModules.sshd ## Add openssh server for clan management
+              clan-core.clanModules.sshd # Add openssh server for clan management
               ./machines/jons-desktop/configuration.nix
             ];
           };
@@ -186,12 +187,16 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
           inputs.clan-core.flakeModules.default
         ];
         clan = {
+          specialArgs = { }; # Add arguments to every nix import in here
           clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
           directory = inputs.self;
           machines = {
             jons-desktop = {
               nixpkgs.hostPlatform = "x86_64-linux";
-              imports = [ ./configuration.nix ];
+              imports = [
+                clan-core.clanModules.sshd # Add openssh server for clan management
+                ./configuration.nix
+              ];
             };
           };
         };
diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix
index 879e4aaa0..04ded52be 100644
--- a/templates/new-clan/flake.nix
+++ b/templates/new-clan/flake.nix
@@ -9,6 +9,7 @@
       system = "x86_64-linux";
       pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
       clan = clan-core.lib.buildClan {
+        specialArgs = { }; # Add arguments to every nix import in here
         directory = self;
         clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
         machines = {
diff --git a/templates/new-clan/machines/jon/configuration.nix b/templates/new-clan/machines/jon/configuration.nix
index 4f4aa69b7..facb35d6f 100644
--- a/templates/new-clan/machines/jon/configuration.nix
+++ b/templates/new-clan/machines/jon/configuration.nix
@@ -1,4 +1,4 @@
-{config, clan, lib, pkgs, ...}:
+{ ... }:
 {
 
-}
\ No newline at end of file
+}
diff --git a/templates/new-clan/machines/sara/configuration.nix b/templates/new-clan/machines/sara/configuration.nix
index 4f4aa69b7..facb35d6f 100644
--- a/templates/new-clan/machines/sara/configuration.nix
+++ b/templates/new-clan/machines/sara/configuration.nix
@@ -1,4 +1,4 @@
-{config, clan, lib, pkgs, ...}:
+{ ... }:
 {
 
-}
\ No newline at end of file
+}

From 033f7c67f4f541a584b860c560e8cf5ac95c6897 Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Sat, 6 Apr 2024 13:34:40 +0200
Subject: [PATCH 07/13] Improve documentation

---
 docs/admins/machines.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/admins/machines.md b/docs/admins/machines.md
index 3d986d870..c108dd91c 100644
--- a/docs/admins/machines.md
+++ b/docs/admins/machines.md
@@ -3,6 +3,15 @@
 Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
 
 
+
+# TODO:
+* clan facts generate
+* clan machine check / build (CI is missing)
+* TODO: How to join others people zerotier
+  * `services.zerotier.joinNetworks = [ "network-id" ]`
+* Approve over webinterface or cli
+
+
 ## Installing a New Machine
 
 Clan CLI, in conjunction with [nixos-anywhere](https://github.com/nix-community/nixos-anywhere), provides a seamless method for installing NixOS on various machines.

From 6a610c7a0b55f88c8be7b6935b5df6d0dc47f717 Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Sat, 6 Apr 2024 13:35:17 +0200
Subject: [PATCH 08/13] Improve documentation

---
 docs/admins/machines.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/admins/machines.md b/docs/admins/machines.md
index c108dd91c..08cbd7f07 100644
--- a/docs/admins/machines.md
+++ b/docs/admins/machines.md
@@ -9,7 +9,7 @@ Begin your journey in machine management by introducing a new machine into your
 * clan machine check / build (CI is missing)
 * TODO: How to join others people zerotier
   * `services.zerotier.joinNetworks = [ "network-id" ]`
-* Approve over webinterface or cli
+* Controler needs to approve over webinterface or cli
 
 
 ## Installing a New Machine

From 49d83fd65970dc8d05a0b41d9f043598b9306ceb Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Sun, 7 Apr 2024 12:53:15 +0200
Subject: [PATCH 09/13] migrate.md: make docs more approachable

---
 docs/admins/migrate.md | 327 +++++++++++++++++++++++++++--------------
 1 file changed, 213 insertions(+), 114 deletions(-)

diff --git a/docs/admins/migrate.md b/docs/admins/migrate.md
index 41edc66da..900f52387 100644
--- a/docs/admins/migrate.md
+++ b/docs/admins/migrate.md
@@ -1,164 +1,253 @@
-## **Migrating Existing NixOS Configuration Flake to Clan Core**
+# Migrating Existing NixOS Configuration Flake to Clan Core
 
-Transitioning your existing setup to Clan Core is straightforward with these detailed steps. Follow this guide to ensure a smooth migration.
+Transitioning your existing setup to Clan Core is easy and straightforward. Follow this guide to ensure a smooth migration.
 
+## 0. Prerequisites
 
-### Before You Begin
+### Backup Your Current Configuration
 
-1. **Backup Your Current Configuration**: Start by creating a backup of your existing NixOS configuration. This step is crucial as it ensures you have the option to revert to your original setup if necessary.
+Create a backup of your existing NixOS configuration.
+This step ensures you have the option to revert to your original setup if necessary.
 
-   ```shellSession
-   cp -r /etc/nixos ~/nixos-backup
-   ```
+```bash
+cp -r /etc/nixos ~/nixos-backup
+```
 
-2. **Initialize flake.nix**: If you haven't yet adopted Nix Flakes in your project, follow these steps to initialize a new `flake.nix` file in your project directory:
+## 1. Initialize a flake.nix
 
-   1. **Generate a Trivial flake.nix File**: This creates a basic `flake.nix` file that you can later customize for your project.
+If you haven't yet adopted Nix Flakes in your project, follow these steps to initialize a new `flake.nix` file in your project directory.
 
-      ```bash
-      cd /etc/nixos && nix flake init -t github:NixOS/templates#trivial
-      ```
+> Note: Clan is based on flakes, it is possible to use cLan without flakes but not officially supported yet.
 
-   2. **Initialize a Git Repository (if necessary)**: If your project isn't already version-controlled with Git, now is a good time to start. This step initializes a new Git repository in your current directory.
+### Generate a Trivial flake.nix File
 
-      ```bash
-      git init
-      ```
+This creates a basic `flake.nix` file that you can later customize for your project.
+  
+Create a place for your system configuration if you don't have one already. We'll create `~/clans/empire`.
+In this example, we're setting up a directory named `empire` inside a `clans` folder in your home directory. This is just an example, and you can name and place your project directory as it suits your organizational preferences.
 
-   3. **Add Files to the Repository**: Add your project files to the Git repository. This step is essential for nix flakes as it will ignore files not inside the git repo. 
+```bash
+mkdir -p ~/clans/empire && cd ~/clans/empire 
+nix flake init -t github:NixOS/templates#trivial
+```
 
-      ```bash
-      git add .
-      ```
+This will initialize a `flake.nix` file that looks like this:
 
+```nix
+# flake.nix
+{
+  description = "A very basic flake";
 
-3. **Create Machines Directory**: Create a machines directory where you put all machine specific nix configs like the configuration.nix
-    1. Create the machines directory in your git root example: `/etc/nixos/machines/`
-        ```bash
-        mkdir machines
-        ```
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+  };
 
-    2. Inside the machines directory create a directory named after the hostname of the machine you want to manage with clan.
-        ```bash
-        mkdir machines/jons-desktop
-        ```
+  outputs = { self, nixpkgs }: {
 
-    3. Move your `configuration.nix` and included files into  `machines/jons-desktop`
-        ```bash
-        mv configuration.nix machines/jons-desktop/configuration.nix 
-        ```
+    packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
 
-    4. Git add your new machines folder
-        ```bash
-        git add machines
-        ```
+    packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
 
-4. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
+  };
+}
+```
 
-   ```nix
-   inputs.clan-core = {
-     url = "git+https://git.clan.lol/clan/clan-core";
-     inputs.nixpkgs.follows = "nixpkgs"; # Only if your configuration uses nixpkgs unstable.
-   };
-   ```
+### Initialize a Git Repository (optional/recommended)
 
-   Ensure to replace the placeholder URL with the actual Git repository URL for Clan Core. The `inputs.nixpkgs.follows` line indicates that your flake should use the same `nixpkgs` input as your main flake configuration.
+If your project isn't already version-controlled with Git, now is a good time to start. This step initializes a new Git repository in your current directory.
 
+```bash
+git init && git add .
+```
 
-5. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
+> Note: adding all files to the git index is essential for `nix flakes` as `flakes` ignores source files that are not part of the git index.
 
-   - Previously:
+Confirm your flake repository is working:
 
-     ```nix
-     outputs = { self, nixpkgs }: {
-      nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
-        system = "x86_64-linux";
-        modules = [ ./configuration.nix ];
-      };
-     };
-     ```
+```bash
+nix flake show
+```
 
-   - With Clan Core:
+```bash
+warning: creating lock file flake.lock'
+path: <some/hash> 
+└───packages
+    └───x86_64-linux
+        ├───default: package 'hello-2.12.1'
+        └───hello: package 'hello-2.12.1'
+```
 
-     ```nix
-     outputs = { self, nixpkgs, clan-core }:
-      let clan = clan-core.lib.buildClan {
-        specialArgs = { }; # Add arguments to every nix import in here
-        directory = self; # Point this to the repository root.
-        clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
-        machines = {
-          jons-desktop = {
-            nixpkgs.hostPlatform = "x86_64-linux";
-            imports = [
-              clan-core.clanModules.sshd # Add openssh server for clan management
-              ./machines/jons-desktop/configuration.nix
-            ];
-          };
+## 2. Create your first Machine
+
+Create a directory where you put **all machine specific configs** like the `configuration.nix` or `hardware-configuration.nix`
+
+> Following this structure will allow you nicely organize all your different machines and allows the cLan-CLI to automatically detect and manage your machines.
+
+```bash
+mkdir -p machines/jons-desktop
+```
+
+> In this case `jons-desktop` is the hostname of the machine you want to manage with cLan.
+
+Move your `configuration.nix` and included files into `machines/jons-desktop`
+
+```bash
+mv configuration.nix machines/jons-desktop/configuration.nix 
+```
+
+Git add all new files/folders
+
+```bash
+git add machines
+```
+
+### Migrate to flakes and `buildClan`
+
+Add `Clan Core` as a new input to your `flake.nix`:
+
+```nix
+# flake.nix
+inputs.clan-core = {
+  url = "git+https://git.clan.lol/clan/clan-core";
+  inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
+}
+```
+
+Your flake should now look something like this.
+
+```nix
+# flake.nix
+{
+  inputs = {
+    # Change ref to your liking
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+
+    clan-core = {
+      url = "git+https://git.clan.lol/clan/clan-core";
+      inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
+    };
+  };
+
+  outputs = { self, nixpkgs, clan-core }: {
+  # ...
+  };
+}
+```
+
+> Note: `inputs.nixpkgs.follows` ensures that `clan-core` uses the same `nixpkgs` version as the rest of your flake.
+
+### Use `clan-core.lib.buildClan` for declaring your machines
+
+If you used flakes already you might use `lib.nixosSystem`
+
+```nix
+# OLD
+
+# flake.nix
+outputs = { self, nixpkgs }: {
+  nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
+    system = "x86_64-linux";
+    modules = [ ./configuration.nix ];
+  };
+}
+```
+
+We explain how to setup `buildClan`
+
+```nix
+# flake.nix
+outputs = { self, nixpkgs, clan-core }:
+  let 
+    clan = clan-core.lib.buildClan {
+      ## Clan wide settings. (Required)
+      clanName = "__CHANGE_ME__"; # Ensure to choose a unique name.
+      directory = self; # Point this to the repository root.
+
+      specialArgs = { }; # Add arguments to every nix import in here
+      machines = {
+        jons-desktop = {
+          nixpkgs.hostPlatform = "x86_64-linux";
+          imports = [
+            ./machines/jons-desktop/configuration.nix
+            clan-core.clanModules.sshd # Add openssh server forcLanmanagement
+          ];
         };
       };
-     in { inherit (clan) nixosConfigurations clanInternals; };
-     ```
+    };
+  in
+  { 
+    inherit (clan) nixosConfigurations clanInternals; 
+  };
+```
 
+## Rebuild and Switch
 
+Apply your updated configuration
 
-6. **Rebuild and Switch**: Apply your updated configuration:
+Before we can rebuild the system we should replace the source of your system ( folder `/etc/nixos`) with a symlink to the `repo`
 
-   ```shellSession
-   sudo nixos-rebuild switch --flake /etc/nixos
-   ```
+```bash
+sudo ls -s ~/clans/empire /etc/nixos
+```
 
-   This rebuilds your system configuration and switches to it. The `--flake /etc/nixos` argument specifies that the `/etc/nixos` directory's flake should be used.
+```bash
+sudo nixos-rebuild switch
+```
 
-7. **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
+This rebuilds your system configuration and switches to it.
 
-8. **Reboot**: If the build is successful and no issues are detected, reboot your system:
+> Note: nixos-rebuild switch uses /etc/nixos by default.
 
-   ```shellSession
-   sudo reboot
-   ```
+## Finish installation
 
-9. **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
+- **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
+- **Reboot**: If the build is successful and no issues are detected, reboot your system:
 
+  ```shellSession
+  sudo reboot
+  ```
 
-# TODO:
-* How do I use clan machines install to setup my current machine?
-* I probably need the clan-core sshd module for that?
-* We need to tell them that configuration.nix of a machine NEEDS to be under the directory CLAN_ROOT/machines/<machine-name> I think?
-
-
-## What's next
-
-After creating your clan checkout [managing machines](./machines.md)
+- **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
 
 ---
 
+## What's next?
 
-## Integrating Clan with Flakes using Flake-Parts
+After creating your cLan see [managing machines](./machines.md)
+
+Or continue with **flake-parts integration**
+
+## Integrating Clan with Flakes using `flake-parts``
+
+Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows modular compositions.
 
-Clan supports integration with the Nix ecosystem through its flake module, making it compatible with [flake.parts](https://flake.parts/),
-a tool for modular Nix flakes composition.
 Here's how to set up Clan using flakes and flake-parts.
 
 ### 1. Update Your Flake Inputs
 
-To begin, you'll need to add `clan-core` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
-
-
+To begin, you'll need to add `flake-parts` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
 
 ```nix
-  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
-  inputs.flake-parts.url = "github:hercules-ci/flake-parts";
-  inputs.flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
+# flake.nix
+inputs = {
+  nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
 
-  # Newly added
-  inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
-  inputs.clan-core.inputs.nixpkgs.follows = "nixpkgs";
-  inputs.clan-core.inputs.flake-parts.follows = "flake-parts";
+  # New flake-parts input
+  flake-parts.url = "github:hercules-ci/flake-parts";
+  flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
+  
+  clan-core = {
+    url = "git+https://git.clan.lol/clan/clan-core";
+    inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
+    # New
+    inputs.flake-parts.follows = "flake-parts";
+  };
+}
 ```
 
 ### 2. Import Clan-Core Flake Module
 
-After updating your flake inputs, the next step is to import the `clan-core` flake module into your project. This allows you to utilize Clan functionalities within your Nix project. Update your `flake.nix` file as shown below:
+After updating your flake inputs, the next step is to import the `clan-core` flake module. This will make the [clan options](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) available within `mkFlake`.
 
 ```nix
   outputs =
@@ -174,9 +263,9 @@ After updating your flake inputs, the next step is to import the `clan-core` fla
 
 ### 3. Configure Clan Settings and Define Machines
 
-Lastly, define your Clan configuration settings, including a unique clan name and the machines you want to manage with Clan.
-This is where you specify the characteristics of each machine,
-such as the platform and specific Nix configurations. Update your `flake.nix` like this:
+Configure your clan settings and define machine configurations.
+
+Below is a guide on how to structure this in your flake.nix:
 
 ```nix
   outputs =
@@ -187,14 +276,17 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
           inputs.clan-core.flakeModules.default
         ];
         clan = {
+          ## Clan wide settings. (Required)
+          clanName = "__CHANGE_ME__"; # Ensure to choose a unique name.
+          directory = self; # Point this to the repository root.
+
           specialArgs = { }; # Add arguments to every nix import in here
-          clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
-          directory = inputs.self;
+          
           machines = {
             jons-desktop = {
               nixpkgs.hostPlatform = "x86_64-linux";
               imports = [
-                clan-core.clanModules.sshd # Add openssh server for clan management
+                clan-core.clanModules.sshd # Add openssh server for cLan management
                 ./configuration.nix
               ];
             };
@@ -207,7 +299,14 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
 For detailed information about configuring `flake-parts` and the available options within Clan,
 refer to the Clan module documentation located [here](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix).
 
-### **Next Steps**
+### Next Steps
+
 With your flake created, explore how to add new machines by reviewing the documentation provided [here](./machines.md).
 
----
\ No newline at end of file
+---
+
+## TODO
+
+* How do I use cLan machines install to setup my current machine?
+* I probably need the clan-core sshd module for that?
+* We need to tell them that configuration.nix of a machine NEEDS to be under the directory CLAN_ROOT/machines/<machine-name> I think?
\ No newline at end of file

From 55f3878e67c7f6f52e08620808e708f628a507f9 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Sun, 7 Apr 2024 14:32:23 +0200
Subject: [PATCH 10/13] machine.md: clean up guide

---
 docs/admins/machines.md         | 120 ++++++++++++++++++++------------
 pkgs/installer/flake-module.nix |   4 ++
 2 files changed, 78 insertions(+), 46 deletions(-)

diff --git a/docs/admins/machines.md b/docs/admins/machines.md
index 08cbd7f07..96a115051 100644
--- a/docs/admins/machines.md
+++ b/docs/admins/machines.md
@@ -1,16 +1,8 @@
 # Managing NixOS Machines with Clan
 
-Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
-
-
-
-# TODO:
-* clan facts generate
-* clan machine check / build (CI is missing)
-* TODO: How to join others people zerotier
-  * `services.zerotier.joinNetworks = [ "network-id" ]`
-* Controler needs to approve over webinterface or cli
+Integrating a new machine into your cLan environment is a very easy yet flexible process, allowing for the centralized management of multiple NixOS configurations.
 
+The Guide below showcases how to introduce a new machine into an existing cLan setup.
 
 ## Installing a New Machine
 
@@ -19,47 +11,75 @@ This process involves preparing a suitable hardware and disk partitioning config
 
 ### Prerequisites
 
-- A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
-- For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
+- [x] A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
+- [x] For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
 
 ## Creating a Bootable USB Drive on Linux
 
 To create a bootable USB flash drive with the NixOS installer:
 
-1. **Build the Installer Image**:
+### Build the Installer Image
 
-   ```shellSession
-   $ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
-   ```
+```bash
+nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
+```
 
-2. **Prepare the USB Flash Drive**:
+### Prepare the USB Flash Drive
 
-   - Insert your USB flash drive into your computer.
-   - Identify your flash drive with `lsblk`. Look for the device with a matching size.
-   - Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
+- Insert your USB flash drive into your computer.
+- Identify your flash drive with `lsblk`. Look for the device with a matching size.
+- Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
 
-     ```shellSession
-     sudo umount /dev/sdX*
-     ```
+```bash
+sudo umount /dev/sdX*
+```
 
-3. **Write the Image to the USB Drive**:
+### Write the Image to the USB Drive
 
-   - Use the `dd` utility to write the NixOS installer image to your USB drive:
+Use the `dd` utility to write the NixOS installer image to your USB drive:
 
-     ```shellSession
-     sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX
-     ```
+```bash
+sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX
+```
 
-4. **Boot and Connect**:
-   - After writing the installer to the USB drive, use it to boot the target machine.
-   - The installer will display an IP address and a root password, which you can use to connect via SSH.
+In case your USB device is `sdb` use `of=/dev/sdb`
+
+### Boot and Connect
+
+After writing the installer to the USB drive, use it to boot the target machine.
+
+> i.e. Plug it into the target machine and select the USB drive as a temporary boot device.
+
+For most hardware you can find the Key-combination below:
+
+- **Dell**: F12 (Boot Menu), F2/Del (BIOS Setup)
+- **HP**: F9 (Boot Menu), Esc (Startup Menu)
+- **Lenovo**: F12 (ThinkPad Boot Menu), F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
+- **Acer**: F12 (Boot Menu), F2/Del (BIOS Setup)
+- **Asus**: F8/Esc (Boot Menu), F2/Del (BIOS Setup)
+- **Toshiba**: F12/F2 (Boot Menu), Esc then F12 (Alternate Method)
+- **Sony**: F11/Assist Button (Boot Menu/Recovery Options)
+- **Samsung**: F2/F12/Esc (Boot Menu), F2 (BIOS Setup)
+- **MSI**: F11 (Boot Menu), Del (BIOS Setup)
+- **Apple**: Option (Alt) Key (Boot Menu for Mac)
+- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
+
+**During Boot**
+
+Select `NixOS` to boot into the clan installer
+
+**After Booting**
+
+The installer will display an IP address and a root password, which you can use to connect via SSH.
+
+Alternatively you can also use the displayed QR code.
 
 ### Finishing the installation
 
 With the target machine running Linux and accessible via SSH, execute the following command to install NixOS on the target machine, replacing `<target_host>` with the machine's hostname or IP address:
 
-```shellSession
-$ clan machines install my-machine <target_host>
+```bash
+clan machines install my-machine <target_host>
 ```
 
 ## Update Your Machines
@@ -70,25 +90,25 @@ Clan CLI enables you to remotely update your machines over SSH. This requires se
 
 Replace `host_or_ip` with the actual hostname or IP address of your target machine:
 
-```shellSession
-$ clan config --machine my-machine clan.networking.targetHost root@host_or_ip
+```bash
+clan config --machine my-machine clan.networking.targetHost root@host_or_ip
 ```
 
-_Note: The use of `root@` in the target address implies SSH access as the root user.
-Ensure that the root login is secured and only used when necessary._
+> Note: The use of `root@` in the target address implies SSH access as the `root` user.
+> Ensure that the root login is secured and only used when necessary.
 
 ### Updating Machine Configurations
 
 Execute the following command to update the specified machine:
 
-```shellSession
-$ clan machines update my-machine
+```bash
+clan machines update my-machine
 ```
 
 You can also update all configured machines simultaneously by omitting the machine name:
 
-```shellSession
-$ clan machines update
+```bash
+clan machines update
 ```
 
 ### Setting a Build Host
@@ -97,8 +117,8 @@ If the machine does not have enough resources to run the NixOS evaluation or bui
 it is also possible to specify a build host instead.
 During an update, the cli will ssh into the build host and run `nixos-rebuild` from there.
 
-```shellSession
-$ clan config --machine my-machine clan.networking.buildHost root@host_or_ip
+```bash
+clan config --machine my-machine clan.networking.buildHost root@host_or_ip
 ```
 
 ### Excluding a machine from `clan machine update`
@@ -106,9 +126,17 @@ $ clan config --machine my-machine clan.networking.buildHost root@host_or_ip
 To exclude machines from beeing updated when running `clan machines update` without any machines specified,
 one can set the `clan.deployment.requireExplicitUpdate` option to true:
 
-
-```shellSession
-$ clan config --machine my-machine clan.deployment.requireExplicitUpdate true
+```bash
+clan config --machine my-machine clan.deployment.requireExplicitUpdate true
 ```
 
 This is useful for machines that are not always online or are not part of the regular update cycle.
+
+---
+
+# TODO:
+* clan facts generate
+* clan machine check / build (CI is missing)
+* TODO: How to join others people zerotier
+  * `services.zerotier.joinNetworks = [ "network-id" ]`
+* Controller needs to approve over webinterface or cli
\ No newline at end of file
diff --git a/pkgs/installer/flake-module.nix b/pkgs/installer/flake-module.nix
index 6de665776..51589a633 100644
--- a/pkgs/installer/flake-module.nix
+++ b/pkgs/installer/flake-module.nix
@@ -7,6 +7,10 @@ let
         self.nixosModules.installer
         self.inputs.nixos-generators.nixosModules.all-formats
       ];
+      # Provide convenience for connecting to wifi      
+      networking.networkmanager.enable = true;
+      networking.wireless.enable = false;
+      users.users.root.extraGroups = [ "networkmanager" ];
 
       system.stateVersion = config.system.nixos.version;
       nixpkgs.pkgs = self.inputs.nixpkgs.legacyPackages.x86_64-linux;

From 83346eeff50907c32a6746aa515b2e6c76fc40fd Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Sun, 7 Apr 2024 15:59:33 +0200
Subject: [PATCH 11/13] template: Fixed incorrect nix code

---
 templates/new-clan/flake.nix | 44 +++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix
index 04ded52be..542f957d4 100644
--- a/templates/new-clan/flake.nix
+++ b/templates/new-clan/flake.nix
@@ -9,46 +9,58 @@
       system = "x86_64-linux";
       pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
       clan = clan-core.lib.buildClan {
-        specialArgs = { }; # Add arguments to every nix import in here
         directory = self;
         clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
+        clanIcon = null; # Optional, a path to an image file
+        # TODO: boot into the installer
+        # remote> nixos-generate-config --root /tmp/config --no-filesystems
+        # local> mkdir -p ./machines/machine1
+        # local> scp -r root@machine1:/tmp/config ./machines/machine1
+        # local> Edit ./machines/machine1/configuration.nix to your liking
         machines = {
           jon = {
             nixpkgs.hostPlatform = system;
             imports = [
-              # TODO: boot into the installer
-              # remote> nixos-generate-config --root /tmp/config --no-filesystems
-              # local> mkdir -p ./machines/machine1
-              # local> scp -r root@machine1:/tmp/config ./machines/machine1
-              # local> Edit ./machines/machine1/configuration.nix to your liking
-              ./modules/disko.nix
               ./machines/jon/configuration.nix
               clan-core.clanModules.sshd
+              clan-core.clanModules.diskLayouts
               {
+                config.clanCore.machineIcon = null; # Optional, a path to an image file
+
                 # Set this for clan commands use ssh i.e. `clan machines update`
-                clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
+                config.clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
+
+                # TODO: Example how to use disko for more complicated setups
+
                 # remote> lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
+                config.clan.diskLayouts.singleDiskExt4 = {
+                  device = "/dev/disk/by-id/__CHANGE_ME__";
+                };
 
-                config.disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
+                config.services.getty.autologinUser = "root";
 
-                clan.networking.zerotier.controller.enable = true;
+                # TODO: Document that there needs to be one controller
+                config.clan.networking.zerotier.controller.enable = true;
               }
             ];
           };
           sara = {
             nixpkgs.hostPlatform = system;
             imports = [
-              # ./machines/machine2/configuration.nix
-              ./modules/disko.nix
               ./machines/sara/configuration.nix
               clan-core.clanModules.sshd
+              clan-core.clanModules.diskLayouts
               {
-                # Set this for clan commands use ssh i.e. `clan machines update`
-                clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
+                config.clanCore.machineIcon = null; # Optional, a path to an image file
+
+                # Set this for clan commands use ssh i.e. `clan machines update`
+                config.clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
 
-                config.disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
                 # local> clan facts generate
-                clan.networking.zerotier.networkId = builtins.readFile ./machines/machine1/facts/zerotier-network-id;
+
+                config.clan.diskLayouts.singleDiskExt4 = {
+                  device = "/dev/disk/by-id/__CHANGE_ME__";
+                };
               }
             ];
           };

From 4faba7c8e1db2e6899d3c1d14d80f18ed2c2a208 Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Sun, 7 Apr 2024 17:09:44 +0200
Subject: [PATCH 12/13] template: Reverted systemd-boot in installer. EF02
 partition on wrong second place

---
 docs/admins/machines.md            | 36 +++++++++++++++++++++---------
 nixosModules/installer/default.nix | 16 ++++++-------
 pkgs/installer/flake-module.nix    | 18 +++++++++++----
 3 files changed, 48 insertions(+), 22 deletions(-)

diff --git a/docs/admins/machines.md b/docs/admins/machines.md
index 96a115051..ecd7731d5 100644
--- a/docs/admins/machines.md
+++ b/docs/admins/machines.md
@@ -26,23 +26,39 @@ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
 
 ### Prepare the USB Flash Drive
 
-- Insert your USB flash drive into your computer.
-- Identify your flash drive with `lsblk`. Look for the device with a matching size.
-- Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
+1. Insert your USB flash drive into your computer.
 
-```bash
-sudo umount /dev/sdX*
-```
+2. Identify your flash drive with `lsblk`.
+    ```shellSession
+    $ lsblk
+    NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
+    sdb                                             8:0    1 117,2G  0 disk
+    └─sdb1                                          8:1    1 117,2G  0 part  /run/media/qubasa/INTENSO
+    nvme0n1                                       259:0    0   1,8T  0 disk
+    ├─nvme0n1p1                                   259:1    0   512M  0 part  /boot
+    └─nvme0n1p2                                   259:2    0   1,8T  0 part
+      └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0    0   1,8T  0 crypt /nix/store                                                                 /
+    ```
+
+    In this case it's `sdb`
+
+3. Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
+
+    ```bash
+    sudo umount /dev/sdb1
+    ```
 
 ### Write the Image to the USB Drive
 
 Use the `dd` utility to write the NixOS installer image to your USB drive:
 
-```bash
-sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX
-```
+  ```bash
+  sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sd<X>
+  ```
+
+  In case your USB device is `sdb` use `of=/dev/sdb`
+
 
-In case your USB device is `sdb` use `of=/dev/sdb`
 
 ### Boot and Connect
 
diff --git a/nixosModules/installer/default.nix b/nixosModules/installer/default.nix
index 842e50728..68ff28f0b 100644
--- a/nixosModules/installer/default.nix
+++ b/nixosModules/installer/default.nix
@@ -59,12 +59,12 @@
     fi
   '';
 
-  boot.loader.systemd-boot.enable = true;
 
   # Grub doesn't find devices for both BIOS and UEFI?
-
-  #boot.loader.grub.efiInstallAsRemovable = true;
-  #boot.loader.grub.efiSupport = true;
+  # NOTE: We need grub here. Otherwise, the system won't boot in some machines.
+  # example: Lenovo E495 didn't boot without grub.
+  boot.loader.grub.efiInstallAsRemovable = true;
+  boot.loader.grub.efiSupport = true;
   disko.devices = {
     disk = {
       stick = {
@@ -74,10 +74,10 @@
         content = {
           type = "gpt";
           partitions = {
-            #boot = {
-            #  size = "1M";
-            #  type = "EF02"; # for grub MBR
-            #};
+            boot = {
+             size = "1M";
+             type = "EF02"; # for grub MBR
+            };
             ESP = {
               size = "100M";
               type = "EF00";
diff --git a/pkgs/installer/flake-module.nix b/pkgs/installer/flake-module.nix
index 51589a633..dc7ee4f2c 100644
--- a/pkgs/installer/flake-module.nix
+++ b/pkgs/installer/flake-module.nix
@@ -7,11 +7,22 @@ let
         self.nixosModules.installer
         self.inputs.nixos-generators.nixosModules.all-formats
       ];
-      # Provide convenience for connecting to wifi      
-      networking.networkmanager.enable = true;
+      # Provide convenience for connecting to wifi
       networking.wireless.enable = false;
-      users.users.root.extraGroups = [ "networkmanager" ];
 
+      # Use iwd instead of wpa_supplicant. It has a user friendly CLI
+      networking.wireless.iwd = {
+        settings = {
+          Network = {
+            EnableIPv6 = true;
+            RoutePriorityOffset = 300;
+          };
+          Settings = {
+            AutoConnect = true;
+          };
+        };
+        enable = true;
+      };
       system.stateVersion = config.system.nixos.version;
       nixpkgs.pkgs = self.inputs.nixpkgs.legacyPackages.x86_64-linux;
     };
@@ -34,7 +45,6 @@ in
     machines.installer = {
       imports = [ installerModule ];
       fileSystems."/".device = lib.mkDefault "/dev/null";
-      boot.loader.grub.device = lib.mkDefault "/dev/null";
     };
   };
   flake.apps.x86_64-linux.install-vm.program = installer.config.formats.vm.outPath;

From 1e0d73e8a9a236b5631afd8c767aadfa37ffd93d Mon Sep 17 00:00:00 2001
From: Qubasa <consulting@qube.email>
Date: Sun, 7 Apr 2024 21:07:02 +0200
Subject: [PATCH 13/13] Improve documentation

---
 docs/admins/install-iso.md         | 125 +++++++++++++++++++++++++++++
 docs/admins/machines.md            |  85 --------------------
 docs/admins/quickstart.md          |  33 +++++++-
 nixosModules/installer/default.nix |  14 +++-
 4 files changed, 169 insertions(+), 88 deletions(-)
 create mode 100644 docs/admins/install-iso.md

diff --git a/docs/admins/install-iso.md b/docs/admins/install-iso.md
new file mode 100644
index 000000000..e969efa09
--- /dev/null
+++ b/docs/admins/install-iso.md
@@ -0,0 +1,125 @@
+# Clan Hardware Installation
+
+For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
+
+## Creating a Bootable USB Drive on Linux
+
+To create a bootable USB flash drive with the NixOS installer:
+
+### Build the Installer Image
+
+```bash
+nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
+```
+
+> Make sure you do this inside 
+
+### Prepare the USB Flash Drive
+
+1. Insert your USB flash drive into your computer.
+
+2. Identify your flash drive with `lsblk`.
+    ```shellSession
+    $ lsblk
+    NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
+    sdb                                             8:0    1 117,2G  0 disk
+    └─sdb1                                          8:1    1 117,2G  0 part  /run/media/qubasa/INTENSO
+    nvme0n1                                       259:0    0   1,8T  0 disk
+    ├─nvme0n1p1                                   259:1    0   512M  0 part  /boot
+    └─nvme0n1p2                                   259:2    0   1,8T  0 part
+      └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0    0   1,8T  0 crypt /nix/store                                                                 /
+    ```
+
+    In this case it's `sdb`
+
+3. Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
+
+    ```bash
+    sudo umount /dev/sdb1
+    ```
+
+### Write the Image to the USB Drive
+
+Use the `dd` utility to write the NixOS installer image to your USB drive:
+
+  ```bash
+  sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sd<X>
+  ```
+
+  In case your USB device is `sdb` use `of=/dev/sdb`
+
+
+
+### Boot and Connect
+
+After writing the installer to the USB drive, use it to boot the target machine.
+
+1. For this secure boot needs to be disabled. Go into your UEFI / Bios settings by pressing one of the keys outlined below while booting:
+
+   - **Dell**: F2/Del (BIOS Setup)
+   - **HP**: Esc (Startup Menu)
+   - **Lenovo**: F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
+   - **Acer**: F2/Del (BIOS Setup)
+   - **Asus**: F2/Del (BIOS Setup)
+   - **Toshiba**: Esc then F12 (Alternate Method)
+   - **Sony**: F11
+   - **Samsung**: F2 (BIOS Setup)
+   - **MSI**: Del (BIOS Setup)
+   - **Apple**: Option (Alt) Key (Boot Menu for Mac)
+   - If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
+
+2. Inside the UEFI/Bios Menu go to `Security->Secure Boot` and disable secure boot
+
+3. Save your settings. Put in the USB stick and reboot.
+
+4.  Press one of keys outlined below to go into the Boot Menu
+       - **Dell**: F12 (Boot Menu)
+       - **HP**: F9 (Boot Menu)
+       - **Lenovo**: F12 (ThinkPad Boot Menu)
+       - **Acer**: F12 (Boot Menu)
+       - **Asus**: F8/Esc (Boot Menu)
+       - **Toshiba**: F12/F2 (Boot Menu)
+       - **Sony**: F11
+       - **Samsung**: F2/F12/Esc (Boot Menu)
+       - **MSI**: F11
+       - **Apple**: Option (Alt) Key (Boot Menu for Mac)
+       - If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
+
+
+
+
+5. Select `NixOS` to boot into the clan installer
+
+
+6. The installer will display an IP address and a root password, which you can use to connect via SSH.  
+    Alternatively you can also use the displayed QR code.
+
+7. Set your keyboard language. Important for writing passwords correctly.
+    ```bash
+    loadkeys de
+    ```
+
+8. If you only have Wifi available, execute:
+    1. Bring up the `iwd` shell
+        ```bash
+        iwctl
+        ```
+    2. List available networks. Double press tab after station for autocompleting your wlan device. In this case `wlan0` 
+        ```shellSession
+        [iwd] station wlan0 get-networks
+        ```
+    3. Connect to a Wifi network. Replace `SSID` with the wlan network name.
+        ```shellSession
+        [iwd] station wlan0 connect SSID
+        ```
+9. Now that you have internet re-execute the init script by pressing `Ctrl+D` or by executing:
+    ```bash
+    bash
+    ```
+
+10. Connect to the machine over ssh
+    ```bash
+    ssh-copy-id -o PreferredAuthentications=password root@<ip>
+    ```
+    Use the root password displayed on your screen as login.
+
diff --git a/docs/admins/machines.md b/docs/admins/machines.md
index ecd7731d5..ba2dc6122 100644
--- a/docs/admins/machines.md
+++ b/docs/admins/machines.md
@@ -1,94 +1,11 @@
 # Managing NixOS Machines with Clan
 
-Integrating a new machine into your cLan environment is a very easy yet flexible process, allowing for the centralized management of multiple NixOS configurations.
-
-The Guide below showcases how to introduce a new machine into an existing cLan setup.
-
-## Installing a New Machine
-
 Clan CLI, in conjunction with [nixos-anywhere](https://github.com/nix-community/nixos-anywhere), provides a seamless method for installing NixOS on various machines.
 This process involves preparing a suitable hardware and disk partitioning configuration and ensuring the target machine is accessible via SSH.
 
 ### Prerequisites
 
 - [x] A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
-- [x] For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
-
-## Creating a Bootable USB Drive on Linux
-
-To create a bootable USB flash drive with the NixOS installer:
-
-### Build the Installer Image
-
-```bash
-nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
-```
-
-### Prepare the USB Flash Drive
-
-1. Insert your USB flash drive into your computer.
-
-2. Identify your flash drive with `lsblk`.
-    ```shellSession
-    $ lsblk
-    NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
-    sdb                                             8:0    1 117,2G  0 disk
-    └─sdb1                                          8:1    1 117,2G  0 part  /run/media/qubasa/INTENSO
-    nvme0n1                                       259:0    0   1,8T  0 disk
-    ├─nvme0n1p1                                   259:1    0   512M  0 part  /boot
-    └─nvme0n1p2                                   259:2    0   1,8T  0 part
-      └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0    0   1,8T  0 crypt /nix/store                                                                 /
-    ```
-
-    In this case it's `sdb`
-
-3. Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
-
-    ```bash
-    sudo umount /dev/sdb1
-    ```
-
-### Write the Image to the USB Drive
-
-Use the `dd` utility to write the NixOS installer image to your USB drive:
-
-  ```bash
-  sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sd<X>
-  ```
-
-  In case your USB device is `sdb` use `of=/dev/sdb`
-
-
-
-### Boot and Connect
-
-After writing the installer to the USB drive, use it to boot the target machine.
-
-> i.e. Plug it into the target machine and select the USB drive as a temporary boot device.
-
-For most hardware you can find the Key-combination below:
-
-- **Dell**: F12 (Boot Menu), F2/Del (BIOS Setup)
-- **HP**: F9 (Boot Menu), Esc (Startup Menu)
-- **Lenovo**: F12 (ThinkPad Boot Menu), F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
-- **Acer**: F12 (Boot Menu), F2/Del (BIOS Setup)
-- **Asus**: F8/Esc (Boot Menu), F2/Del (BIOS Setup)
-- **Toshiba**: F12/F2 (Boot Menu), Esc then F12 (Alternate Method)
-- **Sony**: F11/Assist Button (Boot Menu/Recovery Options)
-- **Samsung**: F2/F12/Esc (Boot Menu), F2 (BIOS Setup)
-- **MSI**: F11 (Boot Menu), Del (BIOS Setup)
-- **Apple**: Option (Alt) Key (Boot Menu for Mac)
-- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
-
-**During Boot**
-
-Select `NixOS` to boot into the clan installer
-
-**After Booting**
-
-The installer will display an IP address and a root password, which you can use to connect via SSH.
-
-Alternatively you can also use the displayed QR code.
 
 ### Finishing the installation
 
@@ -151,8 +68,6 @@ This is useful for machines that are not always online or are not part of the re
 ---
 
 # TODO:
-* clan facts generate
-* clan machine check / build (CI is missing)
 * TODO: How to join others people zerotier
   * `services.zerotier.joinNetworks = [ "network-id" ]`
 * Controller needs to approve over webinterface or cli
\ No newline at end of file
diff --git a/docs/admins/quickstart.md b/docs/admins/quickstart.md
index c66a0ba1c..3136a3bcf 100644
--- a/docs/admins/quickstart.md
+++ b/docs/admins/quickstart.md
@@ -39,7 +39,38 @@ Look for `.clan-flake`, `flake.lock`, and `flake.nix` among your files to confir
 ### **Understanding `.clan-flake`**
 The `.clan-flake` file, while optional, is instrumental in helping the Clan CLI identify your project's root directory, easing project management.
 
+### Edit Flake.nix
+Open the `flake.nix` file and set a unique `clanName` if you want you can also set an optional `clanIcon` or even a per `machineIcon`. These will be used by our future clan GUI.
+
+### Remote into the target machine
+**Right now clan assumes that you already have NixOS running on the target machine.**  
+If that is not the case you can use our [installer image](./install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
+
+On the remote execute:
+1. Generate a hardware-config.nix 
+    ```bash
+    nixos-generate-config --root /etc/nixos --no-filesystems
+    ```
+2. Copy it over and put it into you `machines/jon/hardware-config.nix` folder
+    ```bash
+    scp -r root@<jon-ip>:/etc/nixos/hardware-config.nix ./machines/jon
+    ```
+3. Find the remote disk id by executing on the remote:
+    ```bash
+    lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
+    ```
+4. Edit the following fields inside the `flake.nix`
+    - `clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";`
+    - `clan.diskLayouts.singleDiskExt4 = {
+                  device = "/dev/disk/by-id/__CHANGE_ME__";
+                };`
+
+5. Generate secrets used by clan modules by executing
+    ```bash
+    clan facts generate
+    ```
+
 ### **Next Steps**
-Ready to expand? Explore how to add new machines to your project with the helpful documentation [here](./machines.md).
+Ready to expand? Explore how to install a new machine with the helpful documentation [here](./machines.md).
 
 ---
diff --git a/nixosModules/installer/default.nix b/nixosModules/installer/default.nix
index 68ff28f0b..6e161dbbc 100644
--- a/nixosModules/installer/default.nix
+++ b/nixosModules/installer/default.nix
@@ -5,6 +5,12 @@
   ...
 }:
 {
+  ############################################
+  #                                          #
+  # For install image debugging execute:     #
+  # $ qemu-kvm result/stick.raw -snapshot    #
+  #                                          #
+  ############################################
   systemd.tmpfiles.rules = [ "d /var/shared 0777 root root - -" ];
   imports = [
     (modulesPath + "/profiles/installation-device.nix")
@@ -59,12 +65,15 @@
     fi
   '';
 
+  # boot.loader.systemd-boot.enable = true;
 
   # Grub doesn't find devices for both BIOS and UEFI?
+  # Mic92: Please write where this exactly breaks if you want to comment out grub again.
   # NOTE: We need grub here. Otherwise, the system won't boot in some machines.
   # example: Lenovo E495 didn't boot without grub.
   boot.loader.grub.efiInstallAsRemovable = true;
   boot.loader.grub.efiSupport = true;
+
   disko.devices = {
     disk = {
       stick = {
@@ -75,8 +84,9 @@
           type = "gpt";
           partitions = {
             boot = {
-             size = "1M";
-             type = "EF02"; # for grub MBR
+              priority = 1;
+              size = "1M";
+              type = "EF02"; # for grub MBR
             };
             ESP = {
               size = "100M";