clan
/
clan-core
11
1
Fork 6
Code Issues 91 Pull Requests 10 Actions Packages Projects 1 Releases Wiki Activity

docs: improve flake-parts configuration
checks / checks (pull_request) Successful in 2m3s Details
checks / checks-impure (pull_request) Successful in 1m47s Details

This commit is contained in:
Johannes Kirschbauer 2024-04-16 12:02:22 +02:00
parent f8b881c41e
commit 581b48b518
Signed by: hsjobeki
SSH Key Fingerprint: SHA256:vX3utDqig7Ph5L0JPv87ZTPb/w7cMzREKVZzzLFg9qU
8 changed files with 169 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/mkdocs.yml
View File

@ -52,6 +52,7 @@ theme:
- navigation.instant
- navigation.tabs
- content.code.copy
- content.tabs.link
icon:
repo: fontawesome/brands/git

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

@ -10,23 +10,49 @@ In the `flake.nix` file:
These icons will be used by our future GUI.
```nix title="clan-core.lib.buildClan"
buildClan {
# Set a unique name
clanName = "Lobsters";
# Optional, a path to an image file
clanIcon = ./path/to/file;
=== "**buildClan**"
machines = {
jon = {
```nix title="clan-core.lib.buildClan"
buildClan {
# Set a unique name
clanName = "Lobsters";
# Optional, a path to an image file
clanIcon = ./path/to/file;
# Should usually point to the directory of flake.nix
directory = ./.;
machines = {
jon = {
# ...
# Optional, a path to an image file
clanCore.machineIcon = ./path/to/file;
};
# ...
# Optional, a path to an image file
clanCore.machineIcon = ./path/to/file;
};
# ...
}
}
}
```
```
=== "**flakeParts**"
!!! info "See [Clan with flake-parts](./flake-parts.md) for help migrating to flake-parts."
```nix title="clan-core.flakeModules.default"
clan = {
# Set a unique name
clanName = "Lobsters";
# Optional, a path to an image file
clanIcon = ./path/to/file;
machines = {
jon = {
# ...
# Optional, a path to an image file
clanCore.machineIcon = ./path/to/file;
};
# ...
}
};
```
## Machine configuration
@ -56,27 +82,55 @@ Adding or configuring a new machine requires two simple steps:
1. Edit the following fields inside the `flake.nix`
```nix title="clan-core.lib.buildClan"
buildClan {
# ...
machines = {
"jon" = {
# ...
# Change this to the correct ip-address or hostname
# The hostname is the machine name by default
clan.networking.targetHost = pkgs.lib.mkDefault "root@<hostname>"
# Change this to the ID-LINK of the desired disk shown by 'lsblk'
clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/__CHANGE_ME__";
}
=== "**buildClan**"
```nix title="clan-core.lib.buildClan"
buildClan {
# ...
machines = {
"jon" = {
# ...
# Change this to the correct ip-address or hostname
# The hostname is the machine name by default
clan.networking.targetHost = pkgs.lib.mkDefault "root@<hostname>"
# Change this to the ID-LINK of the desired disk shown by 'lsblk'
clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/__CHANGE_ME__";
}
# ...
};
};
}
```
=== "**flakeParts**"
```nix title="clan-core.flakeModules.default"
clan = {
# ...
machines = {
"jon" = {
# ...
# Change this to the correct ip-address or hostname
# The hostname is the machine name by default
clan.networking.targetHost = pkgs.lib.mkDefault "root@<hostname>"
# Change this to the ID-LINK of the desired disk shown by 'lsblk'
clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/__CHANGE_ME__";
}
# ...
};
};
};
};
}
```
```
### Step 2. Detect hardware specific drivers
@ -86,7 +140,7 @@ Adding or configuring a new machine requires two simple steps:
ssh root@<target-computer> nixos-generate-config --no-filesystems --show-hardware-config > hardware-configuration.nix
```
1. Move the generated file to `machines/jon/hardware-configuration.nix`.
2. Move the generated file to `machines/jon/hardware-configuration.nix`.
### Initialize the facts

69
docs/site/getting-started/flake-parts.md
View File

@ -35,6 +35,7 @@ After updating your flake inputs, the next step is to import the `clan-core` fla
inputs@{ flake-parts, ... }:
flake-parts.lib.mkFlake { inherit inputs; } (
{
#
imports = [
inputs.clan-core.flakeModules.default
];
@ -49,45 +50,53 @@ Configure your clan settings and define machine configurations.
Below is a guide on how to structure this in your flake.nix:
```nix
outputs =
inputs@{ flake-parts, ... }:
flake-parts.lib.mkFlake { inherit inputs; } (
{
imports = [
inputs.clan-core.flakeModules.default
];
clan = {
## Clan wide settings. (Required)
clanName = "__CHANGE_ME__"; # Ensure to choose a unique name.
directory = self; # Point this to the repository root.
outputs = inputs@{ flake-parts, clan-core, ... }:
flake-parts.lib.mkFlake { inherit inputs; } ({self, pkgs, ...}: {
# We define our own systems below. you can still use this to add system specific outputs to your flake.
# See: https://flake.parts/getting-started
systems = [];
specialArgs = { }; # Add arguments to every nix import in here
machines = {
jons-desktop = {
nixpkgs.hostPlatform = "x86_64-linux";
imports = [
clan-core.clanModules.sshd # Add openssh server for Clan management
./configuration.nix
];
# import clan-core modules
imports = [
clan-core.flakeModules.default
];
# Define your clan
clan = {
# Clan wide settings. (Required)
clanName = ""; # Ensure to choose a unique name.
machines = {
jon = {
imports = [
./machines/jon/configuration.nix
# ... more modules
];
nixpkgs.hostPlatform = "x86_64-linux";
clanCore.machineIcon = null; # Optional, a path to an image file
# Set this for clan commands use ssh i.e. `clan machines update`
clan.networking.targetHost = pkgs.lib.mkDefault "root@jon";
# remote> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/nvme-eui.e8238fa6bf530001001b448b4aec2929";
};
# There needs to be exactly one controller per clan
clan.networking.zerotier.controller.enable = true;
};
};
}
);
};
});
```
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).
### Next Steps
## Whats next?
With your flake created, explore how to add new machines by reviewing the documentation provided [here](machines.md).
- [Configure Machines](configure.md): Customize machine configuration
- [Deploying](machines.md): Deploying a Machine configuration
---
## TODO
* How do I use Clan machines install to setup my current machine?
* I probably need the clan-core sshd module for that?
* We need to tell them that configuration.nix of a machine NEEDS to be under the directory CLAN_ROOT/machines/<machine-name> I think?

61
docs/site/getting-started/installer.md
View File

@ -4,32 +4,34 @@ We offer a dedicated installer to assist remote installations.
In this tutorial we will guide you through building and flashing it to a bootable USB drive.
## Step 0. Prerequisites
## Creating and Using the **Clan Installer**
### Step 0. 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
### Step 1. Identify the USB Flash Drive
1. Insert your USB flash drive into your computer.
1. Identify your flash drive with `lsblk`:
2. Identify your flash drive with `lsblk`:
```bash
$ lsblk
```
```bash
$ lsblk
```
```{.console, .no-copy}
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
sdb 8:0 1 117,2G 0 disk
└─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO
nvme0n1 259:0 0 1,8T 0 disk
├─nvme0n1p1 259:1 0 512M 0 part /boot
└─nvme0n1p2 259:2 0 1,8T 0 part
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store /
```
```{.console, .no-copy}
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
sdb 8:0 1 117,2G 0 disk
└─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO
nvme0n1 259:0 0 1,8T 0 disk
├─nvme0n1p1 259:1 0 512M 0 part /boot
└─nvme0n1p2 259:2 0 1,8T 0 part
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store
```
In this case it is `sdb`.
!!! Info "In this case the USB device is `sdb`"
3. Ensure all partitions on the drive are unmounted. Replace `sdb1` in the command below with your device identifier (like `sdc1`, etc.):
@ -45,14 +47,20 @@ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
### Step 3. Flash the Installer to the USB Drive
!!! Danger "Specifying the wrong device can lead to unrecoverable data loss."
The `dd` utility will erase the disk. Make sure to specify the correct device (`of=...`)
If your USB device is `sdb` use `of=/dev/sdb`
Use the `dd` utility to write the NixOS installer image to your USB drive:
```bash
sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result of=/dev/sd<X>
```
If your USB device is `sdb` use `of=/dev/sdb`.
### Step 4. Boot and Connect to your network
After writing the installer to the USB drive, use it to boot the target machine.
@ -73,8 +81,6 @@ After writing the installer to the USB drive, use it to boot the target machine.
- **Apple**: Option (Alt) Key (Boot Menu for Mac)
- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
**During Boot**
Select `NixOS` to boot into the clan installer.
@ -83,19 +89,19 @@ Select `NixOS` to boot into the clan installer.
For deploying your configuration the machine needs to be connected via LAN (recommended).
For connecting via Wifi, please consult the guide below.
For connecting via Wifi, please consult the [guide below](#optional-connect-to-wifi).
---
### Whats next?
## Whats next?
- [Configure Machines](configure.md): Customise machine configuration
- [Configure Machines](configure.md): Customize machine configuration
- [Deploying](machines.md): Deploying a Machine configuration
- [WiFi](#optional-connect-to-wifi): Guide for connecting to Wifi.
---
### (Optional) Connect to Wifi
## (Optional) Connect to Wifi
If you don't have access via LAN the Installer offers support for connecting via Wifi.
@ -114,7 +120,7 @@ Now run the following command to connect to your Wifi:
```bash
# Identify your network device.
device list
# Replace 'wlan0' with your device name
# Replace 'wlan0' with your wireless device name
# Find your Wifi SSID.
station wlan0 scan
station wlan0 get-networks
@ -137,4 +143,7 @@ IPv4 address 192.168.188.50 (Your new local ip)
Press `ctrl-d` to exit `IWD`.
Press `ctrl-d` **again** to update the displayed QR code and connection information.
!!! Important
Press `ctrl-d` **again** to update the displayed QR code and connection information.
You're all set up

2
flakeModules/clan.nix
View File

@ -4,6 +4,7 @@ clan-core:
lib,
flake-parts-lib,
inputs,
self,
...
}:
let
@ -20,6 +21,7 @@ in
directory = mkOption {
type = types.path;
description = "The directory containing the clan subdirectory";
default = self; # default to the directory of the flake
};
specialArgs = mkOption {
type = types.attrsOf types.raw;

6
templates/new-clan/flake.nix
View File

@ -8,12 +8,14 @@
let
system = "x86_64-linux";
pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
# Usage see: https://docs.clan.lol
clan = clan-core.lib.buildClan {
directory = self;
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
clanIcon = null; # Optional, a path to an image file
# Prerequisite: boot into the installer
# Prerequisite: boot into the installer
# See: https://docs.clan.lol/getting-started/installer
# local> mkdir -p ./machines/machine1
# local> Edit ./machines/machine1/configuration.nix to your liking
machines = {
@ -21,7 +23,6 @@
imports = [
./modules/shared.nix
./machines/jon/configuration.nix
./machines/jon/hardware-configuration.nix
];
nixpkgs.hostPlatform = system;
@ -45,7 +46,6 @@
imports = [
./modules/shared.nix
./machines/sara/configuration.nix
./machines/sara/hardware-configuration.nix
];
nixpkgs.hostPlatform = system;

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

@ -1,5 +1,6 @@
{ ... }:
{
imports = [ ./hardware-configuration.nix ];
users.users.root.openssh.authorizedKeys.keys = [
# IMPORTANT! Add your SSH key here
# e.g. > cat ~/.ssh/id_ed25519.pub

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

@ -1,6 +1,6 @@
{ ... }:
{
imports = [ ./hardware-configuration.nix ];
users.users.root.openssh.authorizedKeys.keys = [
# IMPORTANT! Add your SSH key here
# e.g. > cat ~/.ssh/id_ed25519.pub