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.instant
|
||||||
- navigation.tabs
|
- navigation.tabs
|
||||||
- content.code.copy
|
- content.code.copy
|
||||||
|
- content.tabs.link
|
||||||
icon:
|
icon:
|
||||||
repo: fontawesome/brands/git
|
repo: fontawesome/brands/git
|
||||||
|
|
||||||
|
@ -10,23 +10,49 @@ In the `flake.nix` file:
|
|||||||
|
|
||||||
These icons will be used by our future GUI.
|
These icons will be used by our future GUI.
|
||||||
|
|
||||||
```nix title="clan-core.lib.buildClan"
|
=== "**buildClan**"
|
||||||
buildClan {
|
|
||||||
# Set a unique name
|
|
||||||
clanName = "Lobsters";
|
|
||||||
# Optional, a path to an image file
|
|
||||||
clanIcon = ./path/to/file;
|
|
||||||
|
|
||||||
machines = {
|
```nix title="clan-core.lib.buildClan"
|
||||||
jon = {
|
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
|
## 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`
|
1. Edit the following fields inside the `flake.nix`
|
||||||
|
|
||||||
```nix title="clan-core.lib.buildClan"
|
=== "**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__";
|
|
||||||
}
|
|
||||||
|
|
||||||
|
```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
|
### 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
|
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
|
### 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, ... }:
|
inputs@{ flake-parts, ... }:
|
||||||
flake-parts.lib.mkFlake { inherit inputs; } (
|
flake-parts.lib.mkFlake { inherit inputs; } (
|
||||||
{
|
{
|
||||||
|
#
|
||||||
imports = [
|
imports = [
|
||||||
inputs.clan-core.flakeModules.default
|
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:
|
Below is a guide on how to structure this in your flake.nix:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
outputs =
|
outputs = inputs@{ flake-parts, clan-core, ... }:
|
||||||
inputs@{ flake-parts, ... }:
|
flake-parts.lib.mkFlake { inherit inputs; } ({self, pkgs, ...}: {
|
||||||
flake-parts.lib.mkFlake { inherit inputs; } (
|
# 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
|
||||||
imports = [
|
systems = [];
|
||||||
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.
|
|
||||||
|
|
||||||
specialArgs = { }; # Add arguments to every nix import in here
|
# import clan-core modules
|
||||||
|
imports = [
|
||||||
machines = {
|
clan-core.flakeModules.default
|
||||||
jons-desktop = {
|
];
|
||||||
nixpkgs.hostPlatform = "x86_64-linux";
|
# Define your clan
|
||||||
imports = [
|
clan = {
|
||||||
clan-core.clanModules.sshd # Add openssh server for Clan management
|
# Clan wide settings. (Required)
|
||||||
./configuration.nix
|
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,
|
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).
|
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.
|
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] A free USB Drive with at least 1.5GB (All data on it will be lost)
|
||||||
- [x] Linux/NixOS Machine with Internet
|
- [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. Insert your USB flash drive into your computer.
|
||||||
|
|
||||||
1. Identify your flash drive with `lsblk`:
|
2. Identify your flash drive with `lsblk`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ lsblk
|
$ lsblk
|
||||||
```
|
```
|
||||||
|
|
||||||
```{.console, .no-copy}
|
```{.console, .no-copy}
|
||||||
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
|
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
|
||||||
sdb 8:0 1 117,2G 0 disk
|
sdb 8:0 1 117,2G 0 disk
|
||||||
└─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO
|
└─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO
|
||||||
nvme0n1 259:0 0 1,8T 0 disk
|
nvme0n1 259:0 0 1,8T 0 disk
|
||||||
├─nvme0n1p1 259:1 0 512M 0 part /boot
|
├─nvme0n1p1 259:1 0 512M 0 part /boot
|
||||||
└─nvme0n1p2 259:2 0 1,8T 0 part
|
└─nvme0n1p2 259:2 0 1,8T 0 part
|
||||||
└─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store /
|
└─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.):
|
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
|
### 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:
|
Use the `dd` utility to write the NixOS installer image to your USB drive:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result of=/dev/sd<X>
|
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
|
### Step 4. Boot and Connect to your network
|
||||||
|
|
||||||
After writing the installer to the USB drive, use it to boot the target machine.
|
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)
|
- **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.
|
- If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
**During Boot**
|
**During Boot**
|
||||||
|
|
||||||
Select `NixOS` to boot into the clan installer.
|
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 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
|
- [Deploying](machines.md): Deploying a Machine configuration
|
||||||
- [WiFi](#optional-connect-to-wifi): Guide for connecting to Wifi.
|
- [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.
|
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
|
```bash
|
||||||
# Identify your network device.
|
# Identify your network device.
|
||||||
device list
|
device list
|
||||||
# Replace 'wlan0' with your device name
|
# Replace 'wlan0' with your wireless device name
|
||||||
# Find your Wifi SSID.
|
# Find your Wifi SSID.
|
||||||
station wlan0 scan
|
station wlan0 scan
|
||||||
station wlan0 get-networks
|
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` 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,
|
lib,
|
||||||
flake-parts-lib,
|
flake-parts-lib,
|
||||||
inputs,
|
inputs,
|
||||||
|
self,
|
||||||
...
|
...
|
||||||
}:
|
}:
|
||||||
let
|
let
|
||||||
@ -20,6 +21,7 @@ in
|
|||||||
directory = mkOption {
|
directory = mkOption {
|
||||||
type = types.path;
|
type = types.path;
|
||||||
description = "The directory containing the clan subdirectory";
|
description = "The directory containing the clan subdirectory";
|
||||||
|
default = self; # default to the directory of the flake
|
||||||
};
|
};
|
||||||
specialArgs = mkOption {
|
specialArgs = mkOption {
|
||||||
type = types.attrsOf types.raw;
|
type = types.attrsOf types.raw;
|
||||||
|
@ -8,12 +8,14 @@
|
|||||||
let
|
let
|
||||||
system = "x86_64-linux";
|
system = "x86_64-linux";
|
||||||
pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
|
pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
|
||||||
|
# Usage see: https://docs.clan.lol
|
||||||
clan = clan-core.lib.buildClan {
|
clan = clan-core.lib.buildClan {
|
||||||
directory = self;
|
directory = self;
|
||||||
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
|
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
|
||||||
clanIcon = null; # Optional, a path to an image file
|
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> mkdir -p ./machines/machine1
|
||||||
# local> Edit ./machines/machine1/configuration.nix to your liking
|
# local> Edit ./machines/machine1/configuration.nix to your liking
|
||||||
machines = {
|
machines = {
|
||||||
@ -21,7 +23,6 @@
|
|||||||
imports = [
|
imports = [
|
||||||
./modules/shared.nix
|
./modules/shared.nix
|
||||||
./machines/jon/configuration.nix
|
./machines/jon/configuration.nix
|
||||||
./machines/jon/hardware-configuration.nix
|
|
||||||
];
|
];
|
||||||
|
|
||||||
nixpkgs.hostPlatform = system;
|
nixpkgs.hostPlatform = system;
|
||||||
@ -45,7 +46,6 @@
|
|||||||
imports = [
|
imports = [
|
||||||
./modules/shared.nix
|
./modules/shared.nix
|
||||||
./machines/sara/configuration.nix
|
./machines/sara/configuration.nix
|
||||||
./machines/sara/hardware-configuration.nix
|
|
||||||
];
|
];
|
||||||
|
|
||||||
nixpkgs.hostPlatform = system;
|
nixpkgs.hostPlatform = system;
|
||||||
|
@ -1,5 +1,6 @@
|
|||||||
{ ... }:
|
{ ... }:
|
||||||
{
|
{
|
||||||
|
imports = [ ./hardware-configuration.nix ];
|
||||||
users.users.root.openssh.authorizedKeys.keys = [
|
users.users.root.openssh.authorizedKeys.keys = [
|
||||||
# IMPORTANT! Add your SSH key here
|
# IMPORTANT! Add your SSH key here
|
||||||
# e.g. > cat ~/.ssh/id_ed25519.pub
|
# e.g. > cat ~/.ssh/id_ed25519.pub
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
{ ... }:
|
{ ... }:
|
||||||
{
|
{
|
||||||
|
imports = [ ./hardware-configuration.nix ];
|
||||||
users.users.root.openssh.authorizedKeys.keys = [
|
users.users.root.openssh.authorizedKeys.keys = [
|
||||||
# IMPORTANT! Add your SSH key here
|
# IMPORTANT! Add your SSH key here
|
||||||
# e.g. > cat ~/.ssh/id_ed25519.pub
|
# e.g. > cat ~/.ssh/id_ed25519.pub
|
||||||
|
Loading…
Reference in New Issue
Block a user