diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index eea466904..f99cba943 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -48,6 +48,7 @@ nav: - Add Machines: getting-started/configure.md - Secrets & Facts: getting-started/secrets.md - Deploy Machine: getting-started/deploy.md + - Continuous Integration: getting-started/check.md - Guides: - Disk Encryption: getting-started/disk-encryption.md - Mesh VPN: getting-started/mesh-vpn.md diff --git a/docs/site/getting-started/check.md b/docs/site/getting-started/check.md new file mode 100644 index 000000000..18e2debcd --- /dev/null +++ b/docs/site/getting-started/check.md @@ -0,0 +1,27 @@ +### Generate Facts and Vars + +Typically, this step is handled automatically when a machine is deployed. However, to enable the use of `nix flake check` with your configuration, it must be completed manually beforehand. + +Currently, generating all the necessary facts requires two separate commands. This is due to the coexistence of two parallel secret management solutions: the older, stable version (`clan secrets` and `clan facts`) and the newer, experimental version (`clan vars`). + +To generate both facts and vars, execute the following commands: + +```sh +clan facts generate && clan vars generate +``` + + +### Check Configuration + +Validate your configuration by running: + +```bash +nix flake check +``` + +This command helps ensure that your system configuration is correct and free from errors. + +!!! Tip + + You can integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase. + diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index 76d716775..177cd194f 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -79,9 +79,14 @@ Adding or configuring a new machine requires two simple steps: └─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap 16.8G ``` -1. Edit the following fields inside the `./machines/jon/configuration.nix` and/or `./machines/sara/configuration.nix` + !!! Warning + Make sure to copy the `ID-LINK` from toplevel disk device like `nvme0n1` or `sda` instead of `nvme0n1p1` or `sda1` - ```nix title="./machines//configuration.nix" hl_lines="13 18 23 27" + +2. Edit the following fields inside the `./machines/jon/configuration.nix` and/or `./machines/sara/configuration.nix` + + + ```nix title="./machines/jon/configuration.nix" hl_lines="13 18 22 26" { imports = [ ./hardware-configuration.nix @@ -96,14 +101,13 @@ Adding or configuring a new machine requires two simple steps: # Put your username here for login users.users.user.username = "__YOUR_USERNAME__"; - # Set this for clan commands use ssh i.e. `clan machines update` + # Set this for clan commands that use ssh # If you change the hostname, you need to update this line to root@ # This only works however if you have avahi running on your admin machine else use IP clan.core.networking.targetHost = "root@__IP__"; - # You can get your disk id by running the following command on the installer: - # Replace with the IP of the installer printed on the screen or by running the `ip addr` command. - # ssh root@ lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT + + # Replace this __CHANGE_ME__ with the result of the lsblk command from step 1. disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__"; # IMPORTANT! Add your SSH key here @@ -114,80 +118,32 @@ Adding or configuring a new machine requires two simple steps: } ``` - You can also create additional machines using the `clan machines create` command: - - ``` - $ clan machines create --help - usage: clan [-h] [SUBCOMMAND] machines create [-h] [--tags TAGS [TAGS ...]] [--template-name TEMPLATE_NAME] - [--target-host TARGET_HOST] [--debug] [--option name value] [--flake PATH] - machine_name - - positional arguments: - machine_name The name of the machine to create - - options: - -h, --help show this help message and exit - --tags TAGS [TAGS ...] - Tags to associate with the machine. Can be used to assign multiple machines to services. - --template-name TEMPLATE_NAME - The name of the template machine to import - --target-host TARGET_HOST - Address of the machine to install and update, in the format of user@host:1234 - --debug Enable debug logging - --option name value Nix option to set - --flake PATH path to the flake where the clan resides in, can be a remote flake or local, can be set through - the [CLAN_DIR] environment variable - ``` - !!! Info "Replace `__YOUR_USERNAME__` with the ip of your machine, if you use avahi you can also use your hostname" !!! Info "Replace `__IP__` with the ip of your machine, if you use avahi you can also use your hostname" -!!! Info "Replace `__CHANGE_ME__` with the appropriate identifier, such as `nvme-eui.e8238fa6bf530001001b448b4aec2929`" +!!! Info "Replace `__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`" -These steps will allow you to update your machine later. -### Step 2: Detect Drivers + You can also create additional machines using the cli: -Generate the `hardware-configuration.nix` file for your machine by executing the following command: + ``` + $ clan machines create + ``` -```bash -clan machines update-hardware-config [MACHINE_NAME] [HOSTNAME] -``` - -replace `[MACHINE_NAME]` with the name of the machine i.e. `jon` and `[HOSTNAME]` with the `ip_address` or `hostname` of the machine within the network. i.e. `` - -!!! Example - ```bash - clan machines update-hardware-config jon - ``` - - This command connects to the ip configured in the previous step, runs [nixos-facter](https://github.com/nix-community/nixos-facter) - to detect hardware configurations (excluding filesystems), and writes them to `machines/jon/facter.json`. - -### Step 3: Custom Disk Formatting +### Step 2: Custom Disk Formatting In `./modules/disko.nix`, a simple `ext4` disk partitioning scheme is defined for the Disko module. For more complex disk partitioning setups, refer to the [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example). -### Step 4: Custom Configuration +### Step 3 (Optional): Renaming Machine -Modify `./machines/jon/configuration.nix` to personalize the system settings according to your requirements. If you wish to name your machine to something else, do the following steps: ``` mv ./machines/jon/configuration.nix ./machines/newname/configuration.nix ``` -Than rename `jon` to your preferred name in `machines` in `flake.nix` as well as the import line: - -```diff -- imports = [ ./machines/jon/configuration.nix ]; -+ imports = [ ./machines/__NEW_NAME__/configuration.nix ]; -``` - -!!! Info "Replace `__NEW_NAME__` with the name of the machine" - Note that our clan lives inside a git repository. Only files that have been added with `git add` are recognized by `nix`. So for every file that you add or rename you also need to run: diff --git a/docs/site/getting-started/deploy.md b/docs/site/getting-started/deploy.md index 719ca3ef0..282cfc518 100644 --- a/docs/site/getting-started/deploy.md +++ b/docs/site/getting-started/deploy.md @@ -111,7 +111,7 @@ This process involves preparing a suitable hardware and disk partitioning config 1. **SSH with Password Authentication** Run the following command to install using SSH: ```bash - clan machines install [MACHINE] --target-host + clan machines install [MACHINE] --target-host --update-hardware-config nixos-facter ``` 2. **Scanning a QR Code for Installation Details** @@ -119,12 +119,12 @@ This process involves preparing a suitable hardware and disk partitioning config - **Using a JSON String or File Path:** Provide the path to a JSON string or input the string directly: ```terminal - clan machines install [MACHINE] --json [JSON] + clan machines install [MACHINE] --json [JSON] --update-hardware-config nixos-facter ``` - **Using an Image Containing the QR Code:** Provide the path to an image file containing the relevant QR code: ```terminal - clan machines install [MACHINE] --png [PATH] + clan machines install [MACHINE] --png [PATH] --update-hardware-config nixos-facter ``` === "**SSH access**" @@ -132,7 +132,7 @@ This process involves preparing a suitable hardware and disk partitioning config Replace `` with the **target computers' ip address**: ```bash - clan machines install [MACHINE] --target-host + clan machines install [MACHINE] --target-host --update-hardware-config nixos-facter ``` diff --git a/docs/site/getting-started/secrets.md b/docs/site/getting-started/secrets.md index baf112db7..39d196f4d 100644 --- a/docs/site/getting-started/secrets.md +++ b/docs/site/getting-started/secrets.md @@ -39,7 +39,7 @@ Also add your age public key to the repository with 'clan secrets users add YOUR ### Add Your Public Key ```bash -clan secrets users add $USER +clan secrets users add $USER --age-key ``` It's best to choose the same username as on your Setup/Admin Machine that you use to control the deployment with. @@ -53,33 +53,3 @@ sops/ └── key.json ``` If you followed the quickstart tutorial all necessary secrets are initialized at this point. - - - -### Generate Facts and Vars - -Typically, this step is handled automatically when a machine is deployed. However, to enable the use of `nix flake check` with your configuration, it must be completed manually beforehand. - -Currently, generating all the necessary facts requires two separate commands. This is due to the coexistence of two parallel secret management solutions: the older, stable version (`clan secrets` and `clan facts`) and the newer, experimental version (`clan vars`). - -To generate both facts and vars, execute the following commands: - -```sh -clan facts generate && clan vars generate -``` - - -### Check Configuration - -Validate your configuration by running: - -```bash -nix flake check -``` - -This command helps ensure that your system configuration is correct and free from errors. - -!!! Tip - - You can integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase. - diff --git a/templates/clan/flake-parts/machines/jon/hardware-configuration.nix b/templates/clan/flake-parts/machines/jon/hardware-configuration.nix deleted file mode 100644 index d28460609..000000000 --- a/templates/clan/flake-parts/machines/jon/hardware-configuration.nix +++ /dev/null @@ -1,14 +0,0 @@ -# Replace this file with an actual hardware-configuration.nix! -throw '' - Did you forget to generate your hardware config? - - Run the following command: - - 'clan machines update-hardware-config ' - - OR: - - 'ssh root@ nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix' - - And manually replace this file with the generated "hardware-configuration.nix". -'' diff --git a/templates/clan/flake-parts/machines/sara/hardware-configuration.nix b/templates/clan/flake-parts/machines/sara/hardware-configuration.nix deleted file mode 100644 index e4db1a9f2..000000000 --- a/templates/clan/flake-parts/machines/sara/hardware-configuration.nix +++ /dev/null @@ -1,10 +0,0 @@ -# Replace this file with an actual hardware-configuration.nix! -throw '' - Did you forget to generate your hardware config? - - Run the following command: - - 'ssh root@ nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix' - - Then replace this file with the generated "hardware-configuration.nix". -'' diff --git a/templates/clan/new-clan/machines/jon/hardware-configuration.nix b/templates/clan/new-clan/machines/jon/hardware-configuration.nix deleted file mode 100644 index d28460609..000000000 --- a/templates/clan/new-clan/machines/jon/hardware-configuration.nix +++ /dev/null @@ -1,14 +0,0 @@ -# Replace this file with an actual hardware-configuration.nix! -throw '' - Did you forget to generate your hardware config? - - Run the following command: - - 'clan machines update-hardware-config ' - - OR: - - 'ssh root@ nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix' - - And manually replace this file with the generated "hardware-configuration.nix". -'' diff --git a/templates/clan/new-clan/machines/sara/hardware-configuration.nix b/templates/clan/new-clan/machines/sara/hardware-configuration.nix deleted file mode 100644 index e4db1a9f2..000000000 --- a/templates/clan/new-clan/machines/sara/hardware-configuration.nix +++ /dev/null @@ -1,10 +0,0 @@ -# Replace this file with an actual hardware-configuration.nix! -throw '' - Did you forget to generate your hardware config? - - Run the following command: - - 'ssh root@ nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix' - - Then replace this file with the generated "hardware-configuration.nix". -''