docs: Fix multiple issues with the clan installation guide
This commit is contained in:
Qubasa
@@ -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
|
||||
|
||||
27
docs/site/getting-started/check.md
Normal file
27
docs/site/getting-started/check.md
Normal 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.
|
||||
|
||||
@@ -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/<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 = [
|
||||
./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@<new-hostname>
|
||||
# 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 <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
|
||||
# ssh root@<IP> 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:
|
||||
|
||||
```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. `<IP>`
|
||||
|
||||
!!! Example
|
||||
```bash
|
||||
clan machines update-hardware-config jon
|
||||
```
|
||||
$ clan machines create <machinename>
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
@@ -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 <IP>
|
||||
clan machines install [MACHINE] --target-host <IP> --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 `<target_host>` with the **target computers' ip address**:
|
||||
|
||||
```bash
|
||||
clan machines install [MACHINE] --target-host <target_host>
|
||||
clan machines install [MACHINE] --target-host <target_host> --update-hardware-config nixos-facter
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -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 <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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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".
|
||||
''
|
||||
@@ -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".
|
||||
''
|
||||
@@ -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".
|
||||
''
|
||||
@@ -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".
|
||||
''
|
||||
Reference in New Issue
Block a user