rework installation template based on received feedback

docs/site/getting-started/configure.md

@@ -32,9 +32,9 @@ In the `flake.nix` file:
 
 - [x] set a unique `name`.
 
-=== "**buildClan**"
+=== "**normal flake template**"
 
-    ```nix title="clan-core.lib.buildClan"
+    ```nix title="flake.nix" hl_lines="3"
     buildClan {
         # Set a unique name
         meta.name = "Lobsters";
@@ -50,11 +50,11 @@ In the `flake.nix` file:
     }
     ```
 
-=== "**flakeParts**"
+=== "**template using flake-parts**"
 
     !!! info "See [Clan with flake-parts](./flake-parts.md) for help migrating to flake-parts."
 
-    ```nix title="clan-core.flakeModules.default"
+    ```nix title="flake.nix" hl_lines="3"
     clan = {
         # Set a unique name
         meta.name = "Lobsters";
@@ -77,11 +77,11 @@ Adding or configuring a new machine requires two simple steps:
 1. Find the remote disk id by executing:
 
     ```bash title="setup computer"
-    ssh root@flash-installer.local lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
+    ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
     ```
 
     !!! Note
-        Replace `flash-installer.local` with the IP address of the machine if you don't have the avahi service running which resolves mDNS local domains.
+        Replace `<IP>` with the IP address of the machine if you don't have the avahi service running which resolves mDNS local domains.
 
     Which should show something like:
 
@@ -97,75 +97,43 @@ Adding or configuring a new machine requires two simple steps:
     └─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap    16.8G
     ```
 
-1. Edit the following fields inside the `flake.nix`
+1. Edit the following fields inside the `./machines/jon/configuration.nix` and/or `./machines/sara/configuration.nix`
 
