From 4101ebc45b80fa1623561450836c62a8ca223b2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Mon, 25 Aug 2025 11:08:55 +0200
Subject: [PATCH] services/user: add migration guide for root-password

---
 clanServices/users/README.md                  | 41 +++++++++++++++++++
 .../migrations/migrate-inventory-services.md  |  2 +-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/clanServices/users/README.md b/clanServices/users/README.md
index ad7a586f6..4748e1a5a 100644
--- a/clanServices/users/README.md
+++ b/clanServices/users/README.md
@@ -29,3 +29,44 @@
   };
 }
 ```
+
+## Migration from `root-password` module
+
+The deprecated `clan.root-password` module has been replaced by the `users` module. Here's how to migrate:
+
+### 1. Update your flake configuration
+
+Replace the `root-password` module import with a `users` service instance:
+
+```nix
+# OLD - Remove this from your nixosModules:
+imports = [
+  self.inputs.clan-core.clanModules.root-password
+];
+
+# NEW - Add to inventory.instances or machines/flake-module.nix:
+instances = {
+  users-root = {
+    module.name = "users";
+    module.input = "clan-core";
+    roles.default.tags.nixos = { };
+    roles.default.settings = {
+      user = "root";
+      prompt = false;  # Set to true if you want to be prompted
+      groups = [ ];
+    };
+  };
+};
+```
+
+### 2. Migrate vars
+
+The vars structure has changed from `root-password` to `user-password-root`:
+
+```bash
+# For each machine, rename the vars directories:
+cd vars/per-machine/<machine-name>/
+mv root-password user-password-root
+mv user-password-root/password-hash user-password-root/user-password-hash
+mv user-password-root/password user-password-root/user-password
+```
diff --git a/docs/site/guides/migrations/migrate-inventory-services.md b/docs/site/guides/migrations/migrate-inventory-services.md
index 297b43c72..0f4eaa4eb 100644
--- a/docs/site/guides/migrations/migrate-inventory-services.md
+++ b/docs/site/guides/migrations/migrate-inventory-services.md
@@ -271,7 +271,7 @@ The following table shows the migration status of each deprecated clanModule:
 | `nginx`                  | ❌ Removed                                                        |                                                                  |
 | `packages`               | ✅ [Migrated](../../reference/clanServices/packages.md)           |                                                                  |
 | `postgresql`             | ❌ Removed                                                        | Now an [option](../../reference/clan.core/settings.md)           |
-| `root-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              |                                                                  |
+| `root-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              | See [migration guide](../../reference/clanServices/users.md#migration-from-root-password-module) |
 | `single-disk`            | ❌ Removed                                                        |                                                                  |
 | `sshd`                   | ✅ [Migrated](../../reference/clanServices/sshd.md)               |                                                                  |
 | `state-version`          | ✅ [Migrated](../../reference/clanServices/state-version.md)      |                                                                  |