diff --git a/docs/admins/machines.md b/docs/admins/machines.md index b0de192fb..0bedf297a 100644 --- a/docs/admins/machines.md +++ b/docs/admins/machines.md @@ -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._ diff --git a/docs/admins/migrate.md b/docs/admins/migrate.md new file mode 100644 index 000000000..96ee4612d --- /dev/null +++ b/docs/admins/migrate.md @@ -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). + +--- \ No newline at end of file diff --git a/docs/admins/quickstart.md b/docs/admins/quickstart.md index df04d8618..c66a0ba1c 100644 --- a/docs/admins/quickstart.md +++ b/docs/admins/quickstart.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). diff --git a/machines/my-machine/settings.json b/machines/my-machine/settings.json deleted file mode 100644 index 9e26dfeeb..000000000 --- a/machines/my-machine/settings.json +++ /dev/null @@ -1 +0,0 @@ -{} \ No newline at end of file