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

Improved docs

Browse Source
This commit is contained in:
Luis Hebendanz 2024-04-05 18:03:14 +02:00
parent f2ff815aa7
commit 2e29c031ef
4 changed files with 226 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/admins/machines.md
View File

@ -1,28 +1,26 @@
# Managing NixOS Machines
# Managing NixOS Machines with Clan
## Add Your First Machine
Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
To start managing a new machine, use the following commands to create and then list your machines:
## Adding Your First Machine
```shellSession
$ clan machines create my-machine
$ clan machines list
my-machine
```
Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
## Configure Your Machine
1. **Create Your Machine**: Generate a new machine configuration using the Clan CLI with the command below:
```bash
clan machines create my-machine
```
2. **List Available Machines**: Verify the successful addition of your new machine and view any existing machines in your configuration:
```bash
clan machines list
```
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._

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

@ -0,0 +1,181 @@
## **Migrating Existing NixOS Configuration Flake to Clan Core**
Transitioning your existing setup to Clan Core is straightforward with these detailed steps. Follow this guide to ensure a smooth migration.
### Before You Begin
1. **Backup Your Current Configuration**: Start by creating a backup of your existing NixOS configuration. This step is crucial as it ensures you have the option to revert to your original setup if necessary.
```shellSession
cp -r /etc/nixos ~/nixos-backup
```
2. **Initialize 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:
1. **Generate a Trivial flake.nix File**: This creates a basic `flake.nix` file that you can later customize for your project.
```bash
cd /etc/nixos && nix flake init -t github:NixOS/templates#trivial
```
2. **Initialize a Git Repository (if necessary)**: 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
```
3. **Add Files to the Repository**: Add your project files to the Git repository. This step is essential for nix flakes as it will ignore files not inside the git repo.
```bash
git add .
```
1. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
```nix
inputs.clan-core = {
url = "git+https://git.clan.lol/clan/clan-core";
inputs.nixpkgs.follows = "nixpkgs"; # Only if your configuration uses nixpkgs stable.
};
```
Ensure to replace the placeholder URL with the actual Git repository URL for Clan Core. The `inputs.nixpkgs.follows` line indicates that your flake should use the same `nixpkgs` input as your main flake configuration.
2. **Update Outputs**: Modify the `outputs` section of your `flake.nix` to accommodate Clan Core's provisioning method:
```diff
- outputs = { self, nixpkgs }: {
+ outputs = { self, nixpkgs, clan-core }:
```
3. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
- Previously:
```nix
outputs = { self, nixpkgs }: {
nixosConfigurations.example-desktop = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [ ./configuration.nix ];
};
}
```
- With Clan Core:
```nix
outputs = { self, nixpkgs, clan-core }:
let clan = clan-core.lib.buildClan {
directory = self; # Point this to the repository root.
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
machines = {
example-desktop = {
nixpkgs.hostPlatform = "x86_64-linux";
imports = [ ./configuration.nix ];
};
};
};
in { inherit (clan) nixosConfigurations clanInternals; };
```
4. **Rebuild and Switch**: Apply your updated configuration:
```shellSession
sudo nixos-rebuild switch --flake /etc/nixos
```
This rebuilds your system configuration and switches to it. The `--flake .` argument specifies that the current directory's flake should be used.
5. **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
6. **Reboot**: If the build is successful and no issues are detected, reboot your system:
```shellSession
sudo reboot
```
7. **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 flake, you can check out how to add [new machines](./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:
```nix
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";
# Newly added
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).
### **Next Steps**
With your flake created, explore how to add new machines by reviewing the documentation provided [here](./machines.md).
---

215
docs/admins/quickstart.md
View File

@ -1,200 +1,45 @@
# 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`).
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:
Add `clan-core` to the output
```diff
- outputs = { self, nixpkgs, }:
+ outputs = { self, nixpkgs, clan-core }:
```
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 add new machines to your project 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).

1
machines/my-machine/settings.json
View File

@ -1 +0,0 @@
{}