clan-core/docs/admins/quickstart.md

Initializing a New Clan Project

Create a new flake

1. To start a new project, execute the following command to add the clan cli to your shell:

$ nix shell git+https://git.clan.lol/clan/clan-core

2. Then use the following commands to initialize a new clan-flake:

$ clan flakes create my-clan

This action will generate two primary files: flake.nix and .clan-flake.

$ 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

---

Migrating Existing NixOS Configuration Flake

Before You Begin

1. Backup Your Current Configuration: Always start by making a backup of your current NixOS configuration to ensure you can revert if needed.

   $ cp -r /etc/nixos ~/nixos-backup
   

2. Update Flake Inputs: Add a new input for the clan-core dependency:

   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";
   };
   

   • 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

   -  outputs = { self, nixpkgs,  }:
   +  outputs = { self, nixpkgs, clan-core }:
   

   Previous configuration:

   {
     nixosConfigurations.example-desktop = nixpkgs.lib.nixosSystem {
       system = "x86_64-linux";
       modules = [
           ./configuration.nix
       ];
       [...]
     };
   }
   

   After change:

   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:

   $ 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:

   $ 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

---

Integrating Clan with Flakes using Flake-Parts

Clan supports integration with the Nix ecosystem through its flake module, making it compatible with 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:

  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:

  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:

  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.