-    === "**buildClan**"
+   ```nix title="./machines/<machine>/configuration.nix" hl_lines="13 18 23 27"
+   {
+      imports = [
+        ./hardware-configuration.nix
+        # contains your disk format and partitioning configuration.
+        ../../modules/disko.nix
+        # this file is shared among all machines
+        ../../modules/shared.nix
+        # enables GNOME desktop (optional)
+        ../../modules/gnome.nix
+      ];
 
-        ```nix title="clan-core.lib.buildClan" hl_lines="18 23"
+      # Put your username here for login
-        buildClan {
+      users.users.user.username = "__YOUR_USERNAME__";
-          # ...
-          machines = {
-            "jon" = {
-              imports = [
-                # ...
-                ./modules/disko.nix
-                ./machines/jon/configuration.nix
-              ];
-              # ...
 
-              # Change this to the correct ip-address or hostname
+      # Set this for clan commands use ssh i.e. `clan machines update`
-              # The hostname is the machine name by default
+      # If you change the hostname, you need to update this line to root@<new-hostname>
-              clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon"
+      # This only works however if you have avahi running on your admin machine else use IP
+      clan.core.networking.targetHost = "root@__IP__";
 
-              # Change this to the ID-LINK of the desired disk shown by 'lsblk'
+      # You can get your disk id by running the following command on the installer:
-              disko.devices.disk.main = {
+      # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
-                device = "/dev/disk/by-id/__CHANGE_ME__";
+      # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-              }
+      disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
 
-              # e.g. > cat ~/.ssh/id_ed25519.pub
+      # IMPORTANT! Add your SSH key here
-              users.users.root.openssh.authorizedKeys.keys = [
+      # e.g. > cat ~/.ssh/id_ed25519.pub
-                  "<YOUR SSH_KEY>"
+      users.users.root.openssh.authorizedKeys.keys = "__YOUR_SSH_KEY__";
-              ];
-              # ...
-            };
-          };
-        }
-        ```
-
-    === "**flakeParts**"
-
-        ```nix title="clan-core.flakeModules.default" hl_lines="18 23"
-        clan = {
-          # ...
-          machines = {
-            "jon" = {
-              imports = [
-                # ...
-                ./modules/disko.nix
-                ./machines/jon/configuration.nix
-              ];
-              # ...
-
-              # Change this to the correct ip-address or hostname
-              # The hostname is the machine name by default
-              clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon"
-
-              # Change this to the ID-LINK of the desired disk shown by 'lsblk'
-              disko.devices.disk.main = {
-                device = "/dev/disk/by-id/__CHANGE_ME__";
-              }
-
-              # e.g. > cat ~/.ssh/id_ed25519.pub
-              users.users.root.openssh.authorizedKeys.keys = [
-                  "__YOUR_SSH_KEY__"
-              ];
-              # ...
-            };
-          };
-        };
-        ```
 
+      # ...
+   }
+   ```
 
+!!! Info "Replace `__YOUR_USERNAME__` with the ip of your machine, if you use avahi you can also use your hostname"
+!!! Info "Replace `__IP__` with the ip of your machine, if you use avahi you can also use your hostname"
 !!! Info "Replace `__CHANGE_ME__` with the appropriate identifier, such as `nvme-eui.e8238fa6bf530001001b448b4aec2929`"
 !!! Info "Replace `__YOUR_SSH_KEY__` with your personal key, like `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop`"
 
@@ -179,22 +147,57 @@ Generate the `hardware-configuration.nix` file for your machine by executing the
 clan machines hw-generate [MACHINE_NAME] [HOSTNAME]
 ```
 
-replace `[MACHINE_NAME]` with the name of the machine i.e. `jon` and `[HOSTNAME]` with the `ip_adress` or `hostname` of the machine within the network. i.e. `flash-installer.local`
+replace `[MACHINE_NAME]` with the name of the machine i.e. `jon` and `[HOSTNAME]` with the `ip_adress` or `hostname` of the machine within the network. i.e. `<IP>`
 
 !!! Example
     ```bash
-    clan machines hw-generate jon flash-installer.local
+    clan machines hw-generate jon <IP>
     ```
 
-    This command connects to `flash-installer.local` as `root`, runs `nixos-generate-config` to detect hardware configurations (excluding filesystems), and writes them to `machines/jon/hardware-configuration.nix`.
+    This command connects to `<IP>` as `root`, runs `nixos-generate-config` to detect hardware configurations (excluding filesystems), and writes them to `machines/jon/hardware-configuration.nix`.
 
 ### Step 3: Custom Disk Formatting
 
-In `./modules/disko.nix`, a simple `ext4` disk partitioning scheme is defined for the Disko module. For more complex disk partitioning setups, refer to the [Disko examples](https://github.com/nix-community/disko/tree/master/example).
+In `./modules/disko.nix`, a simple `ext4` disk partitioning scheme is defined for the Disko module. For more complex disk partitioning setups,
+refer to the [Disko templates](https://github.com/nix-community/disko-templates) or  [Disko examples](https://github.com/nix-community/disko/tree/master/example).
 
 ### Step 4: Custom Configuration
 
 Modify `./machines/jon/configuration.nix` to personalize the system settings according to your requirements.
+If you wish to name your machine to something else, do the following steps:
+
+```
+mv ./machines/jon/configuration.nix ./machines/newname/configuration.nix
+```
+
+Than rename `jon` to your preferred name in `machines` in `flake.nix` as well as the import line:
+
+```diff
+- imports = [ ./machines/jon/configuration.nix ];
++ imports = [ ./machines/__NEW_NAME__/configuration.nix ];
+```
+
+!!! Info "Replace `__NEW_NAME__` with the name of the machine"
+
+Note that our clan lives inside a git repository.
+Only files that have been added with `git add` are recognized by `nix`.
+So for every file that you add or rename you also need to run:
+
+```
+git add ./path/to/my/file
+```
+
+For renaming jon to your own machine name, you can use the following command:
+
+```
+git mv ./machines/jon ./machines/newname
+```
+
+If you only want to setup a single machine at this point, you can delete `sara` from flake.nix as well as from the machines directory:
+
+```
+git rm ./machines/sara
+```
 
 ### Step 5: Check Configuration
 
@@ -206,9 +209,9 @@ nix flake check
 
 This command helps ensure that your system configuration is correct and free from errors.
 
-!!! Note
+!!! Tip
 
-    Integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase. This practice helps maintain system stability and reduces integration issues.
+    You can integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase.
 
 
 ---

docs/site/getting-started/deploy.md

@@ -112,7 +112,7 @@ This process involves preparing a suitable hardware and disk partitioning config
     1. **SSH with Password Authentication**
         Run the following command to install using SSH:
         ```bash
-        clan machines install [MACHINE] flash-installer.local
+        clan machines install [MACHINE] <IP>
         ```
 
     2. **Scanning a QR Code for Installation Details**
@@ -150,23 +150,17 @@ Clan CLI enables you to remotely update your machines over SSH. This requires se
 
 ### Setting the Target Host
 
-Replace `root@jon` with the actual hostname or IP address of your target machine:
+Replace `root@jon` with the actual hostname or IP address of your target machine in the `configuration.nix` of the machine:
 ```{.nix hl_lines="9" .no-copy}
-buildClan {
+{
     # ...
-    machines = {
+    # Set this for clan commands use ssh i.e. `clan machines update`
-        # "jon" will be the hostname of the machine
+    # If you change the hostname, you need to update this line to root@<new-hostname>
-        "jon" = {
+    # This only works however if you have avahi running on your admin machine else use IP
-            # Set this for clan commands use ssh i.e. `clan machines update`
+    clan.core.networking.targetHost = "root@jon";
-            # If you change the hostname, you need to update this line to root@<new-hostname>
-            # This only works however if you have avahi running on your admin machine else use IP
-            clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon";
-        };
-    };
 };
 ```
 
-
 !!! warning
     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.

docs/site/index.md

@@ -84,7 +84,7 @@ This should yield the following:
 └── modules
     └── shared.nix
 
-5 directories, 6 files
+5 directories, 9 files
 ```
 
 ```bash

templates/flake-module.nix

@@ -1,6 +1,6 @@
 { self, inputs, ... }:
 {
-  flake = (import ./flake.nix).outputs {} // {
+  flake = (import ./flake.nix).outputs { } // {
     checks.x86_64-linux.template-minimal =
       let
         path = self.templates.minimal.path;

templates/new-clan/flake.nix

@@ -6,94 +6,24 @@
   outputs =
     { self, clan-core, ... }:
     let
-      system = "x86_64-linux";
-      pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
       # Usage see: https://docs.clan.lol
       clan = clan-core.lib.buildClan {
         directory = self;
-        meta.name = "__CHANGE_ME__"; # Ensure this is unique among all clans you want to use.
+        # Ensure this is unique among all clans you want to use.
-
+        meta.name = "__CHANGE_ME__";
-        # Distributed services, uncomment to enable.
-        # inventory = {
-        #   services = {
-        #     # This example configures a BorgBackup service
-        #     # Check: https://docs.clan.lol/reference/clanModules which ones are available in Inventory
-        #     borgbackup.instance_1 = {
-        #       roles.server.machines = [ "jon" ];
-        #       roles.client.machines = [ "sara" ];
-        #     };
-        #   };
-        # };
 
         # Prerequisite: boot into the installer
         # See: https://docs.clan.lol/getting-started/installer
         # local> mkdir -p ./machines/machine1
-        # local> Edit ./machines/machine1/configuration.nix to your liking
+        # local> Edit ./machines/<machine>/configuration.nix to your liking
         machines = {
           # "jon" will be the hostname of the machine
           jon = {
-            imports = [
+            imports = [ ./machines/jon/configuration.nix ];
-              ./modules/shared.nix
-              ./modules/disko.nix
-              ./machines/jon/configuration.nix
-            ];
-
-            nixpkgs.hostPlatform = system;
-
-            # Set this for clan commands use ssh i.e. `clan machines update`
-            # If you change the hostname, you need to update this line to root@<new-hostname>
-            # This only works however if you have avahi running on your admin machine else use IP
-            clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon";
-
-            # You can get your disk id by running the following command on the installer:
-            # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
-            # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-            disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
-
-            # IMPORTANT! Add your SSH key here
-            # e.g. > cat ~/.ssh/id_ed25519.pub
-            users.users.root.openssh.authorizedKeys.keys = throw ''
-              Don't forget to add your SSH key here!
-              users.users.root.openssh.authorizedKeys.keys = [ "<YOUR SSH_KEY>" ]
-            '';
-
-            # Zerotier needs one controller to accept new nodes. Once accepted
-            # the controller can be offline and routing still works.
-            clan.core.networking.zerotier.controller.enable = true;
           };
           # "sara" will be the hostname of the machine
           sara = {
-            imports = [
+            imports = [ ./machines/sara/configuration.nix ];
-              ./modules/shared.nix
-              ./modules/disko.nix
-              ./machines/sara/configuration.nix
-            ];
-
-            nixpkgs.hostPlatform = system;
-
-            # Set this for clan commands use ssh i.e. `clan machines update`
-            # If you change the hostname, you need to update this line to root@<new-hostname>
-            # This only works however if you have avahi running on your admin machine else use IP
-            clan.core.networking.targetHost = pkgs.lib.mkDefault "root@sara";
-
-            # You can get your disk id by running the following command on the installer:
-            # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
-            # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-            disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
-
-            # IMPORTANT! Add your SSH key here
-            # e.g. > cat ~/.ssh/id_ed25519.pub
-            users.users.root.openssh.authorizedKeys.keys = throw ''
-              Don't forget to add your SSH key here!
-              users.users.root.openssh.authorizedKeys.keys = [ "<YOUR SSH_KEY>" ]
-            '';
-
-            /*
-              After jon is deployed, uncomment the following line
-              This will allow sara to share the VPN overlay network with jon
-              The networkId is generated by the first deployment of jon
-            */
-            # clan.core.networking.zerotier.networkId = builtins.readFile ../jon/facts/zerotier-network-id;
           };
         };
       };
@@ -102,8 +32,19 @@
       # all machines managed by Clan
       inherit (clan) nixosConfigurations clanInternals;
       # add the Clan cli tool to the dev shell
-      devShells.${system}.default = pkgs.mkShell {
+      # use the "nix develop" command to enter the dev shell
-        packages = [ clan-core.packages.${system}.clan-cli ];
+      devShells =
-      };
+        clan-core.inputs.nixpkgs.lib.genAttrs
+          [
+            "x86_64-linux"
+            "aarch64-linux"
+            "aarch64-darwin"
+            "x86_64-darwin"
+          ]
+          (system: {
+            default = clan-core.inputs.nixpkgs.legacyPackages.${system}.mkShell {
+              packages = [ clan-core.packages.${system}.clan-cli ];
+            };
+          });
     };
 }

templates/new-clan/machines/jon/configuration.nix

@@ -1,38 +1,34 @@
-{ config, ... }:
-let
-  username = config.networking.hostName;
-in
 {
-  imports = [ ./hardware-configuration.nix ];
+  imports = [
+    ./hardware-configuration.nix
+    # contains your disk format and partitioning configuration.
+    ../../modules/disko.nix
+    # this file is shared among all machines
+    ../../modules/shared.nix
+    # enables GNOME desktop (optional)
+    ../../modules/gnome.nix
+  ];
 
-  # Locale service discovery and mDNS
+  # This is your user login name.
-  services.avahi.enable = true;
+  users.users.user.name = "<your-username>";
 
-  services.xserver.enable = true;
+  # Set this for clan commands use ssh i.e. `clan machines update`
-  services.xserver.desktopManager.gnome.enable = true;
+  # If you change the hostname, you need to update this line to root@<new-hostname>
-  services.xserver.displayManager.gdm.enable = true;
+  # This only works however if you have avahi running on your admin machine else use IP
-  # Disable the default gnome apps to speed up deployment
+  clan.core.networking.targetHost = "root@<IP>";
-  services.gnome.core-utilities.enable = false;
 
-  # Enable automatic login for the user.
+  # You can get your disk id by running the following command on the installer:
-  services.displayManager.autoLogin = {
+  # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
-    enable = true;
+  # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-    user = username;
+  disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
-  };
 
-  users.users.${username} = {
+  # IMPORTANT! Add your SSH key here
-    initialPassword = username;
+  # e.g. > cat ~/.ssh/id_ed25519.pub
-    isNormalUser = true;
+  users.users.root.openssh.authorizedKeys.keys = [''
-    extraGroups = [
+    __YOUR_SSH_KEY__
-      "wheel"
+  ''];
-      "networkmanager"
+
-      "video"
+  # Zerotier needs one controller to accept new nodes. Once accepted
-      "audio"
+  # the controller can be offline and routing still works.
-      "input"
+  clan.core.networking.zerotier.controller.enable = true;
-      "dialout"
-      "disk"
-    ];
-    uid = 1000;
-    openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
-  };
 }

templates/new-clan/machines/sara/configuration.nix

@@ -1,39 +1,33 @@
-{ config, ... }:
-
-let
-  username = config.networking.hostName;
-in
 {
-  imports = [ ./hardware-configuration.nix ];
+  imports = [
+    ./hardware-configuration.nix
+    ../../modules/disko.nix
+    ../../modules/shared.nix
+    # enables GNOME desktop (optional)
+    ../../modules/gnome.nix
+  ];
+  # Put your username here for login
+  users.users.user.name = "<your-username>";
 
-  # Locale service discovery and mDNS
+  # Set this for clan commands use ssh i.e. `clan machines update`
-  services.avahi.enable = true;
+  # If you change the hostname, you need to update this line to root@<new-hostname>
+  # This only works however if you have avahi running on your admin machine else use IP
+  clan.core.networking.targetHost = "root@<IP>";
 
-  services.xserver.enable = true;
+  # You can get your disk id by running the following command on the installer:
-  services.xserver.desktopManager.gnome.enable = true;
+  # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
-  services.xserver.displayManager.gdm.enable = true;
+  # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-  # Disable the default gnome apps to speed up deployment
+  disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
-  services.gnome.core-utilities.enable = false;
 
-  # Enable automatic login for the user.
+  # IMPORTANT! Add your SSH key here
-  services.displayManager.autoLogin = {
+  # e.g. > cat ~/.ssh/id_ed25519.pub
-    enable = true;
+  users.users.root.openssh.authorizedKeys.keys = [''
-    user = username;
+    __YOUR_SSH_KEY__
-  };
+  ''];
-
+  /*
-  users.users.${username} = {
+    After jon is deployed, uncomment the following line
-    initialPassword = username;
+    This will allow sara to share the VPN overlay network with jon
-    isNormalUser = true;
+    The networkId is generated by the first deployment of jon
-    extraGroups = [
+  */
-      "wheel"
+  # clan.core.networking.zerotier.networkId = builtins.readFile ../jon/facts/zerotier-network-id;
-      "networkmanager"
-      "video"
-      "audio"
-      "input"
-      "dialout"
-      "disk"
-    ];
-    uid = 1000;
-    openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
-  };
 }

templates/new-clan/modules/disko.nix

@@ -1,5 +1,7 @@
 { lib, ... }:
 {
+  # TO NOT EDIT THIS FILE AFTER INSTALLATION of a machine
+  # Otherwise your system might not boot because of missing partitions / filesystems
   boot.loader.grub.efiSupport = lib.mkDefault true;
   boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
   disko.devices = {
@@ -23,6 +25,7 @@
                 type = "filesystem";
                 format = "vfat";
                 mountpoint = "/boot";
+                mountOptions = [ "nofail" ];
               };
             };
             root = {
@@ -30,6 +33,8 @@
               content = {
                 type = "filesystem";
                 format = "ext4";
+                # format = "btrfs";
+                # format = "bcachefs";
                 mountpoint = "/";
               };
             };

templates/new-clan/modules/gnome.nix

@@ -0,0 +1,5 @@
+{
+  services.xserver.enable = true;
+  services.xserver.desktopManager.gnome.enable = true;
+  services.xserver.displayManager.gdm.enable = true;
+}

templates/new-clan/modules/shared.nix

@@ -1,7 +1,28 @@
-{ clan-core, ... }:
+{ config, clan-core, ... }:
 {
   imports = [
+    # Enables the OpenSSH server for remote access
     clan-core.clanModules.sshd
+    # Set a root password
     clan-core.clanModules.root-password
+    clan-core.clanModules.user-password
   ];
+
+  # Locale service discovery and mDNS
+  services.avahi.enable = true;
+
+  # generate a random password for our user below
+  # can be read using `clan secrets get <machine-name>-user-password` command
+  clan.user-password.user = "user";
+  users.users.user = {
+    isNormalUser = true;
+    extraGroups = [
+      "wheel"
+      "networkmanager"
+      "video"
+      "input"
+    ];
+    uid = 1000;
+    openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
+  };
 }