forked from clan/clan-core
Improved docs
This commit is contained in:
parent
f2ff815aa7
commit
2e29c031ef
@ -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
181
docs/admins/migrate.md
Normal 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).
|
||||
|
||||
---
|
@ -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 +0,0 @@
|
||||
{}
|
Loading…
Reference in New Issue
Block a user