From 4b8f83de9e8d8defb8d707aa8e5a31dffedae6d7 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 15:17:02 +0200 Subject: [PATCH 1/8] docs: create clan update cli instructions --- docs/site/guides/getting-started/index.md | 60 ++++++++++++----------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/docs/site/guides/getting-started/index.md b/docs/site/guides/getting-started/index.md index 3e33018f3..83908f77a 100644 --- a/docs/site/guides/getting-started/index.md +++ b/docs/site/guides/getting-started/index.md @@ -38,31 +38,24 @@ By the end of this guide, you'll have a fresh NixOS configuration ready to push ## Add Clan CLI to Your Shell -Add the Clan CLI into your environment: +Create a new clan ```bash -nix shell git+https://git.clan.lol/clan/clan-core#clan-cli --refresh +nix run git+https://git.clan.lol/clan/clan-core#clan-cli --refresh -- flakes create ``` +This should prompt for a *name*: + ```terminalSession -clan --help +Enter a name for the new clan: my-clan ``` -Should print the available commands. +Enter a *name*, confirm with *enter*. A directory with that name will be created and initialized. -Also checkout the [cli-reference documentation](../../reference/cli/index.md). +!!! Note + This command uses the `default` template -## Initialize Your Project - -If you want to migrate an existing project, follow this [guide](../migrations/migration-guide.md). - -Set the foundation of your Clan project by initializing it by running: - -```bash -clan flakes create my-clan -``` - -This command creates a `flake.nix` and some other files for your project. + See `clan templates list` and the `--help` reference for how to use other templates. ## Explore the Project Structure @@ -83,25 +76,24 @@ For example, you might see something like: └── README.md ``` -Don’t worry if your output looks different—the template evolves over time. +Don’t worry if your output looks different — Clan templates evolves over time. -??? info "Recommended way of sourcing the `clan` CLI tool" +To interact with your newly created clan the you need to load the `clan` cli-package it into your environment by running: - The default template adds the `clan` CLI tool to the development shell. - This means that you can access the `clan` CLI tool directly from the folder - you are in right now. +=== "Automatic (direnv, recommended)" + Prerequisite: [Install Direnv](https://direnv.net/docs/installation.html) - In the `my-clan` directory, run the following command: + ``` + direnv allow + ``` + +=== "Manual (nix develop)" ``` nix develop ``` - This will ensure the `clan` CLI tool is available in your shell environment. - - To automatically add the `clan` CLI tool to your environment without having to - run `nix develop` every time, we recommend setting up [direnv](https://direnv.net/). - +verify that you can run `clan` commands: ``` clan show ``` @@ -109,10 +101,22 @@ clan show You should see something like this: ```terminal-session -Name: my-clan +Name: __CHANGE_ME__ Description: None ``` +To change the name of your clan edit `meta.name` in the `clan.nix` or `flake.nix` file + +```{.nix title="clan.nix" hl_lines="3"} +{ + # Ensure this is unique among all clans you want to use. + meta.name = "__CHANGE_ME__"; + + # ... + # elided +} +``` + --- ## Next Steps From fb60ae80827ccaca7f71a852d8e9e484867d0aba Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 15:17:25 +0200 Subject: [PATCH 2/8] docs: add machines update instructions --- .../guides/getting-started/add-machines.md | 80 +++++-------------- 1 file changed, 21 insertions(+), 59 deletions(-) diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index 8c10dc499..b6d2bb834 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -10,64 +10,23 @@ See the complete [list](../../guides/more-machines.md#automatic-registration) of ## Create a machine -=== "flake.nix (flake-parts)" +=== "clan.nix (declarative)" - ```{.nix hl_lines=12-15} + ```{.nix hl_lines="3-4"} { - inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; - inputs.nixpkgs.follows = "clan-core/nixpkgs"; - inputs.flake-parts.follows = "clan-core/flake-parts"; - inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs"; - - outputs = - inputs@{ flake-parts, ... }: - flake-parts.lib.mkFlake { inherit inputs; } { - imports = [ inputs.clan-core.flakeModules.default ]; - clan = { - inventory.machines = { - # Define a machine - jon = { }; - }; - }; - - systems = [ - "x86_64-linux" - "aarch64-linux" - "x86_64-darwin" - "aarch64-darwin" - ]; + inventory.machines = { + # Define a machine + jon = { }; }; - } - ``` -=== "flake.nix (classic)" - - ```{.nix hl_lines=11-14} - { - inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; - inputs.nixpkgs.follows = "clan-core/nixpkgs"; - - outputs = - { self, clan-core, ... }: - let - clan = clan-core.lib.clan { - inherit self; - - inventory.machines = { - # Define a machine - jon = { }; - }; - }; - in - { - inherit (clan.config) - nixosConfigurations - nixosModules - clanInternals - darwinConfigurations - darwinModules - ; - }; + # Additional NixOS configuration can be added here. + # machines/jon/configuration.nix will be automatically imported. + # See: https://docs.clan.lol/guides/more-machines/#automatic-registration + machines = { + # jon = { config, ... }: { + # environment.systemPackages = [ pkgs.asciinema ]; + # }; + }; } ``` @@ -89,16 +48,18 @@ See the complete [list](../../guides/more-machines.md#automatic-registration) of The option: `machines.` is used to add extra *nixosConfiguration* to a machine -```{.nix .annotate title="flake.nix" hl_lines="3-13 18-22"} -# Sometimes this attribute set is defined in clan.nix -clan = { +Add the following to your `clan.nix` file for each machine. +This example demonstrates what is needed based on a machine called `jon`: + +```{.nix .annotate title="clan.nix" hl_lines="3-9 18-22"} +{ inventory.machines = { jon = { # Define targetHost here # Required before deployment deploy.targetHost = "root@jon"; # (1) - # Define tags here - tags = [ ]; + # Define tags here (optional) + tags = [ ]; # (3) }; sara = { deploy.targetHost = "root@sara"; @@ -119,6 +80,7 @@ clan = { 1. It is required to define a *targetHost* for each machine before deploying. Best practice has been, to use the zerotier ip/hostname or the ip from the from overlay network you decided to use. 2. Add your *ssh key* here - That will ensure you can always login to your machine via *ssh* in case something goes wrong. +3. Tags can be used to automatically add this machine to services later on. - You dont need to set this now. ### (Optional) Renaming a Machine From 83278097f6f2eee4cb0ac4621fc66051d8aaf614 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 15:20:32 +0200 Subject: [PATCH 3/8] docs: add service update instructions --- .../guides/getting-started/add-services.md | 135 +++++++----------- 1 file changed, 54 insertions(+), 81 deletions(-) diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/guides/getting-started/add-services.md index a4355b112..95b39d156 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/guides/getting-started/add-services.md @@ -17,104 +17,77 @@ To learn more: [Guide about clanService](../clanServices.md) ## Configure a Zerotier Network (recommended) -```{.nix title="flake.nix" hl_lines="20-28"} +```{.nix title="clan.nix" hl_lines="12-20"} { - inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; - inputs.nixpkgs.follows = "clan-core/nixpkgs"; - inputs.flake-parts.follows = "clan-core/flake-parts"; - inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs"; - - outputs = - inputs@{ flake-parts, ... }: - flake-parts.lib.mkFlake { inherit inputs; } { - imports = [ inputs.clan-core.flakeModules.default ]; - # Sometimes this attribute set is defined in clan.nix - clan = { - inventory.machines = { - jon = { - targetHost = "root@jon"; - }; - sara = { - targetHost = "root@jon"; - }; - }; - inventory.instances = { - zerotier = { # (1) - # Defines 'jon' as the controller - roles.controller.machines.jon = {}; - # Defines all machines as networking peer. - # The 'all' tag is a clan builtin. - roles.peer.tags.all = {}; - }; - } - }; - - systems = [ - "x86_64-linux" - "aarch64-linux" - "x86_64-darwin" - "aarch64-darwin" - ]; + inventory.machines = { + jon = { + targetHost = "root@jon"; + }; + sara = { + targetHost = "root@jon"; + }; }; + + inventory.instances = { + zerotier = { # (1) + # Replace with the name (string) of your machine that you will use as zerotier-controller + # See: https://docs.zerotier.com/controller/ + # Deploy this machine first to create the network secrets + roles.controller.machines."jon" = { }; # (2) + # Peers of the network + # this line means 'all' clan machines will be 'peers' + roles.peer.tags.all = { }; # (3) + }; + }; + # ... + # elided } ``` 1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them. Or read [authoring/clanServices](../authoring/clanServices/index.md) if you want to bring your own +2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine. + +3. This line will add all machines of your clan as `peer` to zerotier + ## Adding more recommended defaults Adding the following services is recommended for most users: -```{.nix title="flake.nix" hl_lines="25-35"} +```{.nix title="clan.nix" hl_lines="11-26"} { - inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; - inputs.nixpkgs.follows = "clan-core/nixpkgs"; - inputs.flake-parts.follows = "clan-core/flake-parts"; - inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs"; - - outputs = - inputs@{ flake-parts, ... }: - flake-parts.lib.mkFlake { inherit inputs; } { - imports = [ inputs.clan-core.flakeModules.default ]; - # Sometimes this attribute set is defined in clan.nix - clan = { - inventory.machines = { - jon = { - targetHost = "root@jon"; - }; - sara = { - targetHost = "root@jon"; - }; - }; - inventory.instances = { - zerotier = { - roles.controller.machines.jon = {}; - roles.peer.tags.all = {}; - }; - admin = { # (1) - roles.default.tags.all = { }; - roles.default.settings = { - allowedKeys = { - "my-user" = "ssh-ed25519 AAAAC3N..."; # elided - }; - }; - }; - state-version = { # (2) - roles.default.tags.all = { }; - }; + inventory.machines = { + jon = { + targetHost = "root@jon"; + }; + sara = { + targetHost = "root@jon"; + }; + }; + inventory.instances = { + admin = { # (1) + roles.default.tags.all = { }; + roles.default.settings = { + allowedKeys = { + "my-user" = "ssh-ed25519 AAAAC3N..."; # elided }; }; - systems = [ - "x86_64-linux" - "aarch64-linux" - "x86_64-darwin" - "aarch64-darwin" - ]; + }; + jon-user = { # (2) + module.name = "users"; + + roles.default.tags.all = { }; + roles.default.settings = { + user = "jon"; # (3) + }; + }; + # ... + # elided }; } + ``` 1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration. - -2. The `state-version` service will generate a [nixos state version](https://wiki.nixos.org/wiki/FAQ/When_do_I_update_stateVersion) for each system once it is deployed. \ No newline at end of file +2. Adds `jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment. From 0dc867c0b6d39271c2e65b52522d2b142b6ff2db Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 16:15:17 +0200 Subject: [PATCH 4/8] docs: add guide how to create configuration.nix --- docs/site/guides/getting-started/add-machines.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index b6d2bb834..f5c3732fd 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -82,6 +82,21 @@ This example demonstrates what is needed based on a machine called `jon`: 2. Add your *ssh key* here - That will ensure you can always login to your machine via *ssh* in case something goes wrong. 3. Tags can be used to automatically add this machine to services later on. - You dont need to set this now. +### (Optional) Create a `configuration.nix` + +```nix title="./machines/jon/configuration.nix" +{ + imports = [ + # enables GNOME desktop (optional) + ../../modules/gnome.nix + ]; + + # Set nixosOptions here + # Or import your own modules via 'imports' + # ... +} +``` + ### (Optional) Renaming a Machine Older templates included static machine folders like `jon` and `sara`. From 821f5c2bc2e11cf913e9e687734b09df527fe8d3 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 16:15:41 +0200 Subject: [PATCH 5/8] Docs: rewrite deployment instructions --- docs/site/guides/getting-started/deploy.md | 337 +++++++++------------ 1 file changed, 143 insertions(+), 194 deletions(-) diff --git a/docs/site/guides/getting-started/deploy.md b/docs/site/guides/getting-started/deploy.md index 6d26bff4f..cceaeadac 100644 --- a/docs/site/guides/getting-started/deploy.md +++ b/docs/site/guides/getting-started/deploy.md @@ -1,6 +1,6 @@ # Deploy a machine -Now that you have created a new machine, we will walk through how to install it. +Now that you have created a machines, added some services and setup secrets. This guide will walk through how to deploy it. ## Prerequisites @@ -10,231 +10,180 @@ Now that you have created a new machine, we will walk through how to install it. - [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md) - [x] **Initialized secrets**: See [secrets](secrets.md) for how to initialize your secrets. -=== "**Physical Hardware**" +## Physical Hardware - - [x] **USB Flash Drive**: See [Clan Installer](installer.md) +!!! note "skip this if using a cloud VM" - !!! Steps +Steps: - 1. Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md). +- Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md). +- Boot the target machine and connect it to a network that makes it reachable from your setup computer. +- Note down a reachable ip adress (*ipv4*, *ipv6* or *tor*) - 2. Boot the target machine and connect it to a network that makes it reachable from your setup computer. +--- -=== "**Cloud VMs**" +The installer will generate a password and local addresses on boot, then run ssh with these preconfigured. +The installer shows it's deployment relevant information in two formats, a text form, as well as a QR code. - - [x] Any cloud machine if it is reachable via SSH and supports `kexec`. +Sample boot screen shows: - !!! Warning "NixOS can cause strange issues when booting in certain cloud environments." - If on Linode: Make sure that the system uses Direct Disk boot kernel (found in the configuration pannel) +- Root password +- IP address +- Optional Tor and mDNS details + +```{ .bash .annotate .no-copy .nohighlight} +┌─────────────────────────────────────────────────────────────────────────────────────┐ +│ ┌───────────────────────────┐ │ +│ │███████████████████████████│ # This is the QR Code (1) │ +│ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│ │ +│ │██ █ █ █▀▄▄▄█ ▀█ █ █ ██│ │ +│ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│ │ +│ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│ │ +│ │███▀▀▀ █▄▄█ ▀▄ ▄▀▄█ ███│ │ +│ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│ │ +│ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│ │ +│ │██ █ █ █ █ █ ▄▄▄ ▄▀▀ ██│ │ +│ │██ █▄▄▄█ █ ▄ ▄ ▄ ▀█ ▄███│ │ +│ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│ │ +│ │███████████████████████████│ │ +│ └───────────────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │Root password: cheesy-capital-unwell # password (2) │ │ +│ │Local network addresses: │ │ +│ │enp1s0 UP 192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │ +│ │enp2s0 DOWN │ │ +│ │wlan0 DOWN # connect to wlan (3) │ │ +│ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │ +│ │Multicast DNS: nixos-installer.local │ │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ Press 'Ctrl-C' for console access │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────────┘ +``` + +1. This is not an actual QR code, because it is displayed rather poorly on text sites. + This would be the actual content of this specific QR code prettified: + ```json + { + "pass": "cheesy-capital-unwell", + "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion", + "addrs": [ + "2001:9e8:347:ca00:21e:6ff:fe45:3c92" + ] + } + ``` + + To generate the actual QR code, that would be displayed use: + ```shellSession + echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8 + ``` +2. The root password for the installer medium. + This password is autogenerated and meant to be easily typeable. +3. See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually). + +!!! tip + Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop + +## Cloud VMs + +!!! note "skip this if using a physical machine" + +Clan supports any cloud machine if it is reachable via SSH and supports `kexec`. + +Steps: + +- Go to the configuration panel and note down how to connect to the machine via ssh. + +!!! tip "NixOS can cause strange issues when booting in certain cloud environments." + If on Linode: Make sure that the system uses "Direct Disk boot kernel" (found in the configuration panel) ## Setting `targetHost` -=== "flake.nix (flake-parts)" +In your nix files set the targetHost (reachable ip) that you retrieved in the previous step. - ```{.nix hl_lines="22"} - { - inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; - inputs.nixpkgs.follows = "clan-core/nixpkgs"; - inputs.flake-parts.follows = "clan-core/flake-parts"; - inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs"; +```{.nix title="clan.nix" hl_lines="9"} +{ + # Ensure this is unique among all clans you want to use. + meta.name = "my-clan"; - outputs = - inputs@{ flake-parts, ... }: - flake-parts.lib.mkFlake { inherit inputs; } { - systems = [ - "x86_64-linux" - "aarch64-linux" - "x86_64-darwin" - "aarch64-darwin" - ]; - imports = [ inputs.clan-core.flakeModules.default ]; + inventory.machines = { + # Define machines here. + # The machine name will be used as the hostname. + jon = { + deploy.targetHost = "root@192.168.192.4"; # (1) + }; + }; + # ... + # elided +} +``` - clan = { - inventory.machines = { - jon = { - # targetHost will get picked up by cli commands - deploy.targetHost = "root@jon"; - }; - }; - }; - }; - } - ``` - -=== "flake.nix (classic)" - - ```{.nix hl_lines="14"} - { - inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; - inputs.nixpkgs.follows = "clan-core/nixpkgs"; - - outputs = - { self, clan-core, ... }: - let - clan = clan-core.lib.clan { - inherit self; - - inventory.machines = { - jon = { - # targetHost will get picked up by cli commands - deploy.targetHost = "root@jon"; - }; - }; - }; - in - { - inherit (clan.config) - nixosConfigurations - nixosModules - clanInternals - darwinConfigurations - darwinModules - ; - }; - } - ``` +1. Use the ip address of your targetMachine that you want to deploy. If using the [flash-installer](./installer.md) it should display its local ip-address when booted. !!! 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. -## Identify the Target Disk +See also [how to set TargetHost](../target-host.md) for other methods. -On the setup computer, SSH into the target: +## Retrieve the hardware report -```bash title="setup computer" -ssh root@ lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT +By default clan uses [nixos-facter](https://github.com/nix-community/nixos-facter) which captures detailed information about the machine or virtual environment. + +To generate the hardware-report (`facter.json`) run: + +```bash +clan machines update-hardware-config ``` -Replace `` with the machine's IP or hostname if mDNS (i.e. Avahi) is available. +Example output: -Which should show something like: - -```{.shellSession hl_lines="6" .no-copy} -NAME ID-LINK FSTYPE SIZE MOUNTPOINT -sda usb-ST_16GB_AA6271026J1000000509-0:0 14.9G -├─sda1 usb-ST_16GB_AA6271026J1000000509-0:0-part1 1M -├─sda2 usb-ST_16GB_AA6271026J1000000509-0:0-part2 vfat 100M /boot -└─sda3 usb-ST_16GB_AA6271026J1000000509-0:0-part3 ext4 2.9G / -nvme0n1 nvme-eui.e8238fa6bf530001001b448b4aec2929 476.9G -├─nvme0n1p1 nvme-eui.e8238fa6bf530001001b448b4aec2929-part1 vfat 512M -├─nvme0n1p2 nvme-eui.e8238fa6bf530001001b448b4aec2929-part2 ext4 459.6G -└─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap 16.8G +```shell-session +$ clan machines update-hardware-config jon +[jon] $ nixos-facter +Successfully generated: ./machines/jon/facter.json ``` -Look for the top-level disk device (e.g., nvme0n1 or sda) and copy its `ID-LINK`. Avoid using partition IDs like `nvme0n1p1`. +See [update-hardware-config cli reference](../../reference/cli/machines.md#machines-update-hardware-config) for further configuration possibilities if needed. -In this example we would copy `nvme-eui.e8238fa6bf530001001b448b4aec2929` +## Configure your disk schema + +By default clan uses [disko](https://github.com/nix-community/disko) which allows for declarative disk partitioning. + +To setup a disk schema for a machine run + +```bash +clan templates apply disk --to-machine jon --template single-disk --set mainDisk "" +``` + +Which should fail and give the valid options for the specific hardware: + +```terminal-session +Invalid value for placeholder mainDisk - Valid options: +/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368 +``` + +Re-run the command with the correct disk: + +```bash +clan templates apply disk --to-machine jon --template single-disk --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368" +``` + +Should now be succesfull + +```terminal-session +Applied disk template 'single-disk' to machine 'jon' +``` + +A disko.nix file should be created in `machines/jon` +You can have a look and customize it if needed. !!! tip For advanced partitioning, see [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example). -## Fill in hardware specific machine configuration - -Edit the following fields inside the `./machines//configuration.nix` - - - -```nix title="./machines/jon/configuration.nix" hl_lines="12 15 19" -{ - imports = [ - # 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 - ]; - - # Put your username here for login - users.users.user.name = "__YOUR_USERNAME__"; - - # Replace this __CHANGE_ME__ with the copied result of the lsblk command - 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 = [ "__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 `__CHANGE_ME__` with the appropriate `ID-LINK` identifier, such as `nvme-eui.e8238fa6bf530001001b448b4aec2929`" -!!! Info "Replace `__YOUR_SSH_KEY__` with your personal key, like `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop`" - ## Deploy the machine -**Finally deployment time!** Use the following command to build and deploy the image via SSH onto your machine. - -=== "**Image Installer**" - - The installer will generate a password and local addresses on boot, then run ssh with these preconfigured. - The installer shows it's deployment relevant information in two formats, a text form, as well as a QR code. - - Sample boot screen shows: - - - Root password - - IP address - - Optional Tor and mDNS details - - ```{ .bash .annotate .no-copy .nohighlight} - ┌─────────────────────────────────────────────────────────────────────────────────────┐ - │ ┌───────────────────────────┐ │ - │ │███████████████████████████│ # This is the QR Code (1) │ - │ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│ │ - │ │██ █ █ █▀▄▄▄█ ▀█ █ █ ██│ │ - │ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│ │ - │ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│ │ - │ │███▀▀▀ █▄▄█ ▀▄ ▄▀▄█ ███│ │ - │ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│ │ - │ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│ │ - │ │██ █ █ █ █ █ ▄▄▄ ▄▀▀ ██│ │ - │ │██ █▄▄▄█ █ ▄ ▄ ▄ ▀█ ▄███│ │ - │ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│ │ - │ │███████████████████████████│ │ - │ └───────────────────────────┘ │ - │ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ - │ │Root password: cheesy-capital-unwell # password (2) │ │ - │ │Local network addresses: │ │ - │ │enp1s0 UP 192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │ - │ │enp2s0 DOWN │ │ - │ │wlan0 DOWN # connect to wlan (3) │ │ - │ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion │ │ - │ │Multicast DNS: nixos-installer.local │ │ - │ └─────────────────────────────────────────────────────────────────────────────────┘ │ - │ Press 'Ctrl-C' for console access │ - │ │ - └─────────────────────────────────────────────────────────────────────────────────────┘ - ``` - - 1. This is not an actual QR code, because it is displayed rather poorly on text sites. - This would be the actual content of this specific QR code prettified: - ```json - { - "pass": "cheesy-capital-unwell", - "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion", - "addrs": [ - "2001:9e8:347:ca00:21e:6ff:fe45:3c92" - ] - } - ``` - - To generate the actual QR code, that would be displayed use: - ```shellSession - echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8 - ``` - 2. The root password for the installer medium. - This password is autogenerated and meant to be easily typeable. - 3. See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually). - - !!! tip - Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop - -=== "**Cloud VM**" - - Just run the command **Option B: Cloud VM** below +**Finally deployment time!** Use one of the following commands to build and deploy the image via SSH onto your machine. ### Deployment Commands From 6d24117d0c398f6536fb0b3de7ca7eeff1fb7f8d Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 16:34:48 +0200 Subject: [PATCH 6/8] Docs: align workflow, remove targetHost before deployment --- .../guides/getting-started/add-machines.md | 10 ++----- .../guides/getting-started/add-services.md | 29 +++++++------------ 2 files changed, 14 insertions(+), 25 deletions(-) diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index f5c3732fd..5cf0ee197 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -51,15 +51,12 @@ See the complete [list](../../guides/more-machines.md#automatic-registration) of Add the following to your `clan.nix` file for each machine. This example demonstrates what is needed based on a machine called `jon`: -```{.nix .annotate title="clan.nix" hl_lines="3-9 18-22"} +```{.nix .annotate title="clan.nix" hl_lines="3-6 15-19"} { inventory.machines = { jon = { - # Define targetHost here - # Required before deployment - deploy.targetHost = "root@jon"; # (1) # Define tags here (optional) - tags = [ ]; # (3) + tags = [ ]; # (1) }; sara = { deploy.targetHost = "root@sara"; @@ -78,9 +75,8 @@ This example demonstrates what is needed based on a machine called `jon`: } ``` -1. It is required to define a *targetHost* for each machine before deploying. Best practice has been, to use the zerotier ip/hostname or the ip from the from overlay network you decided to use. +1. Tags can be used to automatically add this machine to services later on. - You dont need to set this now. 2. Add your *ssh key* here - That will ensure you can always login to your machine via *ssh* in case something goes wrong. -3. Tags can be used to automatically add this machine to services later on. - You dont need to set this now. ### (Optional) Create a `configuration.nix` diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/guides/getting-started/add-services.md index 95b39d156..80d3dc797 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/guides/getting-started/add-services.md @@ -17,15 +17,11 @@ To learn more: [Guide about clanService](../clanServices.md) ## Configure a Zerotier Network (recommended) -```{.nix title="clan.nix" hl_lines="12-20"} +```{.nix title="clan.nix" hl_lines="8-16"} { inventory.machines = { - jon = { - targetHost = "root@jon"; - }; - sara = { - targetHost = "root@jon"; - }; + jon = { }; + sara = { }; }; inventory.instances = { @@ -55,31 +51,27 @@ To learn more: [Guide about clanService](../clanServices.md) Adding the following services is recommended for most users: -```{.nix title="clan.nix" hl_lines="11-26"} +```{.nix title="clan.nix" hl_lines="7-22"} { inventory.machines = { - jon = { - targetHost = "root@jon"; - }; - sara = { - targetHost = "root@jon"; - }; + jon = { }; + sara = { }; }; inventory.instances = { admin = { # (1) roles.default.tags.all = { }; roles.default.settings = { allowedKeys = { - "my-user" = "ssh-ed25519 AAAAC3N..."; # elided + "my-user" = "ssh-ed25519 AAAAC3N..."; # (2) }; }; }; - jon-user = { # (2) + jon-user = { # (3) module.name = "users"; roles.default.tags.all = { }; roles.default.settings = { - user = "jon"; # (3) + user = "jon"; }; }; # ... @@ -90,4 +82,5 @@ Adding the following services is recommended for most users: ``` 1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration. -2. Adds `jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment. +2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](./add-machines.md#configuring-a-machine) +3. Adds `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment. From 582cbff138e52c895e42f16af6196b508bd7f17d Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 16:39:20 +0200 Subject: [PATCH 7/8] Docs: fix typos --- docs/site/guides/getting-started/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/site/guides/getting-started/index.md b/docs/site/guides/getting-started/index.md index 83908f77a..fbbba9e75 100644 --- a/docs/site/guides/getting-started/index.md +++ b/docs/site/guides/getting-started/index.md @@ -76,12 +76,12 @@ For example, you might see something like: └── README.md ``` -Don’t worry if your output looks different — Clan templates evolves over time. +Don’t worry if your output looks different — Clan templates evolve over time. To interact with your newly created clan the you need to load the `clan` cli-package it into your environment by running: === "Automatic (direnv, recommended)" - Prerequisite: [Install Direnv](https://direnv.net/docs/installation.html) + - prerequisite: [install nix-direnv](https://github.com/nix-community/nix-direnv) ``` direnv allow @@ -94,7 +94,8 @@ To interact with your newly created clan the you need to load the `clan` cli-pac ``` verify that you can run `clan` commands: -``` + +```bash clan show ``` From 0ec26ff0aba9cce0f59bb474c253782848223639 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sat, 12 Jul 2025 16:40:02 +0200 Subject: [PATCH 8/8] Docs: fix code annotations --- docs/site/guides/getting-started/deploy.md | 4 ++-- docs/site/guides/getting-started/index.md | 2 +- docs/site/guides/migrations/disk-id.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/site/guides/getting-started/deploy.md b/docs/site/guides/getting-started/deploy.md index cceaeadac..945f29ffd 100644 --- a/docs/site/guides/getting-started/deploy.md +++ b/docs/site/guides/getting-started/deploy.md @@ -158,7 +158,7 @@ clan templates apply disk --to-machine jon --template single-disk --set mainDisk Which should fail and give the valid options for the specific hardware: -```terminal-session +```shellSession Invalid value for placeholder mainDisk - Valid options: /dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368 ``` @@ -171,7 +171,7 @@ clan templates apply disk --to-machine jon --template single-disk --set mainDisk Should now be succesfull -```terminal-session +```shellSession Applied disk template 'single-disk' to machine 'jon' ``` diff --git a/docs/site/guides/getting-started/index.md b/docs/site/guides/getting-started/index.md index fbbba9e75..8554c6c56 100644 --- a/docs/site/guides/getting-started/index.md +++ b/docs/site/guides/getting-started/index.md @@ -101,7 +101,7 @@ clan show You should see something like this: -```terminal-session +```shellSession Name: __CHANGE_ME__ Description: None ``` diff --git a/docs/site/guides/migrations/disk-id.md b/docs/site/guides/migrations/disk-id.md index db936922b..f71d63d11 100644 --- a/docs/site/guides/migrations/disk-id.md +++ b/docs/site/guides/migrations/disk-id.md @@ -52,7 +52,7 @@ clan vars list Which should print the generated `disk-id/diskId` value in clear text You should see output like: -```terminal-session +```shellSession disk-id/diskId: fcef30a749f8451d8f60c46e1ead726f # ... # elided