forked from clan/clan-core
docs: improve flake-parts configuration
This commit is contained in:
parent
f8b881c41e
commit
581b48b518
@ -52,6 +52,7 @@ theme:
|
||||
- navigation.instant
|
||||
- navigation.tabs
|
||||
- content.code.copy
|
||||
- content.tabs.link
|
||||
icon:
|
||||
repo: fontawesome/brands/git
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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?
|
||||
|
@ -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
|
||||
|
@ -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;
|
||||
|
@ -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,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
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user