From d21d296c5c697e479e866a8eb0adf255e0e834ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= Date: Sun, 21 Jul 2024 21:16:07 +0200 Subject: [PATCH] rework installation template based on received feedback --- docs/site/getting-started/configure.md | 151 +++++++++--------- docs/site/getting-started/deploy.md | 20 +-- docs/site/index.md | 2 +- templates/flake-module.nix | 2 +- templates/new-clan/flake.nix | 97 +++-------- .../new-clan/machines/jon/configuration.nix | 60 ++++--- .../new-clan/machines/sara/configuration.nix | 62 ++++--- templates/new-clan/modules/disko.nix | 5 + templates/new-clan/modules/gnome.nix | 5 + templates/new-clan/modules/shared.nix | 23 ++- 10 files changed, 193 insertions(+), 234 deletions(-) create mode 100644 templates/new-clan/modules/gnome.nix diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index c06b25cf9..8c91e987f 100644 --- a/docs/site/getting-started/configure.md +++ b/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@ 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 `` 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//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" - buildClan { - # ... - machines = { - "jon" = { - imports = [ - # ... - ./modules/disko.nix - ./machines/jon/configuration.nix - ]; - # ... + # Put your username here for login + users.users.user.username = "__YOUR_USERNAME__"; - # 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" + # 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@ + # 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' - disko.devices.disk.main = { - device = "/dev/disk/by-id/__CHANGE_ME__"; - } + # You can get your disk id by running the following command on the installer: + # Replace with the IP of the installer printed on the screen or by running the `ip addr` command. + # ssh root@ 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 - users.users.root.openssh.authorizedKeys.keys = [ - "" - ]; - # ... - }; - }; - } - ``` - - === "**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__" - ]; - # ... - }; - }; - }; - ``` + # IMPORTANT! Add your SSH key here + # 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. `` !!! Example ```bash - clan machines hw-generate jon flash-installer.local + clan machines hw-generate jon ``` - 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 `` 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. --- diff --git a/docs/site/getting-started/deploy.md b/docs/site/getting-started/deploy.md index ff09e188c..3312a606f 100644 --- a/docs/site/getting-started/deploy.md +++ b/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] ``` 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 = { - # "jon" will be the hostname of the machine - "jon" = { - # 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@ - # 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"; - }; - }; + # 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@ + # This only works however if you have avahi running on your admin machine else use IP + clan.core.networking.targetHost = "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. diff --git a/docs/site/index.md b/docs/site/index.md index 74cc4bb7b..7513349c9 100644 --- a/docs/site/index.md +++ b/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 diff --git a/templates/flake-module.nix b/templates/flake-module.nix index 1caecf690..5b746a563 100644 --- a/templates/flake-module.nix +++ b/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; diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix index da1d598d9..342e672f1 100644 --- a/templates/new-clan/flake.nix +++ b/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. - - # 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" ]; - # }; - # }; - # }; + # Ensure this is unique among all clans you want to use. + meta.name = "__CHANGE_ME__"; # 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//configuration.nix to your liking machines = { # "jon" will be the hostname of the machine jon = { - imports = [ - ./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@ - # 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 with the IP of the installer printed on the screen or by running the `ip addr` command. - # ssh root@ 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 = [ "" ] - ''; - - # 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; + imports = [ ./machines/jon/configuration.nix ]; }; # "sara" will be the hostname of the machine sara = { - imports = [ - ./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@ - # 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 with the IP of the installer printed on the screen or by running the `ip addr` command. - # ssh root@ 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 = [ "" ] - ''; - - /* - 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; + imports = [ ./machines/sara/configuration.nix ]; }; }; }; @@ -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 { - packages = [ clan-core.packages.${system}.clan-cli ]; - }; + # use the "nix develop" command to enter the dev shell + 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 ]; + }; + }); }; } diff --git a/templates/new-clan/machines/jon/configuration.nix b/templates/new-clan/machines/jon/configuration.nix index 9fa9a41cd..bcfc7914b 100644 --- a/templates/new-clan/machines/jon/configuration.nix +++ b/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 - services.avahi.enable = true; + # This is your user login name. + users.users.user.name = ""; - services.xserver.enable = true; - services.xserver.desktopManager.gnome.enable = true; - services.xserver.displayManager.gdm.enable = true; - # Disable the default gnome apps to speed up deployment - services.gnome.core-utilities.enable = false; + # 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@ + # This only works however if you have avahi running on your admin machine else use IP + clan.core.networking.targetHost = "root@"; - # Enable automatic login for the user. - services.displayManager.autoLogin = { - enable = true; - user = username; - }; + # You can get your disk id by running the following command on the installer: + # Replace with the IP of the installer printed on the screen or by running the `ip addr` command. + # ssh root@ lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT + disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__"; - users.users.${username} = { - initialPassword = username; - isNormalUser = true; - extraGroups = [ - "wheel" - "networkmanager" - "video" - "audio" - "input" - "dialout" - "disk" - ]; - uid = 1000; - openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys; - }; + # IMPORTANT! Add your SSH key here + # e.g. > cat ~/.ssh/id_ed25519.pub + 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; } diff --git a/templates/new-clan/machines/sara/configuration.nix b/templates/new-clan/machines/sara/configuration.nix index df02f6cad..2e8e9d9fb 100644 --- a/templates/new-clan/machines/sara/configuration.nix +++ b/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 = ""; - # Locale service discovery and mDNS - services.avahi.enable = true; + # 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@ + # This only works however if you have avahi running on your admin machine else use IP + clan.core.networking.targetHost = "root@"; - services.xserver.enable = true; - services.xserver.desktopManager.gnome.enable = true; - services.xserver.displayManager.gdm.enable = true; - # Disable the default gnome apps to speed up deployment - services.gnome.core-utilities.enable = false; + # You can get your disk id by running the following command on the installer: + # Replace with the IP of the installer printed on the screen or by running the `ip addr` command. + # ssh root@ lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT + disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__"; - # Enable automatic login for the user. - services.displayManager.autoLogin = { - enable = true; - user = username; - }; - - users.users.${username} = { - initialPassword = username; - isNormalUser = true; - extraGroups = [ - "wheel" - "networkmanager" - "video" - "audio" - "input" - "dialout" - "disk" - ]; - uid = 1000; - openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys; - }; + # IMPORTANT! Add your SSH key here + # e.g. > cat ~/.ssh/id_ed25519.pub + 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; } diff --git a/templates/new-clan/modules/disko.nix b/templates/new-clan/modules/disko.nix index 7a7509584..a1802a33a 100644 --- a/templates/new-clan/modules/disko.nix +++ b/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 = "/"; }; }; diff --git a/templates/new-clan/modules/gnome.nix b/templates/new-clan/modules/gnome.nix new file mode 100644 index 000000000..bcbc5a148 --- /dev/null +++ b/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; +} diff --git a/templates/new-clan/modules/shared.nix b/templates/new-clan/modules/shared.nix index bcd3118ec..87aead540 100644 --- a/templates/new-clan/modules/shared.nix +++ b/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 -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; + }; }