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

rework installation template based on received feedback

Browse Source
This commit is contained in:
Jörg Thalheim
2024-07-21 21:16:07 +02:00
parent 927aec0db5
commit d21d296c5c
10 changed files with 193 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -32,9 +32,9 @@ In the `flake.nix` file:
- [x] set a unique `name`.
=== "**buildClan**"
=== "**normal flake template**"
```nix title="clan-core.lib.buildClan"
```nix title="flake.nix" hl_lines="3"
buildClan {
# Set a unique name
meta.name = "Lobsters";
@@ -50,11 +50,11 @@ In the `flake.nix` file:
}
```
=== "**flakeParts**"
=== "**template using flake-parts**"
!!! info "See [Clan with flake-parts](./flake-parts.md) for help migrating to flake-parts."
```nix title="clan-core.flakeModules.default"
```nix title="flake.nix" hl_lines="3"
clan = {
# Set a unique name
meta.name = "Lobsters";
@@ -77,11 +77,11 @@ Adding or configuring a new machine requires two simple steps:
1. Find the remote disk id by executing:
```bash title="setup computer"
ssh root@flash-installer.local lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
```
!!! Note
Replace `flash-installer.local` with the IP address of the machine if you don't have the avahi service running which resolves mDNS local domains.
Replace `<IP>` with the IP address of the machine if you don't have the avahi service running which resolves mDNS local domains.
Which should show something like:
@@ -97,75 +97,43 @@ 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 `flake.nix`
1. Edit the following fields inside the `./machines/jon/configuration.nix` and/or `./machines/sara/configuration.nix`
=== "**buildClan**"
```nix title="clan-core.lib.buildClan" hl_lines="18 23"
buildClan {
# ...
machines = {
"jon" = {
```nix title="./machines/<machine>/configuration.nix" hl_lines="13 18 23 27"
{
imports = [
# ...
./modules/disko.nix
./machines/jon/configuration.nix
./hardware-configuration.nix
# contains your disk format and partitioning configuration.
../../modules/disko.nix
# this file is shared among all machines
../../modules/shared.nix
# enables GNOME desktop (optional)
../../modules/gnome.nix
];
# ...
# Change this to the correct ip-address or hostname
# The hostname is the machine name by default
clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon"
# Put your username here for login
users.users.user.username = "__YOUR_USERNAME__";
# Change this to the ID-LINK of the desired disk shown by 'lsblk'
disko.devices.disk.main = {
device = "/dev/disk/by-id/__CHANGE_ME__";
}
# Set this for clan commands use ssh i.e. `clan machines update`
# 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
disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
# IMPORTANT! Add your SSH key here
# e.g. > cat ~/.ssh/id_ed25519.pub
users.users.root.openssh.authorizedKeys.keys = [
"<YOUR SSH_KEY>"
];
users.users.root.openssh.authorizedKeys.keys = "__YOUR_SSH_KEY__";
# ...
};
};
}
```
=== "**flakeParts**"
```nix title="clan-core.flakeModules.default" hl_lines="18 23"
clan = {
# ...
machines = {
"jon" = {
imports = [
# ...
./modules/disko.nix
./machines/jon/configuration.nix
];
# ...
# Change this to the correct ip-address or hostname
# The hostname is the machine name by default
clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon"
# Change this to the ID-LINK of the desired disk shown by 'lsblk'
disko.devices.disk.main = {
device = "/dev/disk/by-id/__CHANGE_ME__";
}
# e.g. > cat ~/.ssh/id_ed25519.pub
users.users.root.openssh.authorizedKeys.keys = [
"__YOUR_SSH_KEY__"
];
# ...
};
};
};
```
!!! 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 `__YOUR_SSH_KEY__` with your personal key, like `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop`"
@@ -179,22 +147,57 @@ Generate the `hardware-configuration.nix` file for your machine by executing the
clan machines hw-generate [MACHINE_NAME] [HOSTNAME]
```
replace `[MACHINE_NAME]` with the name of the machine i.e. `jon` and `[HOSTNAME]` with the `ip_adress` or `hostname` of the machine within the network. i.e. `flash-installer.local`
replace `[MACHINE_NAME]` with the name of the machine i.e. `jon` and `[HOSTNAME]` with the `ip_adress` or `hostname` of the machine within the network. i.e. `<IP>`
!!! Example
```bash
clan machines hw-generate jon flash-installer.local
clan machines hw-generate jon <IP>
```
This command connects to `flash-installer.local` as `root`, runs `nixos-generate-config` to detect hardware configurations (excluding filesystems), and writes them to `machines/jon/hardware-configuration.nix`.
This command connects to `<IP>` as `root`, runs `nixos-generate-config` to detect hardware configurations (excluding filesystems), and writes them to `machines/jon/hardware-configuration.nix`.
### 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, refer to the [Disko examples](https://github.com/nix-community/disko/tree/master/example).
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
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:
```
git add ./path/to/my/file
```
For renaming jon to your own machine name, you can use the following command:
```
git mv ./machines/jon ./machines/newname
```
If you only want to setup a single machine at this point, you can delete `sara` from flake.nix as well as from the machines directory:
```
git rm ./machines/sara
```
### Step 5: Check Configuration
@@ -206,9 +209,9 @@ nix flake check
This command helps ensure that your system configuration is correct and free from errors.
!!! Note
!!! Tip
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. This practice helps maintain system stability and reduces integration issues.
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
docs/site/getting-started/deploy.md
View File

@@ -112,7 +112,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] flash-installer.local
clan machines install [MACHINE] <IP>
```
2. **Scanning a QR Code for Installation Details**
@@ -150,23 +150,17 @@ Clan CLI enables you to remotely update your machines over SSH. This requires se
### Setting the Target Host
Replace `root@jon` with the actual hostname or IP address of your target machine:
Replace `root@jon` with the actual hostname or IP address of your target machine in the `configuration.nix` of the machine:
```{.nix hl_lines="9" .no-copy}
buildClan {
{
# ...
machines = {
# "jon" will be the hostname of the machine
"jon" = {
# Set this for clan commands use ssh i.e. `clan machines update`
# 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 = pkgs.lib.mkDefault "root@jon";
};
};
clan.core.networking.targetHost = "root@jon";
};
```
!!! warning
The use of `root@` in the target address implies SSH access as the `root` user.
Ensure that the root login is secured and only used when necessary.

2
docs/site/index.md
View File

@@ -84,7 +84,7 @@ This should yield the following:
└── modules
└── shared.nix
5 directories, 6 files
5 directories, 9 files
```
```bash

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

@@ -6,94 +6,24 @@
outputs =
{ self, clan-core, ... }:
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;
meta.name = "__CHANGE_ME__"; # Ensure this is unique among all clans you want to use.
# Distributed services, uncomment to enable.
# inventory = {
# services = {
# # This example configures a BorgBackup service
# # Check: https://docs.clan.lol/reference/clanModules which ones are available in Inventory
# borgbackup.instance_1 = {
# roles.server.machines = [ "jon" ];
# roles.client.machines = [ "sara" ];
# };
# };
# };
# Ensure this is unique among all clans you want to use.
meta.name = "__CHANGE_ME__";
# 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
# local> Edit ./machines/<machine>/configuration.nix to your liking
machines = {
# "jon" will be the hostname of the machine
jon = {
imports = [
./modules/shared.nix
./modules/disko.nix
./machines/jon/configuration.nix
];
nixpkgs.hostPlatform = system;
# Set this for clan commands use ssh i.e. `clan machines update`
# 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 = pkgs.lib.mkDefault "root@jon";
# 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
disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
# IMPORTANT! Add your SSH key here
# e.g. > cat ~/.ssh/id_ed25519.pub
users.users.root.openssh.authorizedKeys.keys = throw ''
Don't forget to add your SSH key here!
users.users.root.openssh.authorizedKeys.keys = [ "<YOUR SSH_KEY>" ]
'';
# Zerotier needs one controller to accept new nodes. Once accepted
# the controller can be offline and routing still works.
clan.core.networking.zerotier.controller.enable = true;
imports = [ ./machines/jon/configuration.nix ];
};
# "sara" will be the hostname of the machine
sara = {
imports = [
./modules/shared.nix
./modules/disko.nix
./machines/sara/configuration.nix
];
nixpkgs.hostPlatform = system;
# Set this for clan commands use ssh i.e. `clan machines update`
# 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 = pkgs.lib.mkDefault "root@sara";
# 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
disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
# IMPORTANT! Add your SSH key here
# e.g. > cat ~/.ssh/id_ed25519.pub
users.users.root.openssh.authorizedKeys.keys = throw ''
Don't forget to add your SSH key here!
users.users.root.openssh.authorizedKeys.keys = [ "<YOUR SSH_KEY>" ]
'';
/*
After jon is deployed, uncomment the following line
This will allow sara to share the VPN overlay network with jon
The networkId is generated by the first deployment of jon
*/
# clan.core.networking.zerotier.networkId = builtins.readFile ../jon/facts/zerotier-network-id;
imports = [ ./machines/sara/configuration.nix ];
};
};
};
@@ -102,8 +32,19 @@
# all machines managed by Clan
inherit (clan) nixosConfigurations clanInternals;
# add the Clan cli tool to the dev shell
devShells.${system}.default = pkgs.mkShell {
# use the "nix develop" command to enter the dev shell
devShells =
clan-core.inputs.nixpkgs.lib.genAttrs
[
"x86_64-linux"
"aarch64-linux"
"aarch64-darwin"
"x86_64-darwin"
]
(system: {
default = clan-core.inputs.nixpkgs.legacyPackages.${system}.mkShell {
packages = [ clan-core.packages.${system}.clan-cli ];
};
});
};
}

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

@@ -1,38 +1,34 @@
{ config, ... }:
let
username = config.networking.hostName;
in
{
imports = [ ./hardware-configuration.nix ];
# Locale service discovery and mDNS
services.avahi.enable = true;
services.xserver.enable = true;
services.xserver.desktopManager.gnome.enable = true;
services.xserver.displayManager.gdm.enable = true;
# Disable the default gnome apps to speed up deployment
services.gnome.core-utilities.enable = false;
# Enable automatic login for the user.
services.displayManager.autoLogin = {
enable = true;
user = username;
};
users.users.${username} = {
initialPassword = username;
isNormalUser = true;
extraGroups = [
"wheel"
"networkmanager"
"video"
"audio"
"input"
"dialout"
"disk"
imports = [
./hardware-configuration.nix
# contains your disk format and partitioning configuration.
../../modules/disko.nix
# this file is shared among all machines
../../modules/shared.nix
# enables GNOME desktop (optional)
../../modules/gnome.nix
];
uid = 1000;
openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
};
# This is your user login name.
users.users.user.name = "<your-username>";
# Set this for clan commands use ssh i.e. `clan machines update`
# 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
disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
# IMPORTANT! Add your SSH key here
# e.g. > cat ~/.ssh/id_ed25519.pub
users.users.root.openssh.authorizedKeys.keys = [''
__YOUR_SSH_KEY__
''];
# Zerotier needs one controller to accept new nodes. Once accepted
# the controller can be offline and routing still works.
clan.core.networking.zerotier.controller.enable = true;
}

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

@@ -1,39 +1,33 @@
{ config, ... }:
let
username = config.networking.hostName;
in
{
imports = [ ./hardware-configuration.nix ];
# Locale service discovery and mDNS
services.avahi.enable = true;
services.xserver.enable = true;
services.xserver.desktopManager.gnome.enable = true;
services.xserver.displayManager.gdm.enable = true;
# Disable the default gnome apps to speed up deployment
services.gnome.core-utilities.enable = false;
# Enable automatic login for the user.
services.displayManager.autoLogin = {
enable = true;
user = username;
};
users.users.${username} = {
initialPassword = username;
isNormalUser = true;
extraGroups = [
"wheel"
"networkmanager"
"video"
"audio"
"input"
"dialout"
"disk"
imports = [
./hardware-configuration.nix
../../modules/disko.nix
../../modules/shared.nix
# enables GNOME desktop (optional)
../../modules/gnome.nix
];
uid = 1000;
openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
};
# Put your username here for login
users.users.user.name = "<your-username>";
# Set this for clan commands use ssh i.e. `clan machines update`
# 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
disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
# IMPORTANT! Add your SSH key here
# e.g. > cat ~/.ssh/id_ed25519.pub
users.users.root.openssh.authorizedKeys.keys = [''
__YOUR_SSH_KEY__
''];
/*
After jon is deployed, uncomment the following line
This will allow sara to share the VPN overlay network with jon
The networkId is generated by the first deployment of jon
*/
# clan.core.networking.zerotier.networkId = builtins.readFile ../jon/facts/zerotier-network-id;
}

5
templates/new-clan/modules/disko.nix
View File

@@ -1,5 +1,7 @@
{ lib, ... }:
{
# TO NOT EDIT THIS FILE AFTER INSTALLATION of a machine
# Otherwise your system might not boot because of missing partitions / filesystems
boot.loader.grub.efiSupport = lib.mkDefault true;
boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
disko.devices = {
@@ -23,6 +25,7 @@
type = "filesystem";
format = "vfat";
mountpoint = "/boot";
mountOptions = [ "nofail" ];
};
};
root = {
@@ -30,6 +33,8 @@
content = {
type = "filesystem";
format = "ext4";
# format = "btrfs";
# format = "bcachefs";
mountpoint = "/";
};
};

5
templates/new-clan/modules/gnome.nix Normal file
View File

@@ -0,0 +1,5 @@
{
services.xserver.enable = true;
services.xserver.desktopManager.gnome.enable = true;
services.xserver.displayManager.gdm.enable = true;
}

23
templates/new-clan/modules/shared.nix
View File

@@ -1,7 +1,28 @@
{ clan-core, ... }:
{ config, clan-core, ... }:
{
imports = [
# Enables the OpenSSH server for remote access
clan-core.clanModules.sshd
# Set a root password
clan-core.clanModules.root-password
clan-core.clanModules.user-password
];
# Locale service discovery and mDNS
services.avahi.enable = true;
# generate a random password for our user below
# can be read using `clan secrets get <machine-name>-user-password` command
clan.user-password.user = "user";
users.users.user = {
isNormalUser = true;
extraGroups = [
"wheel"
"networkmanager"
"video"
"input"
];
uid = 1000;
openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
};
}