migrate.md: make docs more approachable
This commit is contained in:
Johannes Kirschbauer
@@ -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
|
```bash
|
||||||
cp -r /etc/nixos ~/nixos-backup
|
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
|
> Note: Clan is based on flakes, it is possible to use cLan without flakes but not officially supported yet.
|
||||||
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.
|
### Generate a Trivial flake.nix File
|
||||||
|
|
||||||
```bash
|
This creates a basic `flake.nix` file that you can later customize for your project.
|
||||||
git init
|
|
||||||
```
|
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.
|
||||||
|
|
||||||
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
|
||||||
|
mkdir -p ~/clans/empire && cd ~/clans/empire
|
||||||
|
nix flake init -t github:NixOS/templates#trivial
|
||||||
|
```
|
||||||
|
|
||||||
```bash
|
This will initialize a `flake.nix` file that looks like this:
|
||||||
git add .
|
|
||||||
```
|
|
||||||
|
|
||||||
|
```nix
|
||||||
|
# flake.nix
|
||||||
|
{
|
||||||
|
description = "A very basic flake";
|
||||||
|
|
||||||
3. **Create Machines Directory**: Create a machines directory where you put all machine specific nix configs like the configuration.nix
|
inputs = {
|
||||||
1. Create the machines directory in your git root example: `/etc/nixos/machines/`
|
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
|
||||||
```bash
|
};
|
||||||
mkdir machines
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Inside the machines directory create a directory named after the hostname of the machine you want to manage with clan.
|
outputs = { self, nixpkgs }: {
|
||||||
```bash
|
|
||||||
mkdir machines/jons-desktop
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Move your `configuration.nix` and included files into `machines/jons-desktop`
|
packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
|
||||||
```bash
|
|
||||||
mv configuration.nix machines/jons-desktop/configuration.nix
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Git add your new machines folder
|
packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
|
||||||
```bash
|
|
||||||
git add machines
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Update Flake Inputs**: Introduce a new input in your `flake.nix` for the Clan Core dependency:
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
```nix
|
### Initialize a Git Repository (optional/recommended)
|
||||||
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.
|
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 .
|
||||||
|
```
|
||||||
|
|
||||||
5. **Revise System Build Function**: Transition from using `lib.nixosSystem` to `clan-core.lib.buildClan` for building your machine derivations:
|
> 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.
|
||||||
|
|
||||||
- Previously:
|
Confirm your flake repository is working:
|
||||||
|
|
||||||
```nix
|
```bash
|
||||||
outputs = { self, nixpkgs }: {
|
nix flake show
|
||||||
nixosConfigurations.jons-desktop = nixpkgs.lib.nixosSystem {
|
```
|
||||||
system = "x86_64-linux";
|
|
||||||
modules = [ ./configuration.nix ];
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
- With Clan Core:
|
```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'
|
||||||
|
```
|
||||||
|
|
||||||
```nix
|
## 2. Create your first Machine
|
||||||
outputs = { self, nixpkgs, clan-core }:
|
|
||||||
let clan = clan-core.lib.buildClan {
|
Create a directory where you put **all machine specific configs** like the `configuration.nix` or `hardware-configuration.nix`
|
||||||
specialArgs = { }; # Add arguments to every nix import in here
|
|
||||||
directory = self; # Point this to the repository root.
|
> Following this structure will allow you nicely organize all your different machines and allows the cLan-CLI to automatically detect and manage your machines.
|
||||||
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
|
|
||||||
machines = {
|
```bash
|
||||||
jons-desktop = {
|
mkdir -p machines/jons-desktop
|
||||||
nixpkgs.hostPlatform = "x86_64-linux";
|
```
|
||||||
imports = [
|
|
||||||
clan-core.clanModules.sshd # Add openssh server for clan management
|
> In this case `jons-desktop` is the hostname of the machine you want to manage with cLan.
|
||||||
./machines/jons-desktop/configuration.nix
|
|
||||||
];
|
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
|
```bash
|
||||||
sudo nixos-rebuild switch --flake /etc/nixos
|
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
|
## Finish installation
|
||||||
sudo reboot
|
|
||||||
```
|
|
||||||
|
|
||||||
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:
|
- **Verify**: After rebooting, verify that your system operates with the new configuration and that all services and applications are functioning as expected.
|
||||||
* 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)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 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.
|
Here's how to set up Clan using flakes and flake-parts.
|
||||||
|
|
||||||
### 1. Update Your Flake Inputs
|
### 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
|
```nix
|
||||||
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
|
# flake.nix
|
||||||
inputs.flake-parts.url = "github:hercules-ci/flake-parts";
|
inputs = {
|
||||||
inputs.flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
|
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
|
||||||
|
|
||||||
# Newly added
|
# New flake-parts input
|
||||||
inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
|
flake-parts.url = "github:hercules-ci/flake-parts";
|
||||||
inputs.clan-core.inputs.nixpkgs.follows = "nixpkgs";
|
flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
|
||||||
inputs.clan-core.inputs.flake-parts.follows = "flake-parts";
|
|
||||||
|
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
|
### 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
|
```nix
|
||||||
outputs =
|
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
|
### 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.
|
Configure your clan settings and define machine configurations.
|
||||||
This is where you specify the characteristics of each machine,
|
|
||||||
such as the platform and specific Nix configurations. Update your `flake.nix` like this:
|
Below is a guide on how to structure this in your flake.nix:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
outputs =
|
outputs =
|
||||||
@@ -187,14 +276,17 @@ such as the platform and specific Nix configurations. Update your `flake.nix` li
|
|||||||
inputs.clan-core.flakeModules.default
|
inputs.clan-core.flakeModules.default
|
||||||
];
|
];
|
||||||
clan = {
|
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
|
specialArgs = { }; # Add arguments to every nix import in here
|
||||||
clanName = "__CHANGE_ME__"; # Ensure this is internet wide unique.
|
|
||||||
directory = inputs.self;
|
|
||||||
machines = {
|
machines = {
|
||||||
jons-desktop = {
|
jons-desktop = {
|
||||||
nixpkgs.hostPlatform = "x86_64-linux";
|
nixpkgs.hostPlatform = "x86_64-linux";
|
||||||
imports = [
|
imports = [
|
||||||
clan-core.clanModules.sshd # Add openssh server for clan management
|
clan-core.clanModules.sshd # Add openssh server for cLan management
|
||||||
./configuration.nix
|
./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,
|
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**
|
### Next Steps
|
||||||
|
|
||||||
With your flake created, explore how to add new machines by reviewing the documentation provided [here](./machines.md).
|
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?
|
||||||
Reference in New Issue
Block a user