diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index d4ddd0905..37b063082 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -51,6 +51,7 @@ nav: - πŸš€ Creating Your First Clan: guides/getting-started/index.md - πŸ“€ Create USB Installer (optional): guides/getting-started/installer.md - βš™οΈ Add Machines: guides/getting-started/add-machines.md + - βš™οΈ Add User: guides/getting-started/add-user.md - βš™οΈ Add Services: guides/getting-started/add-services.md - πŸ” Secrets & Facts: guides/getting-started/secrets.md - 🚒 Deploy Machine: guides/getting-started/deploy.md diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/guides/getting-started/add-services.md index 80d3dc797..3c54a5a9f 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/guides/getting-started/add-services.md @@ -51,7 +51,7 @@ To learn more: [Guide about clanService](../clanServices.md) Adding the following services is recommended for most users: -```{.nix title="clan.nix" hl_lines="7-22"} +```{.nix title="clan.nix" hl_lines="7-14"} { inventory.machines = { jon = { }; @@ -66,19 +66,10 @@ Adding the following services is recommended for most users: }; }; }; - jon-user = { # (3) - module.name = "users"; - - roles.default.tags.all = { }; - roles.default.settings = { - user = "jon"; - }; - }; # ... # elided }; } - ``` 1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration. diff --git a/docs/site/guides/getting-started/add-user.md b/docs/site/guides/getting-started/add-user.md new file mode 100644 index 000000000..8a7cca86e --- /dev/null +++ b/docs/site/guides/getting-started/add-user.md @@ -0,0 +1,127 @@ +# How to add users + +!!! Note "Under construction" + +The users concept of clan is not done yet. This guide outlines some solutions from our community. +Defining users can be done in many different ways. We want to highlight two approaches: + +- Using clan's [users](../../reference/clanServices/users.md) service. +- Using a custom approach. + +## Adding Users using the [users](../../reference/clanServices/users.md) service + +To add a first *user* this guide will be leveraging two things: + +- [clanServices](../../reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `Γ¬nstance`. +- [clanServices/users](../../reference/clanServices/users.md): Implements logic for adding a single user perInstance. + +The example shows how to add a user called `jon`: + +```{.nix title="clan.nix" hl_lines="7-21"} +{ + inventory.machines = { + jon = { }; + sara = { }; + }; + inventory.instances = { + jon-user = { # (1) + module.name = "users"; + + roles.default.tags.all = { }; # (2) + + roles.default.settings = { + user = "jon"; # (3) + groups = [ + "wheel" + "networkmanager" + "video" + "input" + ]; + }; + }; + # ... + # elided + }; +} +``` + +1. Add `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment. +2. Add this user to `all` machines +3. Define the `name` of the user to be `jon` + +The `users` service creates a `/home/jon` directory, allows `jon` to sign in and will take care of the users password as part of [deployment](./deploy.md). + +For more information see [clanService/users](../../reference/clanServices/users.md) + +## Using a custom approach + +Some people like to define a `users` folder in their repository root. +That allows to bind all user specific logic to a single place (`default.nix`) +Which can be imported into individual machines to make the user avilable on that machine. + +```bash +. +β”œβ”€β”€ machines +β”‚Β Β  β”œβ”€β”€ jon +# ...... +β”œβ”€β”€ users +β”‚Β Β  β”œβ”€β”€ jon +β”‚ β”‚ └── default.nix # <- a NixOS module; sets some options +# ... ... ... +``` + +## using [home-manager](https://github.com/nix-community/home-manager) + +When using clan's `users` service it is possible to define extraModules. +In fact this is always possible when using clan's services. + +We can use this property of clan services to bind a nixosModule to the user, which configures home-manager. + +```{.nix title="clan.nix" hl_lines="22"} +{ + inventory.machines = { + jon = { }; + sara = { }; + }; + inventory.instances = { + jon-user = { + module.name = "users"; + + roles.default.tags.all = { }; + + roles.default.settings = { + user = "jon", + groups = [ + "wheel" + "networkmanager" + "video" + "input" + ]; + }; + + roles.default.extraModules = [ ./users/jon/home.nix ]; # (1) + }; + # ... + # elided + }; +} +``` + +1. Type `path` or `string`: Must point to a seperate file. Inlining a module is not possible + +!!! Note "This is inspiration" + Our community might come up with better solutions soon. + We are seeking contributions to improve this pattern if you have a nicer solution in mind. + +```nix title="users/jon/home.nix" +# NixOS module to import home-manager and the home-manager configuration of 'jon' +{ self, ...}: +{ + imports = [ self.inputs.home-manager.nixosModules.default ]; + home-manager.users.jon = { + imports = [ + ./home-configuration.nix + ]; + }; +} +``` diff --git a/docs/site/guides/getting-started/index.md b/docs/site/guides/getting-started/index.md index 8554c6c56..783fcd79b 100644 --- a/docs/site/guides/getting-started/index.md +++ b/docs/site/guides/getting-started/index.md @@ -128,6 +128,7 @@ You can continue with **any** of the following steps at your own pace: - [x] [Initialize Clan](./index.md#initialize-your-project) - [ ] [Create USB Installer (optional)](./installer.md) - [ ] [Add Machines](./add-machines.md) +- [ ] [Add a User](./add-user.md) - [ ] [Add Services](./add-services.md) - [ ] [Configure Secrets](./secrets.md) - [ ] [Deploy](./deploy.md) - Requires configured secrets