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

Merge pull request 'improve starter template' (#1123) from Qubasa-better-template into main
All checks were successful
checks / check-links (push) Successful in 14s
Details
checks / checks (push) Successful in 38s
Details
checks / checks-impure (push) Successful in 1m48s
Details

Browse Source
This commit is contained in:
clan-bot 2024-04-07 19:12:02 +00:00
commit d89edef9a1
11 changed files with 649 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
docs/admins/install-iso.md Normal file
View File

@ -0,0 +1,125 @@
# Clan Hardware Installation
For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
## Creating a Bootable USB Drive on Linux
To create a bootable USB flash drive with the NixOS installer:
### Build the Installer Image
```bash
nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
```
> Make sure you do this inside
### Prepare the USB Flash Drive
1. Insert your USB flash drive into your computer.
2. Identify your flash drive with `lsblk`.
```shellSession
$ lsblk
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's `sdb`
3. Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
```bash
sudo umount /dev/sdb1
```
### Write the Image to the USB Drive
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/stick.raw of=/dev/sd<X>
```
In case your USB device is `sdb` use `of=/dev/sdb`
### Boot and Connect
After writing the installer to the USB drive, use it to boot the target machine.
1. For this secure boot needs to be disabled. Go into your UEFI / Bios settings by pressing one of the keys outlined below while booting:
- **Dell**: F2/Del (BIOS Setup)
- **HP**: Esc (Startup Menu)
- **Lenovo**: F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
- **Acer**: F2/Del (BIOS Setup)
- **Asus**: F2/Del (BIOS Setup)
- **Toshiba**: Esc then F12 (Alternate Method)
- **Sony**: F11
- **Samsung**: F2 (BIOS Setup)
- **MSI**: Del (BIOS Setup)
- **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.
2. Inside the UEFI/Bios Menu go to `Security->Secure Boot` and disable secure boot
3. Save your settings. Put in the USB stick and reboot.
4. Press one of keys outlined below to go into the Boot Menu
- **Dell**: F12 (Boot Menu)
- **HP**: F9 (Boot Menu)
- **Lenovo**: F12 (ThinkPad Boot Menu)
- **Acer**: F12 (Boot Menu)
- **Asus**: F8/Esc (Boot Menu)
- **Toshiba**: F12/F2 (Boot Menu)
- **Sony**: F11
- **Samsung**: F2/F12/Esc (Boot Menu)
- **MSI**: F11
- **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.
5. Select `NixOS` to boot into the clan installer
6. The installer will display an IP address and a root password, which you can use to connect via SSH.
Alternatively you can also use the displayed QR code.
7. Set your keyboard language. Important for writing passwords correctly.
```bash
loadkeys de
```
8. If you only have Wifi available, execute:
1. Bring up the `iwd` shell
```bash
iwctl
```
2. List available networks. Double press tab after station for autocompleting your wlan device. In this case `wlan0`
```shellSession
[iwd] station wlan0 get-networks
```
3. Connect to a Wifi network. Replace `SSID` with the wlan network name.
```shellSession
[iwd] station wlan0 connect SSID
```
9. Now that you have internet re-execute the init script by pressing `Ctrl+D` or by executing:
```bash
bash
```
10. Connect to the machine over ssh
```bash
ssh-copy-id -o PreferredAuthentications=password root@<ip>
```
Use the root password displayed on your screen as login.

111
docs/admins/machines.md
View File

@ -1,89 +1,18 @@
# Managing NixOS Machines
## Add Your First Machine
To start managing a new machine, use the following commands to create and then list your machines:
```shellSession
$ clan machines create my-machine
$ clan machines list
my-machine
```
## Configure Your Machine
In the example below, we demonstrate how to add a new user named `my-user` and set a password. This user will be configured to log in to the machine `my-machine`.
### Creating a New User
```shellSession
# Add a new user
$ clan config --machine my-machine users.users.my-user.isNormalUser true
# Set a password for the user
$ clan config --machine my-machine users.users.my-user.initialHashedPassword $(mkpasswd)
```
_Note: The `$(mkpasswd)` command generates a hashed password. Ensure you have the `mkpasswd` utility installed or use an alternative method to generate a secure hashed password._
## Test Your Machine Configuration Inside a VM
Before deploying your configuration to a live environment, you can run a virtual machine (VM) to test the settings:
```shellSession
$ clan vms run my-machine
```
This command run a VM based on the configuration of `my-machine`, allowing you to verify changes in a controlled environment.
## Installing a New Machine
# Managing NixOS Machines with Clan
Clan CLI, in conjunction with [nixos-anywhere](https://github.com/nix-community/nixos-anywhere), provides a seamless method for installing NixOS on various machines.
This process involves preparing a suitable hardware and disk partitioning configuration and ensuring the target machine is accessible via SSH.
### Prerequisites
- A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
- For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
## Creating a Bootable USB Drive on Linux
To create a bootable USB flash drive with the NixOS installer:
1. **Build the Installer Image**:
```shellSession
$ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
```
2. **Prepare the USB Flash Drive**:
- Insert your USB flash drive into your computer.
- Identify your flash drive with `lsblk`. Look for the device with a matching size.
- Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
```shellSession
sudo umount /dev/sdX*
```
3. **Write the Image to the USB Drive**:
- Use the `dd` utility to write the NixOS installer image to your USB drive:
```shellSession
sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX
```
4. **Boot and Connect**:
- After writing the installer to the USB drive, use it to boot the target machine.
- The installer will display an IP address and a root password, which you can use to connect via SSH.
- [x] A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
### Finishing the installation
With the target machine running Linux and accessible via SSH, execute the following command to install NixOS on the target machine, replacing `<target_host>` with the machine's hostname or IP address:
```shellSession
$ clan machines install my-machine <target_host>
```bash
clan machines install my-machine <target_host>
```
## Update Your Machines
@ -94,25 +23,25 @@ Clan CLI enables you to remotely update your machines over SSH. This requires se
Replace `host_or_ip` with the actual hostname or IP address of your target machine:
```shellSession
$ clan config --machine my-machine clan.networking.targetHost root@host_or_ip
```bash
clan config --machine my-machine clan.networking.targetHost root@host_or_ip
```
_Note: 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._
> Note: 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.
### Updating Machine Configurations
Execute the following command to update the specified machine:
```shellSession
$ clan machines update my-machine
```bash
clan machines update my-machine
```
You can also update all configured machines simultaneously by omitting the machine name:
```shellSession
$ clan machines update
```bash
clan machines update
```
### Setting a Build Host
@ -121,8 +50,8 @@ If the machine does not have enough resources to run the NixOS evaluation or bui
it is also possible to specify a build host instead.
During an update, the cli will ssh into the build host and run `nixos-rebuild` from there.
```shellSession
$ clan config --machine my-machine clan.networking.buildHost root@host_or_ip
```bash
clan config --machine my-machine clan.networking.buildHost root@host_or_ip
```
### Excluding a machine from `clan machine update`
@ -130,9 +59,15 @@ $ clan config --machine my-machine clan.networking.buildHost root@host_or_ip
To exclude machines from beeing updated when running `clan machines update` without any machines specified,
one can set the `clan.deployment.requireExplicitUpdate` option to true:
```shellSession
$ clan config --machine my-machine clan.deployment.requireExplicitUpdate true
```bash
clan config --machine my-machine clan.deployment.requireExplicitUpdate true
```
This is useful for machines that are not always online or are not part of the regular update cycle.
---
# TODO:
* TODO: How to join others people zerotier
* `services.zerotier.joinNetworks = [ "network-id" ]`
* Controller needs to approve over webinterface or cli

312
docs/admins/migrate.md Normal file
View File

@ -0,0 +1,312 @@
# Migrating Existing NixOS Configuration Flake to Clan Core
Transitioning your existing setup to Clan Core is easy and straightforward. Follow this guide to ensure a smooth migration.
## 0. Prerequisites
### Backup Your Current Configuration
Create a backup of your existing NixOS configuration.
This step ensures you have the option to revert to your original setup if necessary.
```bash
cp -r /etc/nixos ~/nixos-backup
```
## 1. Initialize a flake.nix
If you haven't yet adopted Nix Flakes in your project, follow these steps to initialize a new `flake.nix` file in your project directory.
> Note: Clan is based on flakes, it is possible to use cLan without flakes but not officially supported yet.
### Generate a Trivial flake.nix File
This creates a basic `flake.nix` file that you can later customize for your project.
Create a place for your system configuration if you don't have one already. We'll create `~/clans/empire`.
In this example, we're setting up a directory named `empire` inside a `clans` folder in your home directory. This is just an example, and you can name and place your project directory as it suits your organizational preferences.
```bash
mkdir -p ~/clans/empire && cd ~/clans/empire
nix flake init -t github:NixOS/templates#trivial
```
This will initialize a `flake.nix` file that looks like this:
```nix
# flake.nix
{
description = "A very basic flake";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
};
outputs = { self, nixpkgs }: {
packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
};
}
```
### Initialize a Git Repository (optional/recommended)
If your project isn't already version-controlled with Git, now is a good time to start. This step initializes a new Git repository in your current directory.
```bash
git init && git add .
```
> Note: adding all files to the git index is essential for `nix flakes` as `flakes` ignores source files that are not part of the git index.
Confirm your flake repository is working:
```bash
nix flake show
```
```bash
warning: creating lock file flake.lock'
path: <some/hash>
└───packages
└───x86_64-linux
├───default: package 'hello-2.12.1'
└───hello: package 'hello-2.12.1'
```
## 2. Create your first Machine
Create a directory where you put **all machine specific configs** like the `configuration.nix` or `hardware-configuration.nix`
> Following this structure will allow you nicely organize all your different machines and allows the cLan-CLI to automatically detect and manage your machines.
```bash
mkdir -p machines/jons-desktop
```
> In this case `jons-desktop` is the hostname of the machine you want to manage with cLan.
Move your `configuration.nix` and included files into `machines/jons-desktop`
```bash
mv configuration.nix machines/jons-desktop/configuration.nix
```
Git add all new files/folders
```bash
git add machines
```
### Migrate to flakes and `buildClan`
Add `Clan Core` as a new input to your `flake.nix`:
```nix
# flake.nix
inputs.clan-core = {
url = "git+https://git.clan.lol/clan/clan-core";
inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
}
```
Your flake should now look something like this.
```nix
# flake.nix
{
inputs = {
# Change ref to your liking
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
clan-core = {
url = "git+https://git.clan.lol/clan/clan-core";
inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
};
};
outputs = { self, nixpkgs, clan-core }: {
# ...
};
}
```
> Note: `inputs.nixpkgs.follows` ensures that `clan-core` uses the same `nixpkgs` version as the rest of your flake.
### Use `clan-core.lib.buildClan` for declaring your machines
If you used flakes already you might use `lib.nixosSystem`
```nix
# OLD
# flake.nix
outputs = { self, nixpkgs }: {
nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [ ./configuration.nix ];
};
}
```
We explain how to setup `buildClan`
```nix
# flake.nix
outputs = { self, nixpkgs, clan-core }:
let
clan = clan-core.lib.buildClan {
## 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
machines = {
jons-desktop = {
nixpkgs.hostPlatform = "x86_64-linux";
imports = [
./machines/jons-desktop/configuration.nix
clan-core.clanModules.sshd # Add openssh server forcLanmanagement
];
};
};
};
in
{
inherit (clan) nixosConfigurations clanInternals;
};
```
## Rebuild and Switch
Apply your updated configuration
Before we can rebuild the system we should replace the source of your system ( folder `/etc/nixos`) with a symlink to the `repo`
```bash
sudo ls -s ~/clans/empire /etc/nixos
```
```bash
sudo nixos-rebuild switch
```
This rebuilds your system configuration and switches to it.
> Note: nixos-rebuild switch uses /etc/nixos by default.
## Finish installation
- **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
- **Reboot**: If the build is successful and no issues are detected, reboot your system:
```shellSession
sudo reboot
```
- **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
---
## What's next?
After creating your cLan see [managing machines](./machines.md)
Or continue with **flake-parts integration**
## Integrating Clan with Flakes using `flake-parts``
Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows modular compositions.
Here's how to set up Clan using flakes and flake-parts.
### 1. Update Your Flake Inputs
To begin, you'll need to add `flake-parts` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
```nix
# flake.nix
inputs = {
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
# New flake-parts input
flake-parts.url = "github:hercules-ci/flake-parts";
flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
clan-core = {
url = "git+https://git.clan.lol/clan/clan-core";
inputs.nixpkgs.follows = "nixpkgs"; # Needed if your configuration uses nixpkgs unstable.
# New
inputs.flake-parts.follows = "flake-parts";
};
}
```
### 2. Import Clan-Core Flake Module
After updating your flake inputs, the next step is to import the `clan-core` flake module. This will make the [clan options](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) available within `mkFlake`.
```nix
outputs =
inputs@{ flake-parts, ... }:
flake-parts.lib.mkFlake { inherit inputs; } (
{
imports = [
inputs.clan-core.flakeModules.default
];
}
);
```
### 3. Configure Clan Settings and Define Machines
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.
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
];
};
};
};
}
);
```
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
With your flake created, explore how to add new machines by reviewing the documentation provided [here](./machines.md).
---
## 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?

238
docs/admins/quickstart.md
View File

@ -1,200 +1,76 @@
# Initializing a New Clan Project
# **Quick Start Guide to Initializing a New Clan Project**
## Create a new flake
This guide will lead you through initiating a new Clan project
1. To start a new project, execute the following command to add the clan cli to your shell:
## **Overview**
```shellSession
$ nix shell git+https://git.clan.lol/clan/clan-core
```
Dive into our structured guide tailored to meet your needs:
2. Then use the following commands to initialize a new clan-flake:
```shellSession
$ clan flakes create my-clan
```
This action will generate two primary files: `flake.nix` and `.clan-flake`.
```shellSession
$ ls -la
drwx------ joerg users 5 B a minute ago ./
drwxrwxrwt root root 139 B 12 seconds ago ../
.rw-r--r-- joerg users 77 B a minute ago .clan-flake
.rw-r--r-- joerg users 4.8 KB a minute ago flake.lock
.rw-r--r-- joerg users 242 B a minute ago flake.nix
```
### Understanding the .clan-flake Marker File
The `.clan-flake` marker file serves an optional purpose: it helps the `clan-cli` utility locate the project's root directory.
If `.clan-flake` is missing, `clan-cli` will instead search for other indicators like `.git`, `.hg`, `.svn`, or `flake.nix` to identify the project root.
## What's next
After creating your flake, you can check out how to add [new machines](./machines.md)
- [**Starting with a New Clan Project**](#starting-with-a-new-clan-project): Kickstart your journey with Clan by setting up a new project from the ground up.
- [**Migrating Existing Flake Configuration**](migrate.md#migrating-existing-nixos-configuration-flake): Transition your existing flake-based Nix configuration to harness the power of Clan Core.
- [**Integrating Clan using Flake-Parts**](./migrate.md#integrating-clan-with-flakes-using-flake-parts): Enhance your Clan experience by integrating it with Flake-Parts.
---
# Migrating Existing NixOS Configuration Flake
## **Starting with a New Clan Project**
#### Before You Begin
Embark on your Clan adventure with these initial steps:
1. **Backup Your Current Configuration**: Always start by making a backup of your current NixOS configuration to ensure you can revert if needed.
### **Step 1: Add Clan CLI to Your Shell**
Incorporate the Clan CLI into your development workflow with this simple command:
```shell
nix shell git+https://git.clan.lol/clan/clan-core
```
```shellSession
$ cp -r /etc/nixos ~/nixos-backup
```
### **Step 2: Initialize Your Project**
Set the foundation of your Clan project by initializing it as follows:
```shell
clan flakes create my-clan
```
This command crafts the essential `flake.nix` and `.clan-flake` files for your project.
2. **Update Flake Inputs**: Add a new input for the `clan-core` dependency:
### **Step 3: Verify the Project Structure**
Ensure the creation of your project files with a quick directory listing:
```shell
cd my-clan && ls -la
```
Look for `.clan-flake`, `flake.lock`, and `flake.nix` among your files to confirm successful setup.
```nix
inputs.clan-core = {
url = "git+https://git.clan.lol/clan/clan-core";
# Don't do this if your machines are on nixpkgs stable.
inputs.nixpkgs.follows = "nixpkgs";
};
```
### **Understanding `.clan-flake`**
The `.clan-flake` file, while optional, is instrumental in helping the Clan CLI identify your project's root directory, easing project management.
- `url`: Specifies the Git repository URL for Clan Core.
- `inputs.nixpkgs.follows`: Tells Nix to use the same `nixpkgs` input as your main input (in this case, it follows `nixpkgs`).
### Edit Flake.nix
Open the `flake.nix` file and set a unique `clanName` if you want you can also set an optional `clanIcon` or even a per `machineIcon`. These will be used by our future clan GUI.
3. **Update Outputs**: Then modify the `outputs` section of your `flake.nix` to adapt to Clan Core's new provisioning method. The key changes are as follows:
### Remote into the target machine
**Right now clan assumes that you already have NixOS running on the target machine.**
If that is not the case you can use our [installer image](./install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
Add `clan-core` to the output
On the remote execute:
1. Generate a hardware-config.nix
```bash
nixos-generate-config --root /etc/nixos --no-filesystems
```
2. Copy it over and put it into you `machines/jon/hardware-config.nix` folder
```bash
scp -r root@<jon-ip>:/etc/nixos/hardware-config.nix ./machines/jon
```
3. Find the remote disk id by executing on the remote:
```bash
lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
```
4. Edit the following fields inside the `flake.nix`
- `clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";`
- `clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/__CHANGE_ME__";
};`
```diff
- outputs = { self, nixpkgs, }:
+ outputs = { self, nixpkgs, clan-core }:
```
5. Generate secrets used by clan modules by executing
```bash
clan facts generate
```
Previous configuration:
```nix
{
nixosConfigurations.example-desktop = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
];
[...]
};
}
```
After change:
```nix
let clan = clan-core.lib.buildClan {
# this needs to point at the repository root
directory = self;
specialArgs = {};
clanName = "NEEDS_TO_BE_UNIQUE"; # TODO: Changeme
machines = {
example-desktop = {
nixpkgs.hostPlatform = "x86_64-linux";
imports = [ ./configuration.nix ];
};
};
};
in { inherit (clan) nixosConfigurations clanInternals; }
```
- `nixosConfigurations`: Defines NixOS configurations, using Clan Core’s `buildClan` function to manage the machines.
- Inside `machines`, a new machine configuration is defined (in this case, `example-desktop`).
- Inside `example-desktop` which is the target machine hostname, `nixpkgs.hostPlatform` specifies the host platform as `x86_64-linux`.
- `clanInternals`: Is required to enable evaluation of the secret generation/upload script on every architecture
- `clanName`: Is required and needs to be globally unique, as else we have a cLAN name clash
4. **Rebuild and Switch**: Rebuild your NixOS configuration using the updated flake:
```shellSession
$ sudo nixos-rebuild switch --flake .
```
- This command rebuilds and switches to the new configuration. Make sure to include the `--flake .` argument to use the current directory as the flake source.
5. **Test Configuration**: Before rebooting, verify that your new configuration builds without errors or warnings.
6. **Reboot**: If everything is fine, you can reboot your system to apply the changes:
```shellSession
$ sudo reboot
```
7. **Verify**: After the reboot, confirm that your system is running with the new configuration, and all services and applications are functioning as expected.
By following these steps, you've successfully migrated your NixOS Flake configuration to include the `clan-core` input and adapted the `outputs` section to work with Clan Core's new machine provisioning method.
## What's next
After creating your flake, you can check out how to add [new machines](./machines.md)
### **Next Steps**
Ready to expand? Explore how to install a new machine with the helpful documentation [here](./machines.md).
---
# Integrating Clan with Flakes using Flake-Parts
Clan supports integration with the Nix ecosystem through its flake module, making it compatible with [flake.parts](https://flake.parts/),
a tool for modular Nix flakes composition.
Here's how to set up Clan using flakes and flake-parts.
### 1. Update Your Flake Inputs
To begin, you'll need to add `clan-core` as a new dependency in your flake's inputs. This is alongside the already existing dependencies, such as `flake-parts` and `nixpkgs`. Here's how you can update your `flake.nix` file:
```diff
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
inputs.flake-parts.url = "github:hercules-ci/flake-parts";
inputs.flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
+ inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
+ inputs.clan-core.inputs.nixpkgs.follows = "nixpkgs";
+ inputs.clan-core.inputs.flake-parts.follows = "flake-parts";
```
### 2. Import Clan-Core Flake Module
After updating your flake inputs, the next step is to import the `clan-core` flake module into your project. This allows you to utilize Clan functionalities within your Nix project. Update your `flake.nix` file as shown below:
```nix
outputs =
inputs@{ flake-parts, ... }:
flake-parts.lib.mkFlake { inherit inputs; } (
{
imports = [
inputs.clan-core.flakeModules.default
];
}
);
```
### 3. Configure Clan Settings and Define Machines
Lastly, define your Clan configuration settings, including a unique clan name and the machines you want to manage with Clan.
This is where you specify the characteristics of each machine,
such as the platform and specific Nix configurations. Update your `flake.nix` like this:
```nix
outputs =
inputs@{ flake-parts, ... }:
flake-parts.lib.mkFlake { inherit inputs; } (
{
imports = [
inputs.clan-core.flakeModules.default
];
clan = {
clanName = "NEEDS_TO_BE_UNIQUE"; # Please replace this with a unique name for your clan.
directory = inputs.self;
machines = {
example-desktop = {
nixpkgs.hostPlatform = "x86_64-linux";
imports = [ ./configuration.nix ];
};
};
};
}
);
```
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).

