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 + ``` + + 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@ + ``` + Use the root password displayed on your screen as login. + diff --git a/docs/admins/machines.md b/docs/admins/machines.md index b0de192fb..ba2dc6122 100644 --- a/docs/admins/machines.md +++ b/docs/admins/machines.md @@ -1,89 +1,18 @@ -# Managing NixOS Machines - -## Add Your First Machine - -To start managing a new machine, use the following commands to create and then list your machines: - -```shellSession -$ clan machines create my-machine -$ clan machines list -my-machine -``` - -## Configure Your Machine - -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._ - -## 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 +# Managing NixOS Machines with Clan 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 -- 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. - -## Creating a Bootable USB Drive on Linux - -To create a bootable USB flash drive with the NixOS installer: - -1. **Build the Installer Image**: - - ```shellSession - $ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso - ``` - -2. **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.): - - ```shellSession - sudo umount /dev/sdX* - ``` - -3. **Write the Image to the 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 - ``` - -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. +- [x] A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers. ### 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 `` with the machine's hostname or IP address: -```shellSession -$ clan machines install my-machine +```bash +clan machines install my-machine ``` ## Update Your Machines @@ -94,25 +23,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 @@ -121,8 +50,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` @@ -130,9 +59,15 @@ $ 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: +* 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/migrate.md b/docs/admins/migrate.md new file mode 100644 index 000000000..900f52387 --- /dev/null +++ b/docs/admins/migrate.md @@ -0,0 +1,312 @@ +# Migrating Existing NixOS Configuration Flake to Clan Core + +Transitioning your existing setup to Clan Core is easy and straightforward. Follow this guide to ensure a smooth migration. + +## 0. Prerequisites + +### Backup Your Current Configuration + +Create a backup of your existing NixOS configuration. +This step ensures you have the option to revert to your original setup if necessary. + +```bash +cp -r /etc/nixos ~/nixos-backup +``` + +## 1. Initialize a 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. + +> Note: Clan is based on flakes, it is possible to use cLan without flakes but not officially supported yet. + +### Generate a Trivial flake.nix File + +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. + +```bash +mkdir -p ~/clans/empire && cd ~/clans/empire +nix flake init -t github:NixOS/templates#trivial +``` + +This will initialize a `flake.nix` file that looks like this: + +```nix +# flake.nix +{ + description = "A very basic flake"; + + inputs = { + nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable"; + }; + + outputs = { self, nixpkgs }: { + + packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello; + + packages.x86_64-linux.default = self.packages.x86_64-linux.hello; + + }; +} +``` + +### Initialize a Git Repository (optional/recommended) + +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 . +``` + +> 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. + +Confirm your flake repository is working: + +```bash +nix flake show +``` + +```bash +warning: creating lock file flake.lock' +path: +└───packages + └───x86_64-linux + ├───default: package 'hello-2.12.1' + └───hello: package 'hello-2.12.1' +``` + +## 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; + }; +``` + +## 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` + +```bash +sudo ls -s ~/clans/empire /etc/nixos +``` + +```bash +sudo nixos-rebuild switch +``` + +This rebuilds your system configuration and switches to it. + +> Note: nixos-rebuild switch uses /etc/nixos by default. + +## Finish installation + +- **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 + ``` + +- **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 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. + +Here's how to set up Clan using flakes and flake-parts. + +### 1. Update Your Flake Inputs + +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 +# flake.nix +inputs = { + nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable"; + + # 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. This will make the [clan options](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) available within `mkFlake`. + +```nix + outputs = + inputs@{ flake-parts, ... }: + flake-parts.lib.mkFlake { inherit inputs; } ( + { + imports = [ + inputs.clan-core.flakeModules.default + ]; + } + ); +``` + +### 3. Configure Clan Settings and Define Machines + +Configure your clan settings and define machine configurations. + +Below is a guide on how to structure this in your flake.nix: + +```nix + outputs = + inputs@{ flake-parts, ... }: + flake-parts.lib.mkFlake { inherit inputs; } ( + { + imports = [ + 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 + + machines = { + jons-desktop = { + nixpkgs.hostPlatform = "x86_64-linux"; + imports = [ + clan-core.clanModules.sshd # Add openssh server for cLan management + ./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). + +--- + +## 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/ I think? \ No newline at end of file diff --git a/docs/admins/quickstart.md b/docs/admins/quickstart.md index df04d8618..3136a3bcf 100644 --- a/docs/admins/quickstart.md +++ b/docs/admins/quickstart.md @@ -1,200 +1,76 @@ -# 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`). +### 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. -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: +### 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. - Add `clan-core` to the output +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@:/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@";` + - `clan.diskLayouts.singleDiskExt4 = { + device = "/dev/disk/by-id/__CHANGE_ME__"; + };` - ```diff - - outputs = { self, nixpkgs, }: - + outputs = { self, nixpkgs, clan-core }: - ``` +5. Generate secrets used by clan modules by executing + ```bash + clan facts generate + ``` - 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 install a new machine 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/nixosModules/installer/default.nix b/nixosModules/installer/default.nix index 842e50728..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; + # 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; - #boot.loader.grub.efiInstallAsRemovable = true; - #boot.loader.grub.efiSupport = true; disko.devices = { disk = { stick = { @@ -74,10 +83,11 @@ content = { type = "gpt"; partitions = { - #boot = { - # size = "1M"; - # type = "EF02"; # for grub MBR - #}; + boot = { + priority = 1; + size = "1M"; + type = "EF02"; # for grub MBR + }; ESP = { size = "100M"; type = "EF00"; 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/pkgs/installer/flake-module.nix b/pkgs/installer/flake-module.nix index 6de665776..dc7ee4f2c 100644 --- a/pkgs/installer/flake-module.nix +++ b/pkgs/installer/flake-module.nix @@ -7,7 +7,22 @@ let self.nixosModules.installer self.inputs.nixos-generators.nixosModules.all-formats ]; + # Provide convenience for connecting to wifi + networking.wireless.enable = false; + # 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; }; @@ -30,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; diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix index 2f34b17c1..542f957d4 100644 --- a/templates/new-clan/flake.nix +++ b/templates/new-clan/flake.nix @@ -10,7 +10,61 @@ 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. + 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 = [ + ./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` + config.clan.networking.targetHost = pkgs.lib.mkDefault "root@"; + + # 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.services.getty.autologinUser = "root"; + + # TODO: Document that there needs to be one controller + config.clan.networking.zerotier.controller.enable = true; + } + ]; + }; + sara = { + nixpkgs.hostPlatform = system; + imports = [ + ./machines/sara/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` + config.clan.networking.targetHost = pkgs.lib.mkDefault "root@"; + + # local> clan facts generate + + config.clan.diskLayouts.singleDiskExt4 = { + device = "/dev/disk/by-id/__CHANGE_ME__"; + }; + } + ]; + }; + }; }; in { diff --git a/templates/new-clan/machines/jon/configuration.nix b/templates/new-clan/machines/jon/configuration.nix new file mode 100644 index 000000000..facb35d6f --- /dev/null +++ b/templates/new-clan/machines/jon/configuration.nix @@ -0,0 +1,4 @@ +{ ... }: +{ + +} diff --git a/templates/new-clan/machines/sara/configuration.nix b/templates/new-clan/machines/sara/configuration.nix new file mode 100644 index 000000000..facb35d6f --- /dev/null +++ b/templates/new-clan/machines/sara/configuration.nix @@ -0,0 +1,4 @@ +{ ... }: +{ + +} 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 = "/"; + }; + }; + }; + }; + }; + }; + }; +}