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

migrate.md: make docs more approachable

Browse Source
This commit is contained in:
Johannes Kirschbauer
2024-04-07 12:53:15 +02:00
parent 6a610c7a0b
commit 49d83fd659
1 changed files with 213 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
docs/admins/migrate.md
View File

@@ -1,164 +1,253 @@
## **Migrating Existing NixOS Configuration Flake to Clan Core**
# 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.
Transitioning your existing setup to Clan Core is easy and straightforward. Follow this guide to ensure a smooth migration.
## 0. Prerequisites
### Before You Begin
### Backup Your Current Configuration
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.
Create a backup of your existing NixOS configuration.
This step ensures you have the option to revert to your original setup if necessary.
```shellSession
cp -r /etc/nixos ~/nixos-backup
```
```bash
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. Initialize a flake.nix
1. **Generate a Trivial flake.nix File**: This creates a basic `flake.nix` file that you can later customize for your project.
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.
```bash
cd /etc/nixos && nix flake init -t github:NixOS/templates#trivial
```
> Note: Clan is based on flakes, it is possible to use cLan without flakes but not officially supported yet.
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.
### Generate a Trivial flake.nix File
```bash
git init
```
This creates a basic `flake.nix` file that you can later customize for your project.
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.
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
git add .
```
```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:
3. **Create Machines Directory**: Create a machines directory where you put all machine specific nix configs like the configuration.nix
1. Create the machines directory in your git root example: `/etc/nixos/machines/`
```bash
mkdir machines
```
```nix
# flake.nix
{
description = "A very basic flake";
2. Inside the machines directory create a directory named after the hostname of the machine you want to manage with clan.
```bash
mkdir machines/jons-desktop
```
inputs = {
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
};
3. Move your `configuration.nix` and included files into `machines/jons-desktop`
```bash
mv configuration.nix machines/jons-desktop/configuration.nix
```
outputs = { self, nixpkgs }: {
4. Git add your new machines folder
```bash
git add machines
```
packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
4. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
```nix
inputs.clan-core = {
url = "git+https://git.clan.lol/clan/clan-core";
inputs.nixpkgs.follows = "nixpkgs"; # Only if your configuration uses nixpkgs unstable.
};
```
};
}
```
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.
### 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.
5. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
```bash
git init && git add .
```
- Previously:
> 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.
```nix
outputs = { self, nixpkgs }: {
nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [ ./configuration.nix ];
};
};
```
Confirm your flake repository is working:
- With Clan Core:
```bash
nix flake show
```
```nix
outputs = { self, nixpkgs, clan-core }:
let clan = clan-core.lib.buildClan {
specialArgs = { }; # Add arguments to every nix import in here
directory = self; # Point this to the repository root.
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
machines = {
jons-desktop = {
nixpkgs.hostPlatform = "x86_64-linux";
imports = [
clan-core.clanModules.sshd # Add openssh server for clan management
./machines/jons-desktop/configuration.nix
];
};
```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; };
```
};
in
{
inherit (clan) nixosConfigurations clanInternals;
};
```
## Rebuild and Switch
Apply your updated configuration
6. **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`
```shellSession
sudo nixos-rebuild switch --flake /etc/nixos
```
```bash
sudo ls -s ~/clans/empire /etc/nixos
```
This rebuilds your system configuration and switches to it. The `--flake /etc/nixos` argument specifies that the `/etc/nixos` directory's flake should be used.
```bash
sudo nixos-rebuild switch
```
7. **Test Configuration**: Ensure your new configuration builds correctly without any errors or warnings before proceeding.
This rebuilds your system configuration and switches to it.
8. **Reboot**: If the build is successful and no issues are detected, reboot your system:
> Note: nixos-rebuild switch uses /etc/nixos by default.
```shellSession
sudo reboot
```
## Finish installation
9. **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
- **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
```
# 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?
## What's next
After creating your clan checkout [managing machines](./machines.md)
- **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?
## Integrating Clan with Flakes using Flake-Parts
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.
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:
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
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";
# flake.nix
inputs = {
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
# 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";
# 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 into your project. This allows you to utilize Clan functionalities within your Nix project. Update your `flake.nix` file as shown below:
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 =
@@ -174,9 +263,9 @@ After updating your flake inputs, the next step is to import the `clan-core` fla
### 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:
Configure your clan settings and define machine configurations.
Below is a guide on how to structure this in your flake.nix:
```nix
outputs =
@@ -187,14 +276,17 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
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
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
directory = inputs.self;
machines = {
jons-desktop = {
nixpkgs.hostPlatform = "x86_64-linux";
imports = [
clan-core.clanModules.sshd # Add openssh server for clan management
clan-core.clanModules.sshd # Add openssh server for cLan management
./configuration.nix
];
};
@@ -207,7 +299,14 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
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**
### 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?