diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 94e0593d4..b4dd46d2f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -59,14 +59,15 @@ nav: - Configure Disk Config: guides/getting-started/choose-disk.md - Update Machine: guides/getting-started/update.md - Continuous Integration: guides/getting-started/flake-check.md - - Using Services: guides/clanServices.md + - Convert Existing NixOS Config: guides/getting-started/convert-flake.md + - ClanServices: guides/clanServices.md - Backup & Restore: guides/backups.md - Disk Encryption: guides/disk-encryption.md - Age Plugins: guides/age-plugins.md - Secrets management: guides/secrets.md - Networking: guides/networking.md - Zerotier VPN: guides/mesh-vpn.md - - Secure Boot: guides/secure-boot.md + - How to disable Secure Boot: guides/secure-boot.md - Flake-parts: guides/flake-parts.md - macOS: guides/macos.md - Contributing: @@ -77,7 +78,6 @@ nav: - Writing a Service Module: guides/services/community.md - Writing a Disko Template: guides/disko-templates/community.md - Migrations: - - Migrate existing Flakes: guides/migrations/migration-guide.md - Migrate from clan modules to services: guides/migrations/migrate-inventory-services.md - Facts Vars Migration: guides/migrations/migration-facts-vars.md - Disk id: guides/migrations/disk-id.md diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index b3d93ad29..a26d60c5b 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -2,9 +2,9 @@ Machines can be added using the following methods -- Editing nix expressions in flake.nix (i.e. via `clan-core.lib.clan`) -- Editing machines/`machine_name`/configuration.nix (automatically included if it exists) -- `clan machines create` (imperative) +- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../../concepts/autoincludes.md)) +- Imperative via cli command: `clan machines create` +- Editing nix expressions in flake.nix See [`clan-core.lib.clan`](/options/?scope=Flake Options (clan.nix file)) See the complete [list](../../concepts/autoincludes.md) of auto-loaded files. @@ -39,7 +39,6 @@ See the complete [list](../../concepts/autoincludes.md) of auto-loaded files. The imperative command might create a machine folder in `machines/jon` And might persist information in `inventory.json` - ### Configuring a machine !!! Note diff --git a/docs/site/guides/migrations/migration-guide.md b/docs/site/guides/getting-started/convert-flake.md similarity index 82% rename from docs/site/guides/migrations/migration-guide.md rename to docs/site/guides/getting-started/convert-flake.md index d2e2c78d5..80525c595 100644 --- a/docs/site/guides/migrations/migration-guide.md +++ b/docs/site/guides/getting-started/convert-flake.md @@ -1,18 +1,20 @@ -# Migrate existing NixOS configurations +# Convert existing NixOS configurations -This guide will help you migrate your existing NixOS configurations into Clan. +This guide will help you convert your existing NixOS configurations into a Clan. !!! Warning Migrating instead of starting new can be trickier and might lead to bugs or - unexpected issues. We recommend following the [Getting Started](../getting-started/index.md) guide first. Once you have a working setup, you can easily transfer your NixOS configurations over. + unexpected issues. We recommend reading the [Getting Started](./index.md) guide first. + + Once you have a working setup and understand the concepts transfering your NixOS configurations over is easy. + +## Back up your existing configuration -## Back up your existing configuration! Before you start, it is strongly recommended to back up your existing configuration in any form you see fit. If you use version control to manage your configuration changes, it is also a good idea to follow the migration guide in a separte branch until everything works as expected. - ## Starting Point We assume you are already using NixOS flakes to manage your configuration. If @@ -43,10 +45,9 @@ have have two hosts: **berlin** and **cologne**. } ``` -## Add clan-core Input +## 1. Add `clan-core` to `inputs` -Add `clan-core` to your flake as input. It will provide everything we need to -manage your configurations with clan. +Add `clan-core` to your flake as input. ```nix inputs.clan-core = { @@ -56,7 +57,7 @@ inputs.clan-core = { } ``` -## Update Outputs +## 2. Update Outputs To be able to access our newly added dependency, it has to be added to the output parameters. @@ -105,24 +106,23 @@ For the provide flake example, your flake should now look like this: { nixosConfigurations = clan.nixosConfigurations; - inherit (clan) clanInternals; - - clan = { - inherit (clan) templates; - }; + inherit (clan.config) nixosConfigurations nixosModules clanInternals; + clan = clan.config; }; } ``` -Et voilà! Your existing hosts are now part of a clan. Existing Nix tooling +✅ Et voilà! Your existing hosts are now part of a clan. + +Existing Nix tooling should still work as normal. To check that you didn't make any errors, run `nix flake show` and verify both hosts are still recognized as if nothing had -changed. You should also see the new `clanInternals` output. +changed. You should also see the new `clan` output. ``` ❯ nix flake show git+file:///my-nixos-config -├───clanInternals: unknown +├───clan: unknown └───nixosConfigurations ├───berlin: NixOS configuration └───cologne: NixOS configuration @@ -131,7 +131,7 @@ git+file:///my-nixos-config Of course you can also rebuild your configuration using `nixos-rebuild` and veryify everything still works. -## Add Clan CLI devShell +## 3. Add `clan-cli` to your `devShells` At this point Clan is set up, but you can't use the CLI yet. To do so, it is recommended to expose it via a `devShell` in your flake. It is also possible to @@ -163,8 +163,8 @@ cologne ## Specify Targets -Clan needs to know where it can reach your hosts. For each of your hosts, set -`clan.core.networking.targetHost` to its adress or hostname. +Clan needs to know where it can reach your hosts. For testing purpose set +`clan.core.networking.targetHost` to the machines adress or hostname. ```nix # machines/berlin/configuration.nix @@ -173,6 +173,8 @@ Clan needs to know where it can reach your hosts. For each of your hosts, set } ``` +See our guide on for properly [configuring machines networking](../networking.md) + ## Next Steps You are now fully set up. Use the CLI to manage your hosts or proceed to diff --git a/lib/modules/inventory/distributed-service/service-module.nix b/lib/modules/inventory/distributed-service/service-module.nix index 250bc3971..35256a753 100644 --- a/lib/modules/inventory/distributed-service/service-module.nix +++ b/lib/modules/inventory/distributed-service/service-module.nix @@ -639,7 +639,7 @@ in Exports are used to share and expose information between instances. - Define exports in the [`perInstance`](#perInstance) or [`perMachine`](#perMachine) scope. + Define exports in the [`perInstance`](#roles.perInstance) or [`perMachine`](#perMachine) scope. Accessing the exports: