From 9eac509b2674d4662bc9ec5d53808b57535ca8e7 Mon Sep 17 00:00:00 2001 From: Gabriel Arazas Date: Tue, 21 Dec 2021 14:29:27 +0800 Subject: [PATCH] Update documentation --- README.adoc | 4 ++- hosts/README.adoc | 35 +++++++++++++++++++++--- modules/README.adoc | 6 ++--- users/README.adoc | 66 +++++++++++++++------------------------------ 4 files changed, 60 insertions(+), 51 deletions(-) diff --git a/README.adoc b/README.adoc index d30a7003..a31bd625 100644 --- a/README.adoc +++ b/README.adoc @@ -3,7 +3,7 @@ This is my NixOS config as a link:https://www.tweag.io/blog/2020-05-25-flakes/[Nix flake]. -I finally have some time trying to grok flakes and redo my NixOS config from scratch after leaving NixOs (because I have work and have to quickly set things up without me trying to debug how NixOS works). +I finally have some time trying to grok flakes and redo my NixOS config from scratch after leaving it for some time (because I have work and have to quickly set things up without me trying to debug how NixOS works). Here is the result. @@ -11,6 +11,8 @@ Here is the result. == Installation +Since this uses Nix flakes, you should have Nix v2.4 and above installed. + This primarily uses Nix flakes so you can have a preview of what's available in my config. [source, shell] diff --git a/hosts/README.adoc b/hosts/README.adoc index a1397646..cf164844 100644 --- a/hosts/README.adoc +++ b/hosts/README.adoc @@ -1,12 +1,41 @@ = Host-specific configuration :toc: -These are configurations that are specific to a machine (e.g., desktop, servers, VM, containers). +These are NixOS configurations that are specific to a machine (e.g., desktop, servers, VM, containers). Ideally, it should be made minimal as much as possible considering you also have to manage your users. + + + +== Integrating with custom modules + +The host configurations placed here most likely use the link:../modules/nixos[custom NixOS modules]. +The custom modules shouldn't be imported manually from the host. +In the case for our link:../flake.nix[flake configuration], the importing of modules are already taken care of — specifically through `mkHost` from link:../lib/flake-utils[`../lib/flake-utils`] (see the linked file for the implementation). + +It is best practice to assume the host configurations make use of the link:../modules/nixos[custom NixOS modules], link:../pkgs[custom packages], and the flake inputs. +In other words, always pay attention to link:../flake.nix[`../flake.nix`]. + + + + +== User management + For managing users, there are multiple ways to manage them with this config: * The usual `users.users.${user}` from system configuration (see `man configuration.nix.5`). -* Modularize them (see link:../users/README.adoc[User-specific configuration] for more information). -If you have user-specific configs in set, you have to manage them with link:../modules/users.nix[`modules.users.users`] which is my implementation of managing users (e.g., `modules.users.users = [ "foo-dogsquared" ]`). +* If you intend to import users from the link:../users/nixos/[`../users/nixos/`], you can simply import them through `imports` in the system module. ++ +For a convenient option, there is the function `getUsers` defined from the link:../lib[custom library]. +You can use it as follows: ++ +[source, nix] +---- +imports = [ # Your modules ] + # Import the following NixOS users. + ++ (lib.attrValues (lib.getUsers "nixos" [ "foo-dogsquared" "polski" ])); +---- + +* link:../modules/users.nix[`modules.users.users.${user}`] which is my implementation for managing users from link:../users/home-manager/[`../users/home-manager/`] — e.g., `modules.users.users.foo-dogsquared = {}`. +This is integrating my home-manager users to map into NixOS users. diff --git a/modules/README.adoc b/modules/README.adoc index 6746f8ed..75e5e3ad 100644 --- a/modules/README.adoc +++ b/modules/README.adoc @@ -6,11 +6,11 @@ These are various modules ranging from link:https://nixos.org/manual/nixos/stabl The modules are imported usually through `lib.filesToAttr`, allowing for easier structuring without modifying the index file of each module (i.e., `default.nix`). (See the implementation for more details.) -For example, take the following module folder structure... +For example, take the following module folder structure of the link:./nixos/[custom NixOS modules]... [source, tree] ---- -modules/ +nixos/ ├── themes/ │   ├── a-happy-gnome/ │   │   ├── default.nix @@ -30,7 +30,7 @@ modules/ └── users.nix ---- -...should have the following attribute set. +...where it should have the equivalent attribute set. [source, nix] ---- diff --git a/users/README.adoc b/users/README.adoc index 1120b07d..1eaabf1a 100644 --- a/users/README.adoc +++ b/users/README.adoc @@ -1,54 +1,32 @@ -= Users configuration += User-specific configuration :toc: This is where user-specific configurations comes in. -Ideally, the configurations are link:https://nix-community.github.io/home-manager/[home-manager config]. -The configs should assume to be used as a configuration as `.config/nixpkgs/home.nix` (i.e., `home-manager.lib.homeManagerConfiguration`, `home-manager.users.${user}`, in your ordinary home-manager setup in a foreign distro). +Similar to modules, the top-level of this directory contains users for various types (e.g., home-manager, NixOS) where it contains individual users for that type. -Here's an example of a sample user config placed in `users/hello.nix`. +Take note of the following structure: -[source, nix] +[source, tree] ---- -{ config, options, pkgs, lib, ... }: - -{ - programs.home-manager.enable = true; - programs.direnv.enable = true; - home.file.".npmrc".source = ./config/npmrc; -} +users/ +├── home-manager/ +│ ├── foo-dogsquared/ +│ ├── harepoint/ +│   └── polski/ +├── nixos/ +│ ├── foo-dogsquared/ +│ ├── harepoint/ +│ ├── polski/ +│   └── vmguest/ +└── README.adoc ---- -This is to be imported to `homeManagerConfiguration` in the flake outputs and when indicated from `config.modules.users.users` (e.g., `modules.users.users = [ "hello" ];`). +It doesn't require to have users to be present for all types. +There are conventions for setting in each user type. +* For NixOS user configuration, it is expect to only have one user with their respective user-specific configuration. +This includes user-specific packages, home-manager-specific configuration (even importing them from `./home-manager` users), and so forth. +If you want to set users from the host, see link:../hosts/README.adoc[Host-specific configurations] for more details. - - -== Modules - -There are also user modules (in link:./modules[`./modules`]) that are imported to use with home-manager, allowing you to extend it as you wish. -It works just like link:https://github.com/nix-community/home-manager/tree/master/modules[home-manager modules]. - -For easier identification, it should be stored with `modules` as the top-level attribute (e.g., `modules.alacritty`, `modules.i18n`). - -Here's an example user module that simply ports my Alacritty config. - -[source, nix] ----- -{ config, options, lib, pkgs, ... }: - -let - cfg = config.modules.alacritty; -in -{ - options.modules.alacritty.enable = lib.mkEnableOption "Ports my Alacritty configuration."; - - config = lib.mkIf cfg.enable { - home.packages = with pkgs; [ alacritty ]; - xdg.configFile."alacritty" = { - source = ../config/alacritty - recursive = true; - }; - }; -} ----- - +* home-manager users are just home-manager configurations (i.e., `$XDG_CONFIG_HOME/nix/home.nix`). +That's pretty much it.