diff --git a/docs/site/guides/disk-encryption.md b/docs/site/guides/disk-encryption.md index 215f89ed3..e38c4ae13 100644 --- a/docs/site/guides/disk-encryption.md +++ b/docs/site/guides/disk-encryption.md @@ -63,8 +63,7 @@ Replace `kernelModules` with the ethernet module loaded one on your target machi } ``` - -### Step 1: Copying SSH Public Key +## Copying SSH Public Key Before starting the installation process, ensure that the SSH public key is copied to the NixOS installer. @@ -74,7 +73,7 @@ Before starting the installation process, ensure that the SSH public key is copi ssh-copy-id -o PreferredAuthentications=password -o PubkeyAuthentication=no root@nixos-installer.local ``` -### Step 1.5: Prepare Secret Key and Partition Disks +## Prepare Secret Key and Partition Disks 1. Access the installer using SSH: @@ -100,7 +99,7 @@ blkdiscard /dev/disk/by-id/ clan machines install gchq-local --target-host root@nixos-installer --phases kexec,disko ``` -### Step 2: ZFS Pool Import and System Installation +## ZFS Pool Import and System Installation 1. SSH into the installer once again: @@ -151,7 +150,7 @@ zpool export zroot 8. Perform a reboot of the machine and remove the USB installer. -### Step 3: Accessing the Initial Ramdisk (initrd) Environment +## Accessing the Initial Ramdisk (initrd) Environment 1. SSH into the initrd environment using the `initrd_rsa_key` and provided port: diff --git a/docs/site/guides/flake-parts.md b/docs/site/guides/flake-parts.md index c95db284b..6a3c8bf04 100644 --- a/docs/site/guides/flake-parts.md +++ b/docs/site/guides/flake-parts.md @@ -3,7 +3,7 @@ Clan supports integration with [flake-parts](https://flake.parts/), a framework To construct your Clan using flake-parts, follow these steps: -## 1. Update Your Flake Inputs +## 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 `clan-core` and `nixpkgs`. Here's how you can update your `flake.nix` file: @@ -25,7 +25,7 @@ inputs = { } ``` -## 2. Import the Clan flake-parts Module +## Import the Clan flake-parts Module After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../reference/nix-api/clan.md) available within `mkFlake`. @@ -43,7 +43,7 @@ After updating your flake inputs, the next step is to import the Clan flake-part } ``` -### 3. Configure Clan Settings and Define Machines +## Configure Clan Settings and Define Machines Next you'll need to configure Clan wide settings and define machines, here's an example of how `flake.nix` should look: @@ -91,6 +91,6 @@ Next you'll need to configure Clan wide settings and define machines, here's an ``` 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). +refer to the [Clan module](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) documentation. --- diff --git a/docs/site/guides/getting-started/deploy.md b/docs/site/guides/getting-started/deploy.md index 5101044b1..6d26bff4f 100644 --- a/docs/site/guides/getting-started/deploy.md +++ b/docs/site/guides/getting-started/deploy.md @@ -27,7 +27,7 @@ Now that you have created a new machine, we will walk through how to install it. !!! 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) -### Step 1. Setting `targetHost` +## Setting `targetHost` === "flake.nix (flake-parts)" @@ -98,7 +98,7 @@ Now that you have created a new machine, we will walk through how to install it. 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. -### Step 2. Identify the Target Disk +## Identify the Target Disk On the setup computer, SSH into the target: @@ -129,7 +129,7 @@ In this example we would copy `nvme-eui.e8238fa6bf530001001b448b4aec2929` !!! 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). -### Step 3. Fill in hardware specific machine configuration +## Fill in hardware specific machine configuration Edit the following fields inside the `./machines//configuration.nix` @@ -164,7 +164,7 @@ Edit the following fields inside the `./machines//configuration.ni !!! 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`" -### Step 4. Deploy the machine +## Deploy the machine **Finally deployment time!** Use the following command to build and deploy the image via SSH onto your machine. @@ -227,7 +227,7 @@ Edit the following fields inside the `./machines//configuration.ni ``` 2. The root password for the installer medium. This password is autogenerated and meant to be easily typeable. - 3. See how to connect the installer medium to wlan [here](./installer.md#optional-connect-to-wifi-manually). + 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 @@ -236,21 +236,21 @@ Edit the following fields inside the `./machines//configuration.ni Just run the command **Option B: Cloud VM** below -#### Deployment Commands +### Deployment Commands -##### Using password auth +#### Using password auth ```bash clan machines install [MACHINE] --target-host --update-hardware-config nixos-facter ``` -##### Using QR JSON +#### Using QR JSON ```bash clan machines install [MACHINE] --json "[JSON]" --update-hardware-config nixos-facter ``` -##### Using QR image file +#### Using QR image file ```bash clan machines install [MACHINE] --png [PATH] --update-hardware-config nixos-facter diff --git a/docs/site/guides/getting-started/index.md b/docs/site/guides/getting-started/index.md index 3070ca7e2..c13f9ad3d 100644 --- a/docs/site/guides/getting-started/index.md +++ b/docs/site/guides/getting-started/index.md @@ -4,8 +4,7 @@ Ready to create your own Clan and manage a fleet of machines? Follow these simpl By the end of this guide, you'll have a fresh NixOS configuration ready to push to one or more machines. You'll create a new Git repository and a flake, and all you need is at least one machine to push to. This is the easiest way to begin, and we recommend you to copy your existing configuration into this new setup! - -### Prerequisites +## Prerequisites === "**Linux**" @@ -37,22 +36,23 @@ By the end of this guide, you'll have a fresh NixOS configuration ready to push If you have previously installed Nix, make sure `experimental-features = nix-command flakes` is present in `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`. If this is not the case, please add it to `~/.config/nix/nix.conf`. -### Step 1: Add Clan CLI to Your Shell +## Add Clan CLI to Your Shell -Add the Clan CLI into your development workflow: +Add the Clan CLI into your environment: ```bash nix shell git+https://git.clan.lol/clan/clan-core#clan-cli --refresh ``` -You can find reference documentation for the `clan` CLI program [here](../../reference/cli/index.md). - -Alternatively you can check out the help pages directly: ```terminalSession clan --help ``` -### Step 2: Initialize Your Project +Should print the avilable commands. + +Also checkout the [cli-reference documentation](../../reference/cli/index.md). + +## Initialize Your Project If you want to migrate an existing project, follow this [guide](../migrations/migration-guide.md). @@ -62,19 +62,18 @@ Set the foundation of your Clan project by initializing it by running: clan flakes create my-clan ``` -This command creates the `flake.nix` and `.clan-flake` files for your project. -It will also generate files from a default template, to help show general clan usage patterns. +This command creates a `flake.nix` and some other files for your project. -### Step 3: Verify the Project Structure +## Verify the Project Structure -Ensure that all project files exist by running: +Take a lookg at all project files: ```bash cd my-clan tree ``` -This should yield the following: +Depending on the current template you should see something like this: ``` { .console .no-copy } . @@ -109,7 +108,6 @@ This should yield the following: 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/). - ```bash clan machines list ``` @@ -122,4 +120,3 @@ sara !!! success You just successfully bootstrapped your first Clan. - diff --git a/docs/site/guides/getting-started/installer.md b/docs/site/guides/getting-started/installer.md index ada969dc7..485e750f7 100644 --- a/docs/site/guides/getting-started/installer.md +++ b/docs/site/guides/getting-started/installer.md @@ -11,13 +11,12 @@ To install Clan on physical machines, you need to use our custom installer image ??? info "Reasons for a Custom Install Image" Our custom install images are built to include essential tools like [nixos-facter](https://github.com/nix-community/nixos-facter) and support for [ZFS](https://wiki.archlinux.org/title/ZFS). They're also optimized to run on systems with as little as 1 GB of RAM, ensuring efficient performance even on lower-end hardware. - -### Step 0. Prerequisites +## 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 +## Identify the USB Flash Drive 1. Insert your USB flash drive into your computer. @@ -45,7 +44,7 @@ To install Clan on physical machines, you need to use our custom installer image sudo umount /dev/sdb1 ``` -### Step 2. Installer +## Installer === "**Linux OS**" **Create a Custom Installer** @@ -118,7 +117,7 @@ sudo umount /dev/sdb1 !!! Note If you don't have `wget` installed, you can use `curl --progress-bar -OL ` instead. - ### Step 2.5 Flash the Installer to the USB Drive + ## Flash the Installer to the USB Drive !!! Danger "Specifying the wrong device can lead to unrecoverable data loss." @@ -151,11 +150,10 @@ sudo umount /dev/sdb1 If you need to configure Wi-Fi first, refer to the next section. If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the `nixos-installer.local` address. +## Boot From USB Stick -### Step 3: Boot From USB Stick - To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../../guides/secure-boot.md) - ## (Optional) Connect to Wifi Manually If you don't have access via LAN the Installer offers support for connecting via Wifi. @@ -203,4 +201,3 @@ Press ++ctrl+d++ to exit `IWD`. Press ++ctrl+d++ **again** to update the displayed QR code and connection information. You're all set up - diff --git a/docs/site/guides/inventory.md b/docs/site/guides/inventory.md index d829812ee..878a6cf57 100644 --- a/docs/site/guides/inventory.md +++ b/docs/site/guides/inventory.md @@ -121,16 +121,3 @@ It is possible to add services to multiple machines via tags as shown }; } ``` - -### API specification - -**The complete schema specification is available [here](../reference/nix-api/inventory.md)** - -Or it can build anytime via: - -```sh -nix build git+https://git.clan.lol/clan/clan-core#schemas.inventory -> result -> ├── schema.cue -> └── schema.json -``` diff --git a/docs/site/guides/macos.md b/docs/site/guides/macos.md index 6ef9ee1a3..0eccbca58 100644 --- a/docs/site/guides/macos.md +++ b/docs/site/guides/macos.md @@ -9,7 +9,7 @@ Currently, Clan supports the following features for macOS: - `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations - Support for [vars](../guides/vars-backend.md) -## Step 1: Add Your Machine to Your Clan Flake +## Add Your Machine to Your Clan Flake In this example, we'll name the machine `yourmachine`. Replace this with your preferred machine name. @@ -35,7 +35,7 @@ clan-core.lib.clan { } ``` -## Step 2: Add a `configuration.nix` for Your Machine +## Add a `configuration.nix` for Your Machine Create the file `./machines/yourmachine/configuration.nix` with the following content (replace `yourmachine` with your chosen machine name): @@ -48,7 +48,7 @@ Create the file `./machines/yourmachine/configuration.nix` with the following co After creating the file, run `git add` to ensure Nix recognizes it. -## Step 3: Generate Vars (If Needed) +## Generate Vars (If Needed) If your machine uses vars, generate them with: @@ -58,12 +58,12 @@ clan vars generate yourmachine Replace `yourmachine` with your chosen machine name. -## Step 4: Install Nix +## Install Nix Install Nix on your macOS machine using one of the methods described in the [nix-darwin prerequisites](https://github.com/nix-darwin/nix-darwin?tab=readme-ov-file#prerequisites). -## Step 5: Install nix-darwin +## Install nix-darwin Upload your Clan flake to the macOS machine. Then, from within your flake directory, run: @@ -73,7 +73,7 @@ sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#yourmachine Replace `yourmachine` with your chosen machine name. -## Step 6: Manage Your Machine with Clan +## Manage Your Machine with Clan Once all the steps above are complete, you can start managing your machine with: diff --git a/docs/site/guides/migrations/migrate-inventory-services.md b/docs/site/guides/migrations/migrate-inventory-services.md index f7100dbb8..f814bb710 100644 --- a/docs/site/guides/migrations/migrate-inventory-services.md +++ b/docs/site/guides/migrations/migrate-inventory-services.md @@ -74,9 +74,7 @@ instances = { ## Steps to Migrate - - -### 1. Move `services` entries to `instances` +### Move `services` entries to `instances` Check if a service that you use has been migrated [In our reference](../../reference/clanServices/index.md) @@ -96,7 +94,7 @@ Each nested service-instance-pair becomes a flat key, like `borgbackup.simple --- -### 2. Add `module.name` and `module.input` +### Add `module.name` and `module.input` Each instance must declare the module name and flake input it comes from: @@ -117,7 +115,7 @@ Then refer to it as `input = "clan-core"`. --- -### 3. Move role and machine config under `roles` +### Move role and machine config under `roles` In the new system: diff --git a/docs/site/guides/secure-boot.md b/docs/site/guides/secure-boot.md index 3fe5cabd5..51d39c633 100644 --- a/docs/site/guides/secure-boot.md +++ b/docs/site/guides/secure-boot.md @@ -1,9 +1,11 @@ At the moment, NixOS/Clan does not support [Secure Boot](https://wiki.gentoo.org/wiki/Secure_Boot). Therefore, you need to disable it in the BIOS. You can watch this [video guide](https://www.youtube.com/watch?v=BKVShiMUePc) or follow the instructions below: -### Step 1: Insert the USB Stick +## Insert the USB Stick + - Begin by inserting the USB stick into a USB port on your computer. -### Step 2: Access the UEFI/BIOS Menu +## Access the UEFI/BIOS Menu + - Restart your computer. - As your computer restarts, press the appropriate key to enter the UEFI/BIOS settings. ??? tip "The key depends on your laptop or motherboard manufacturer. Click to see a reference list:" @@ -32,18 +34,22 @@ At the moment, NixOS/Clan does not support [Secure Boot](https://wiki.gentoo.org !!! Note Pressing the key quickly and repeatedly is sometimes necessary to access the UEFI/BIOS menu, as the window to enter this mode is brief. -### Step 3: Access Advanced Mode (Optional) +## Access Advanced Mode (Optional) + - If your UEFI/BIOS has a `Simple` or `Easy` mode interface, look for an option labeled `Advanced Mode` (often found in the lower right corner). - Click on `Advanced Mode` to access more settings. This step is optional, as your boot settings might be available in the basic view. -### Step 4: Disable Secure Boot +## Disable Secure Boot + - Locate the `Secure Boot` option in your UEFI/BIOS settings. This is typically found under a `Security` tab, `Boot` tab, or a similarly named section. - Set the `Secure Boot` option to `Disabled`. -### Step 5: Change Boot Order +## Change Boot Order + - Find the option to adjust the boot order—often labeled `Boot Order`, `Boot Sequence`, or `Boot Priority`. - Ensure that your USB device is set as the first boot option. This allows your computer to boot from the USB stick. -### Step 6: Save and Exit +## Save and Exit + - Save your changes before exiting the UEFI/BIOS menu. Look for a `Save & Exit` option or press the corresponding function key (often `F10`). - Your computer should now restart and boot from the USB stick.