diff --git a/README.md b/README.md index 2154cdfb1..dd93740df 100644 --- a/README.md +++ b/README.md @@ -18,13 +18,13 @@ Our mission is simple: to democratize computing by providing tools that empower If you're new to cLAN and eager to dive in, start with our quickstart guide and explore the core functionalities that Clan offers: -- **Quickstart Guide**: Check out [quickstart.md](docs/admins/quickstart.md) to get up and running with cLAN in no time. +- **Quickstart Guide**: Check out [quickstart.md](docs/admins/01-quickstart.md) to get up and running with cLAN in no time. ### Managing Secrets In the Clan ecosystem, security is paramount. Learn how to handle secrets effectively: -- **Secrets Management**: Securely manage secrets by consulting [secrets-management.md](docs/admins/secrets-management.md). +- **Secrets Management**: Securely manage secrets by consulting [secrets.md](docs/admins/06-secrets.md). ### Contributing to cLAN diff --git a/docs/admins/01-quickstart.md b/docs/admins/01-quickstart.md index dbf9c37cb..82495ca65 100644 --- a/docs/admins/01-quickstart.md +++ b/docs/admins/01-quickstart.md @@ -7,8 +7,7 @@ Welcome to your simple guide on starting a new Clan project! We've put together a straightforward guide to help you out: - [**Starting with a New Clan Project**](#starting-with-a-new-clan-project): Create a new Clan from scratch. -- [**Migrating Existing Flake Configuration**](migrate.md#migrating-existing-nixos-configuration-flake): How to switch your current setup to a Clan setup. -- [**Integrating Clan using Flake-Parts**](./migrate.md#integrating-clan-with-flakes-using-flake-parts) +- [**Integrating Clan using Flake-Parts**](./08-flake-parts.md) --- @@ -85,7 +84,7 @@ Open the `flake.nix` file and set a unique `clanName` if you want you can also s **Right now clan assumes that you already have NixOS running on the target machine.** -If that is not the case you can use our [installer image](./install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password. +If that is not the case you can use our [installer image](./03-install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password. On the remote execute: 1. Generate a hardware-config.nix @@ -112,11 +111,11 @@ On the remote execute: ``` ### **Next Steps** -Ready to expand? Explore how to install a new machine with the helpful documentation [here](./machines.md). +Ready to expand? Explore how to install a new machine with the helpful documentation [here](./02-machines.md). Ready to explore more? - **Adding New Machines to your setup**. [Following our template](/templates/new-clan/flake.nix) -- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how] (./machines.md). +- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how] (./02-machines.md). --- diff --git a/docs/admins/02-machines.md b/docs/admins/02-machines.md index 7be4cc2be..2acb034c6 100644 --- a/docs/admins/02-machines.md +++ b/docs/admins/02-machines.md @@ -322,7 +322,7 @@ clan machines install jon root@192.168.188.50 > `Install jon to root@192.168.188.50? [y/N]` > Confirm with `y` after checking that for correctness -If you didn't generate any secrets yet. The deployment command will fail (Don't worry you can re-run it). See [secrets-management](./secrets-management.md) for how to generate your initial secrets. +If you didn't generate any secrets yet. The deployment command will fail (Don't worry you can re-run it). See [secrets](./06-secrets.md) for how to generate your initial secrets. #### ๐ŸŽ‰ ๐Ÿš€ Your machine is all set up diff --git a/docs/admins/08-flake-parts.md b/docs/admins/08-flake-parts.md new file mode 100644 index 000000000..3fcec3cd0 --- /dev/null +++ b/docs/admins/08-flake-parts.md @@ -0,0 +1,93 @@ +# 08 Clan with `flake-parts` + +Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows modular compositions. + +Here's how to set up Clan using flakes and flake-parts. + +## 1. Update Your Flake Inputs + +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 +# flake.nix +inputs = { + nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable"; + + # 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. This will make the [clan options](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) available within `mkFlake`. + +```nix + outputs = + inputs@{ flake-parts, ... }: + flake-parts.lib.mkFlake { inherit inputs; } ( + { + imports = [ + inputs.clan-core.flakeModules.default + ]; + } + ); +``` + +### 3. Configure Clan Settings and Define Machines + +Configure your clan settings and define machine configurations. + +Below is a guide on how to structure this in your flake.nix: + +```nix + outputs = + inputs@{ flake-parts, ... }: + flake-parts.lib.mkFlake { inherit inputs; } ( + { + imports = [ + 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 + + machines = { + jons-desktop = { + nixpkgs.hostPlatform = "x86_64-linux"; + imports = [ + clan-core.clanModules.sshd # Add openssh server for Clan management + ./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](./02-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/ I think? \ No newline at end of file diff --git a/docs/admins/99-migrate.md b/docs/admins/99-migrate.md deleted file mode 100644 index 3173ff836..000000000 --- a/docs/admins/99-migrate.md +++ /dev/null @@ -1,312 +0,0 @@ -# 99 Migration guide - -Transitioning your existing setup to Clan Core is easy and straightforward. Follow this guide to ensure a smooth migration. - -## 0. Prerequisites - -### Backup Your Current Configuration - -Create a backup of your existing NixOS configuration. -This step ensures you have the option to revert to your original setup if necessary. - -```bash -cp -r /etc/nixos ~/nixos-backup -``` - -## 1. Initialize a 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. - -> Note: Clan is based on flakes, it is possible to use Clan without flakes but not officially supported yet. - -### Generate a Trivial flake.nix File - -This creates a basic `flake.nix` file that you can later customize for your project. - -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 -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: - -```nix -# flake.nix -{ - description = "A very basic flake"; - - inputs = { - nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable"; - }; - - outputs = { self, nixpkgs }: { - - packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello; - - packages.x86_64-linux.default = self.packages.x86_64-linux.hello; - - }; -} -``` - -### 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. - -```bash -git init && git add . -``` - -> 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. - -Confirm your flake repository is working: - -```bash -nix flake show -``` - -```bash -warning: creating lock file flake.lock' -path: -โ””โ”€โ”€โ”€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; - }; -``` - -## 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` - -```bash -sudo ls -s ~/clans/empire /etc/nixos -``` - -```bash -sudo nixos-rebuild switch -``` - -This rebuilds your system configuration and switches to it. - -> Note: nixos-rebuild switch uses /etc/nixos by default. - -## Finish installation - -- **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 - ``` - -- **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 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. - -Here's how to set up Clan using flakes and flake-parts. - -### 1. Update Your Flake Inputs - -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 -# flake.nix -inputs = { - nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable"; - - # 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. This will make the [clan options](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) available within `mkFlake`. - -```nix - outputs = - inputs@{ flake-parts, ... }: - flake-parts.lib.mkFlake { inherit inputs; } ( - { - imports = [ - inputs.clan-core.flakeModules.default - ]; - } - ); -``` - -### 3. Configure Clan Settings and Define Machines - -Configure your clan settings and define machine configurations. - -Below is a guide on how to structure this in your flake.nix: - -```nix - outputs = - inputs@{ flake-parts, ... }: - flake-parts.lib.mkFlake { inherit inputs; } ( - { - imports = [ - 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 - - machines = { - jons-desktop = { - nixpkgs.hostPlatform = "x86_64-linux"; - imports = [ - clan-core.clanModules.sshd # Add openssh server for Clan management - ./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). - ---- - -## 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/ I think? \ No newline at end of file