diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index fb9932e3..f2456015 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -52,6 +52,7 @@ theme: - navigation.instant - navigation.tabs - content.code.copy + - content.tabs.link icon: repo: fontawesome/brands/git diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index 2f4875a5..74392ac7 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -10,23 +10,49 @@ In the `flake.nix` file: These icons will be used by our future GUI. -```nix title="clan-core.lib.buildClan" -buildClan { - # Set a unique name - clanName = "Lobsters"; - # Optional, a path to an image file - clanIcon = ./path/to/file; +=== "**buildClan**" - machines = { - jon = { + ```nix title="clan-core.lib.buildClan" + buildClan { + # Set a unique name + clanName = "Lobsters"; + # Optional, a path to an image file + clanIcon = ./path/to/file; + # Should usually point to the directory of flake.nix + directory = ./.; + + machines = { + jon = { + # ... + # Optional, a path to an image file + clanCore.machineIcon = ./path/to/file; + }; # ... - # Optional, a path to an image file - clanCore.machineIcon = ./path/to/file; - }; - # ... + } } -} -``` + ``` + +=== "**flakeParts**" + + !!! info "See [Clan with flake-parts](./flake-parts.md) for help migrating to flake-parts." + + ```nix title="clan-core.flakeModules.default" + clan = { + # Set a unique name + clanName = "Lobsters"; + # Optional, a path to an image file + clanIcon = ./path/to/file; + + machines = { + jon = { + # ... + # Optional, a path to an image file + clanCore.machineIcon = ./path/to/file; + }; + # ... + } + }; + ``` ## Machine configuration @@ -56,27 +82,55 @@ Adding or configuring a new machine requires two simple steps: 1. Edit the following fields inside the `flake.nix` - ```nix title="clan-core.lib.buildClan" - buildClan { - # ... - machines = { - "jon" = { - # ... - - # Change this to the correct ip-address or hostname - # The hostname is the machine name by default - clan.networking.targetHost = pkgs.lib.mkDefault "root@" - - # Change this to the ID-LINK of the desired disk shown by 'lsblk' - clan.diskLayouts.singleDiskExt4 = { - device = "/dev/disk/by-id/__CHANGE_ME__"; - } + === "**buildClan**" + ```nix title="clan-core.lib.buildClan" + buildClan { # ... + machines = { + "jon" = { + # ... + + # Change this to the correct ip-address or hostname + # The hostname is the machine name by default + clan.networking.targetHost = pkgs.lib.mkDefault "root@" + + # Change this to the ID-LINK of the desired disk shown by 'lsblk' + clan.diskLayouts.singleDiskExt4 = { + device = "/dev/disk/by-id/__CHANGE_ME__"; + } + + # ... + }; + }; + } + ``` + + === "**flakeParts**" + + + + ```nix title="clan-core.flakeModules.default" + clan = { + # ... + machines = { + "jon" = { + # ... + + # Change this to the correct ip-address or hostname + # The hostname is the machine name by default + clan.networking.targetHost = pkgs.lib.mkDefault "root@" + + # Change this to the ID-LINK of the desired disk shown by 'lsblk' + clan.diskLayouts.singleDiskExt4 = { + device = "/dev/disk/by-id/__CHANGE_ME__"; + } + + # ... + }; + }; }; - }; - } - ``` + ``` ### Step 2. Detect hardware specific drivers @@ -86,7 +140,7 @@ Adding or configuring a new machine requires two simple steps: ssh root@ nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix ``` -1. Move the generated file to `machines/jon/hardware-configuration.nix`. +2. Move the generated file to `machines/jon/hardware-configuration.nix`. ### Initialize the facts diff --git a/docs/site/getting-started/flake-parts.md b/docs/site/getting-started/flake-parts.md index 9b4fe2ff..eb642923 100644 --- a/docs/site/getting-started/flake-parts.md +++ b/docs/site/getting-started/flake-parts.md @@ -35,6 +35,7 @@ After updating your flake inputs, the next step is to import the `clan-core` fla inputs@{ flake-parts, ... }: flake-parts.lib.mkFlake { inherit inputs; } ( { + # imports = [ inputs.clan-core.flakeModules.default ]; @@ -49,45 +50,53 @@ 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. + outputs = inputs@{ flake-parts, clan-core, ... }: + flake-parts.lib.mkFlake { inherit inputs; } ({self, pkgs, ...}: { + # We define our own systems below. you can still use this to add system specific outputs to your flake. + # See: https://flake.parts/getting-started + systems = []; - 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 - ]; + # import clan-core modules + imports = [ + clan-core.flakeModules.default + ]; + # Define your clan + clan = { + # Clan wide settings. (Required) + clanName = ""; # Ensure to choose a unique name. + + machines = { + jon = { + imports = [ + ./machines/jon/configuration.nix + # ... more modules + ]; + nixpkgs.hostPlatform = "x86_64-linux"; + 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@jon"; + + # remote> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT + clan.diskLayouts.singleDiskExt4 = { + device = "/dev/disk/by-id/nvme-eui.e8238fa6bf530001001b448b4aec2929"; }; + + # There needs to be exactly one controller per clan + clan.networking.zerotier.controller.enable = true; + }; }; - } - ); + }; + }); ``` 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 +## Whats next? -With your flake created, explore how to add new machines by reviewing the documentation provided [here](machines.md). +- [Configure Machines](configure.md): Customize machine configuration +- [Deploying](machines.md): Deploying a Machine configuration --- - -## 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? diff --git a/docs/site/getting-started/installer.md b/docs/site/getting-started/installer.md index 8f5ced27..5bb7f009 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/getting-started/installer.md @@ -4,32 +4,34 @@ We offer a dedicated installer to assist remote installations. In this tutorial we will guide you through building and flashing it to a bootable USB drive. -## Step 0. Prerequisites +## Creating and Using the **Clan Installer** + +### Step 0. Prerequisites - [x] A free USB Drive with at least 1.5GB (All data on it will be lost) - [x] Linux/NixOS Machine with Internet -## Step 1. Identify the USB Flash Drive +### Step 1. Identify the USB Flash Drive 1. Insert your USB flash drive into your computer. -1. Identify your flash drive with `lsblk`: +2. Identify your flash drive with `lsblk`: -```bash -$ lsblk -``` + ```bash + $ lsblk + ``` -```{.console, .no-copy} -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 / -``` + ```{.console, .no-copy} + 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 is `sdb`. + !!! Info "In this case the USB device is `sdb`" 3. Ensure all partitions on the drive are unmounted. Replace `sdb1` in the command below with your device identifier (like `sdc1`, etc.): @@ -45,14 +47,20 @@ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso ### Step 3. Flash the Installer to the USB Drive +!!! Danger "Specifying the wrong device can lead to unrecoverable data loss." + + The `dd` utility will erase the disk. Make sure to specify the correct device (`of=...`) + + If your USB device is `sdb` use `of=/dev/sdb` + + + 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 of=/dev/sd ``` -If your USB device is `sdb` use `of=/dev/sdb`. - ### Step 4. Boot and Connect to your network After writing the installer to the USB drive, use it to boot the target machine. @@ -73,8 +81,6 @@ After writing the installer to the USB drive, use it to boot the target machine. - **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. @@ -83,19 +89,19 @@ Select `NixOS` to boot into the clan installer. For deploying your configuration the machine needs to be connected via LAN (recommended). -For connecting via Wifi, please consult the guide below. +For connecting via Wifi, please consult the [guide below](#optional-connect-to-wifi). --- -### Whats next? +## Whats next? -- [Configure Machines](configure.md): Customise machine configuration +- [Configure Machines](configure.md): Customize machine configuration - [Deploying](machines.md): Deploying a Machine configuration - [WiFi](#optional-connect-to-wifi): Guide for connecting to Wifi. --- -### (Optional) Connect to Wifi +## (Optional) Connect to Wifi If you don't have access via LAN the Installer offers support for connecting via Wifi. @@ -114,7 +120,7 @@ Now run the following command to connect to your Wifi: ```bash # Identify your network device. device list -# Replace 'wlan0' with your device name +# Replace 'wlan0' with your wireless device name # Find your Wifi SSID. station wlan0 scan station wlan0 get-networks @@ -137,4 +143,7 @@ IPv4 address 192.168.188.50 (Your new local ip) Press `ctrl-d` to exit `IWD`. -Press `ctrl-d` **again** to update the displayed QR code and connection information. +!!! Important + Press `ctrl-d` **again** to update the displayed QR code and connection information. + +You're all set up diff --git a/flakeModules/clan.nix b/flakeModules/clan.nix index c1224118..c53826cc 100644 --- a/flakeModules/clan.nix +++ b/flakeModules/clan.nix @@ -4,6 +4,7 @@ clan-core: lib, flake-parts-lib, inputs, + self, ... }: let @@ -20,6 +21,7 @@ in directory = mkOption { type = types.path; description = "The directory containing the clan subdirectory"; + default = self; # default to the directory of the flake }; specialArgs = mkOption { type = types.attrsOf types.raw; diff --git a/templates/new-clan/flake.nix b/templates/new-clan/flake.nix index e7ef6236..5f5ccd8a 100644 --- a/templates/new-clan/flake.nix +++ b/templates/new-clan/flake.nix @@ -8,12 +8,14 @@ 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; clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique. clanIcon = null; # Optional, a path to an image file - # Prerequisite: boot into the installer + # 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 machines = { @@ -21,7 +23,6 @@ imports = [ ./modules/shared.nix ./machines/jon/configuration.nix - ./machines/jon/hardware-configuration.nix ]; nixpkgs.hostPlatform = system; @@ -45,7 +46,6 @@ imports = [ ./modules/shared.nix ./machines/sara/configuration.nix - ./machines/sara/hardware-configuration.nix ]; nixpkgs.hostPlatform = system; diff --git a/templates/new-clan/machines/jon/configuration.nix b/templates/new-clan/machines/jon/configuration.nix index a6d0abee..c84ebb69 100644 --- a/templates/new-clan/machines/jon/configuration.nix +++ b/templates/new-clan/machines/jon/configuration.nix @@ -1,5 +1,6 @@ { ... }: { + imports = [ ./hardware-configuration.nix ]; users.users.root.openssh.authorizedKeys.keys = [ # IMPORTANT! Add your SSH key here # e.g. > cat ~/.ssh/id_ed25519.pub diff --git a/templates/new-clan/machines/sara/configuration.nix b/templates/new-clan/machines/sara/configuration.nix index b98037b3..c84ebb69 100644 --- a/templates/new-clan/machines/sara/configuration.nix +++ b/templates/new-clan/machines/sara/configuration.nix @@ -1,6 +1,6 @@ { ... }: { - + imports = [ ./hardware-configuration.nix ]; users.users.root.openssh.authorizedKeys.keys = [ # IMPORTANT! Add your SSH key here # e.g. > cat ~/.ssh/id_ed25519.pub