yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Fix multiple issues with the clan installation guide

Browse Source
This commit is contained in:
Qubasa
2025-02-18 17:38:37 +07:00
parent f28a38bbb3
commit 125c2df666
9 changed files with 50 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/mkdocs.yml
View File

@@ -48,6 +48,7 @@ nav:
- Add Machines: getting-started/configure.md - Add Machines: getting-started/configure.md
- Secrets & Facts: getting-started/secrets.md - Secrets & Facts: getting-started/secrets.md
- Deploy Machine: getting-started/deploy.md - Deploy Machine: getting-started/deploy.md
- Continuous Integration: getting-started/check.md
- Guides: - Guides:
- Disk Encryption: getting-started/disk-encryption.md - Disk Encryption: getting-started/disk-encryption.md
- Mesh VPN: getting-started/mesh-vpn.md - Mesh VPN: getting-started/mesh-vpn.md

27
docs/site/getting-started/check.md Normal file
View File

@@ -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.

78
docs/site/getting-started/configure.md
View File

@@ -79,9 +79,14 @@ Adding or configuring a new machine requires two simple steps:
└─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap 16.8G └─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/<machine>/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`
<!-- Note: Use "jon" instead of "<machine>" as "<" is not supported in title tag -->
```nix title="./machines/jon/configuration.nix" hl_lines="13 18 22 26"
{ {
imports = [ imports = [
./hardware-configuration.nix ./hardware-configuration.nix
@@ -96,14 +101,13 @@ Adding or configuring a new machine requires two simple steps:
# Put your username here for login # Put your username here for login
users.users.user.username = "__YOUR_USERNAME__"; 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@<new-hostname> # If you change the hostname, you need to update this line to root@<new-hostname>
# This only works however if you have avahi running on your admin machine else use IP # This only works however if you have avahi running on your admin machine else use IP
clan.core.networking.targetHost = "root@__IP__"; clan.core.networking.targetHost = "root@__IP__";
# You can get your disk id by running the following command on the installer:
# Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command. # Replace this __CHANGE_ME__ with the result of the lsblk command from step 1.
# ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__"; disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
# IMPORTANT! Add your SSH key here # 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 `__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 `__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`" !!! 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 <machinename>
```
```bash ### Step 2: Custom Disk Formatting
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. `<IP>`
!!! 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
In `./modules/disko.nix`, a simple `ext4` disk partitioning scheme is defined for the Disko module. For more complex disk partitioning setups, 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). 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: If you wish to name your machine to something else, do the following steps:
``` ```
mv ./machines/jon/configuration.nix ./machines/newname/configuration.nix 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. Note that our clan lives inside a git repository.
Only files that have been added with `git add` are recognized by `nix`. 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: So for every file that you add or rename you also need to run:

8
docs/site/getting-started/deploy.md
View File

@@ -111,7 +111,7 @@ This process involves preparing a suitable hardware and disk partitioning config
1. **SSH with Password Authentication** 1. **SSH with Password Authentication**
Run the following command to install using SSH: Run the following command to install using SSH:
```bash ```bash
clan machines install [MACHINE] --target-host <IP> clan machines install [MACHINE] --target-host <IP> --update-hardware-config nixos-facter
``` ```
2. **Scanning a QR Code for Installation Details** 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:** - **Using a JSON String or File Path:**
Provide the path to a JSON string or input the string directly: Provide the path to a JSON string or input the string directly:
```terminal ```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:** - **Using an Image Containing the QR Code:**
Provide the path to an image file containing the relevant QR code: Provide the path to an image file containing the relevant QR code:
```terminal ```terminal
clan machines install [MACHINE] --png [PATH] clan machines install [MACHINE] --png [PATH] --update-hardware-config nixos-facter
``` ```
=== "**SSH access**" === "**SSH access**"
@@ -132,7 +132,7 @@ This process involves preparing a suitable hardware and disk partitioning config
Replace `<target_host>` with the **target computers' ip address**: Replace `<target_host>` with the **target computers' ip address**:
```bash ```bash
clan machines install [MACHINE] --target-host <target_host> clan machines install [MACHINE] --target-host <target_host> --update-hardware-config nixos-facter
``` ```

32
docs/site/getting-started/secrets.md
View File

@@ -39,7 +39,7 @@ Also add your age public key to the repository with 'clan secrets users add YOUR
### Add Your Public Key ### Add Your Public Key
```bash ```bash
clan secrets users add $USER <your_public_key> clan secrets users add $USER --age-key <your_public_key>
``` ```
It's best to choose the same username as on your Setup/Admin Machine that you use to control the deployment with. 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 └── key.json
``` ```
If you followed the quickstart tutorial all necessary secrets are initialized at this point. 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.

14
templates/clan/flake-parts/machines/jon/hardware-configuration.nix
View File

@@ -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 <machine_name> <hostname>'
OR:
'ssh root@<hostname> nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix'
And manually replace this file with the generated "hardware-configuration.nix".
''

10
templates/clan/flake-parts/machines/sara/hardware-configuration.nix
View File

@@ -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@<hostname> nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix'
Then replace this file with the generated "hardware-configuration.nix".
''

14
templates/clan/new-clan/machines/jon/hardware-configuration.nix
View File

@@ -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 <machine_name> <hostname>'
OR:
'ssh root@<hostname> nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix'
And manually replace this file with the generated "hardware-configuration.nix".
''

10
templates/clan/new-clan/machines/sara/hardware-configuration.nix
View File

@@ -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@<hostname> nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix'
Then replace this file with the generated "hardware-configuration.nix".
''