24
nixosModules/installer/default.nix
View File

@ -5,6 +5,12 @@
...
}:
{
############################################
# #
# For install image debugging execute: #
# $ qemu-kvm result/stick.raw -snapshot #
# #
############################################
systemd.tmpfiles.rules = [ "d /var/shared 0777 root root - -" ];
imports = [
(modulesPath + "/profiles/installation-device.nix")
@ -59,12 +65,15 @@
fi
'';
boot.loader.systemd-boot.enable = true;
# boot.loader.systemd-boot.enable = true;
# Grub doesn't find devices for both BIOS and UEFI?
# Mic92: Please write where this exactly breaks if you want to comment out grub again.
# NOTE: We need grub here. Otherwise, the system won't boot in some machines.
# example: Lenovo E495 didn't boot without grub.
boot.loader.grub.efiInstallAsRemovable = true;
boot.loader.grub.efiSupport = true;
#boot.loader.grub.efiInstallAsRemovable = true;
#boot.loader.grub.efiSupport = true;
disko.devices = {
disk = {
stick = {
@ -74,10 +83,11 @@
content = {
type = "gpt";
partitions = {
#boot = {
# size = "1M";
# type = "EF02"; # for grub MBR
#};
boot = {
priority = 1;
size = "1M";
type = "EF02"; # for grub MBR
};
ESP = {
size = "100M";
type = "EF00";

2
pkgs/clan-cli/clan_cli/flakes/create.py
View File

@ -6,7 +6,7 @@ from ..cmd import CmdOut, run
from ..errors import ClanError
from ..nix import nix_command, nix_shell
DEFAULT_URL: str = "git+https://git.clan.lol/clan/clan-core?new-clan"
DEFAULT_URL: str = "git+https://git.clan.lol/clan/clan-core"
def create_flake(directory: Path, url: str) -> dict[str, CmdOut]:

16
pkgs/installer/flake-module.nix
View File

@ -7,7 +7,22 @@ let
self.nixosModules.installer
self.inputs.nixos-generators.nixosModules.all-formats
];
# Provide convenience for connecting to wifi
networking.wireless.enable = false;
# Use iwd instead of wpa_supplicant. It has a user friendly CLI
networking.wireless.iwd = {
settings = {
Network = {
EnableIPv6 = true;
RoutePriorityOffset = 300;
};
Settings = {
AutoConnect = true;
};
};
enable = true;
};
system.stateVersion = config.system.nixos.version;
nixpkgs.pkgs = self.inputs.nixpkgs.legacyPackages.x86_64-linux;
};
@ -30,7 +45,6 @@ in
machines.installer = {
imports = [ installerModule ];
fileSystems."/".device = lib.mkDefault "/dev/null";
boot.loader.grub.device = lib.mkDefault "/dev/null";
};
};
flake.apps.x86_64-linux.install-vm.program = installer.config.formats.vm.outPath;

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

@ -10,7 +10,61 @@
pkgs = clan-core.inputs.nixpkgs.legacyPackages.${system};
clan = clan-core.lib.buildClan {
directory = self;
clanName = "__CHANGE_ME__";
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
clanIcon = null; # Optional, a path to an image file
# TODO: boot into the installer
# remote> nixos-generate-config --root /tmp/config --no-filesystems
# local> mkdir -p ./machines/machine1
# local> scp -r root@machine1:/tmp/config ./machines/machine1
# local> Edit ./machines/machine1/configuration.nix to your liking
machines = {
jon = {
nixpkgs.hostPlatform = system;
imports = [
./machines/jon/configuration.nix
clan-core.clanModules.sshd
clan-core.clanModules.diskLayouts
{
config.clanCore.machineIcon = null; # Optional, a path to an image file
# Set this for clan commands use ssh i.e. `clan machines update`
config.clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
# TODO: Example how to use disko for more complicated setups
# remote> lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT
config.clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/__CHANGE_ME__";
};
config.services.getty.autologinUser = "root";
# TODO: Document that there needs to be one controller
config.clan.networking.zerotier.controller.enable = true;
}
];
};
sara = {
nixpkgs.hostPlatform = system;
imports = [
./machines/sara/configuration.nix
clan-core.clanModules.sshd
clan-core.clanModules.diskLayouts
{
config.clanCore.machineIcon = null; # Optional, a path to an image file
# Set this for clan commands use ssh i.e. `clan machines update`
config.clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
# local> clan facts generate
config.clan.diskLayouts.singleDiskExt4 = {
device = "/dev/disk/by-id/__CHANGE_ME__";
};
}
];
};
};
};
in
{

4
templates/new-clan/machines/jon/configuration.nix Normal file
View File

@ -0,0 +1,4 @@
{ ... }:
{
}

4
templates/new-clan/machines/sara/configuration.nix Normal file
View File

@ -0,0 +1,4 @@
{ ... }:
{
}

36
templates/new-clan/modules/disko.nix Normal file
View File

@ -0,0 +1,36 @@
{
config.disko.devices = {
disk = {
main = {
type = "disk";
device = throw "Change this to your disk device";
content = {
type = "gpt";
partitions = {
boot = {
size = "1M";
type = "EF02"; # for grub MBR
};
ESP = {
size = "512M";
type = "EF00";
content = {
type = "filesystem";
format = "vfat";
mountpoint = "/boot";
};
};
root = {
size = "100%";
content = {
type = "filesystem";
format = "ext4";
mountpoint = "/";
};
};
};
};
};
};
};
}