nixos-config/docs/content/en-US/03-project-specific-setup/02-declarative-user-management/index.adoc

---
title: Declarative user management
---
= Declarative user management

Similarly to xref:../02-declarative-user-management/index.adoc[Declarative host management], this project also provides a way to declare home-manager users.
The `users.toml` sits in the project root expecting certain data.
Similar to `images.toml`, it expects a table of users with each representing one of the users from github:{github-repo}[`./users/home-manager/`, path=./users/home-manager/, rev=master].
These are then included as part of `homeConfigurations` for easier installation with the standalone home-manager tool.
Of which they are then included as part of deploy nodes for deploy-rs (also for easier deployment).

Here's an example user with complete schema.

.A user with complete schema
[source, toml]
----
[foo-dogsquared]
systems = [ "x86_64-linux" ]
nixpkgs-channel = "nixos-stable"
home-manager-channel = "home-manager-23.05"
home-directory = "/home/foo-dogsquared"
username = "foodogsquared"

[foo-dogsquared.deploy]
hostname = "local.foodogsquared.one"
ssh-user = "admin"
profile = "foodogsquared"
fast-connection = true
auto-rollback = true
magic-rollback = true
remote-build = true
----

- `systems` contains a list of platforms of the home-manager user.
This is mainly used to indicate the platform used for the nixpkgs repository.
Take note if there's more than one platforms specified the home environment attribute name will change from `$HOSTNAME` to `$HOSTNAME-$SYSTEM` (e.g., `foo-dogsquared` to `foo-dogsquared-x86_64-linux`).

- `nixpkgs-channel` indicates the branch of the nixpkgs to be used.
By default, this uses the `nixpkgs` which follows the `nixos-unstable` branch.

- `home-manager-channel` contains the home-manager channel to be used.
The value should be one of the home-manager channel that is imported into this flake.
By default, it sets the home-manager channel at `home-manager` which is pointed at the unstable channel.

- `home-directory` is the associated home directory of the home-manager.
It is set for `config.home.directory` at the home-manager configuration.
By default, it will be set at `/home/$USERNAME`.

- `username` is the username of the home-manager user to be used for `config.home.username` at the home-manager configuration.
If unset, it will use the table key.
In the above example, the unset value would be `foo-dogsquared`.

- `deploy` is pretty similar to the previous configuration setting that it sets certain options for deploy-rs.