DOC.md: split off from README.md

Keep the README.md lean and use DOC.md for more detailed explanations. While
revising user documentation, a default `nixos` user profile was created, which
serves as a goood base example.

DOC.md

@@ -0,0 +1,99 @@
+## Hosts
+Module declarations dependant on particular machines should be stored in the
+[hosts](hosts) directory. Every file in this directory will be added automatically
+to the the `nixosConfigurations` flake output and thus becomes deployable via
+`nixos-rebuild` and `rebuild`.
+
+See [`hosts/default.nix`](hosts/default.nix) for the implementation.
+
+## Profiles
+A profile is any directory under [profiles](profiles) containing a `default.nix`
+defining a valid NixOS module, with the added restriction that no new
+delclarations to the `options` _or_ `config` attributes are allowed
+(use [modules](modules) instead). Their purpose is to provide abstract
+expressions suitable for reuse by multiple deployments. They are perhaps _the_
+key mechanism by which we keep this repo maintainable.
+
+Profiles can have subprofiles which are themselves just profiles that live under
+another. There's no hard rule that everything in the folder must be imported by
+its `default.nix`, so you can also store relevant code that is useful but not
+wanted by default in, say, an `alt.nix`. Importantly, every subdirectory in a
+profile should be independent of its parent. i.e:
+
+```nix
+{
+  # importing `profile` without implicitly importing `some`
+  imports = [ ./profiles/some/profile ];
+}
+```
+
+It is okay for profiles to depend on other profiles so long as they are
+explicitly loaded via `imports`.
+
+Optionally, you may choose to export your profiles via the flake output. If
+you include it in the list defined in [profiles/list.nix](profiles/list.nix),
+it will be available to other flakes via `nixosModules.profiles`.
+
+## Users
+User declarations belong in the `users` directory.
+
+These are actually just a special case of [profiles](#profiles) attached to
+a particular interactive user. Its primarily for declarations to
+`users.users.<new-user>` where `<new-user>.isNormalUser` is true.
+
+This is a convenient place to import your profiles such that a particular user
+always has a reliable stack.
+
+For convenience, [home-manager][home-manager] is available automatically for
+home directory setup and should only be used from this directory.
+
+## Lib
+The [lib](lib) directory contains a file `utils.nix` which is an attribute set
+meant to consist mainly of utility functions you might want to write and use
+throughout the configuration. They are available via a new `usr` attribute
+passed to every NixOS module, eg:
+
+```
+# hosts/some-host.nix
+{ usr, ... }:
+let
+  inherit (usr) utils;
+
+  data = utils.myFunction # ...
+in
+{
+  # NixOS configuration
+}
+```
+
+## Secrets
+Anything you wish to keep encrypted goes in the `secrets` directory, which is
+created on first entering a `nix-shell`.
+
+Be sure to run `git crypt init`, before committing anything to this directory.
+Be sure to check out git-crypt's [documentation](https://github.com/AGWA/git-crypt)
+if your not familiar. The filter is already set up to encrypt everything in this
+folder by default.
+
+To keep [profiles](profiles) reusable across configurations, secrets should
+only be imported from the `users` or [`hosts`](hosts) directory.
+
+## Modules, Packages and Overlays
+All expressions in both [modules/list.nix](modules/list.nix) and
+[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the
+repo. They are additionally included in the `nixosModules` and `overlay` flake
+outputs, respectively. Packages can manually be added to [flake.nix](flake.nix)
+for inclusion in the `packages` output as well.
+
+The directory structure is identical to nixpkgs to provide a kind of staging area
+for any modules or packages we might be wanting to merge there later. If your not
+familiar or can't be bothered, simply dropping a valid nix file and pointing the
+`default.nix` to it, is all that's really required.
+
+As for overlays, they should be defined in the [overlays](overlays) directory.
+They will be automatically pulled in for use by all configurations. Nix command
+line tools will be able to read overlays from here as well since it is set as
+`nixpkgs-overlays` in `NIX_PATH`. And of course they will be exported via the
+flake output `overlays` as well.
+
+[home-manager]: https://github.com/rycee/home-manager

README.md

@@ -3,8 +3,9 @@ A NixOS configuration template using the experimental [flakes][rfc] mechanism.
 Its aim is to provide a generic repository which neatly separates concerns
 and allows one to get up and running with NixOS faster than ever.
 
-Flakes are still an experimental feature, but once they finally get merged
+Please be advised, flakes are still an experimental feature.
-even more will become possible, i.e. [nixops](https://nixos.org/nixops)
+Presuming they get [merged][rfc], even more will become possible, e.g.
+[nixops](https://nixos.org/nixops)/[disnix](https://nixos.org/disnix)
 support.
 
 #### Flake Talk:
@@ -22,6 +23,9 @@ nix-shell
 
 git checkout -b $new_branch template
 
+# set a root password, preferably with `hashedPassword`
+$EDITOR ./users/root/default.nix
+
 # generate hardware config
 nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
 
@@ -35,7 +39,6 @@ nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
 # any ./profiles you may wish to try out.
 $EDITOR ./hosts/${new_host}.nix
 
-
 # backup existing config and ensure configuration lives in expected location
 mv /etc/nixos /etc/nixos.old
 ln -s $PWD /etc/nixos
@@ -52,15 +55,13 @@ git add ./hosts/${new_host}.nix
 # This will be run as root.
 rebuild $new_host switch
 
+# you may wish to start by creating a user
+mkdir users/new-user && $EDITOR users/new-user/default.nix
 ```
 
+Best to read the [doc](DOC.md), in order to understand the impetus behind
+the directory structure.
 
-And now you should be ready to start writing your nix configuration or import
-your current one. Review the [structure](#structure) below on how to build your
-layout. And be sure to update the [locale.nix](local/locale.nix) for your
-region.
-
-You can always checkout my personal branch for more concrete examples.
 
 ## Additional Capabilities
 
@@ -72,7 +73,8 @@ rebuild iso
 nix profile install ".#packages.x86_64-linux.myPackage"
 ```
 
-this flake exports multiple outputs for use in other flakes:
+this flake exports multiple outputs for use in other flakes, or forks
+of this one:
 ```nix
 # external flake.nix
 {
@@ -95,102 +97,13 @@ this flake exports multiple outputs for use in other flakes:
 
 ```
 
-# Structure
+### NUR usage
 
-The structure is here to keep things simple and clean. Anything sufficiently
+You can use packages, modules and overlays from the
-generic can ultimately be exported for use in other flakes without getting
+[Nix User Repository][nur].
-tied up in user concerns. As an added bonus, one can now trivially swap or
-combine [profiles](#profiles), creating a custom config in mere moments.
 
-## Hosts
+Since NUR packages are completely unchecked, they are not included by default.
-Distributions for particular machines should be stored in the [hosts](hosts)
+Check out the NUR [branch](https://github.com/nrdxp/nixflk/tree/NUR) for usage.
-directory. Every file in this directory will be added automatically to the
-the `nixosConfigurations` flake output and thus becomes deployable. See the
-[`default.nix`](hosts/default.nix) for the implementation details.
-
-## Profiles
-A profile is any directory under [profiles](profiles) containing a `default.nix`
-defining a valid NixOS module, with the added restriction that no new
-delclarations to the `options` _or_ `config` attributes are allowed
-(use [modules](modules) instead). Their purpose is to provide abstract
-expressions suitable for reuse by multiple deployments. They are perhaps _the_
-key mechanism by which we keep this repo maintainable.
-
-Profiles can have subprofiles which are themselves just profiles that live under
-another. There's no hard rule that everything in the folder must be imported by
-its `default.nix`, so you can also store relevant code that is useful but not
-wanted by default in, say, an `alt.nix`.  Importantly, every subdirectory in a
-profile should be independent of its parent.
-
-For example, a zsh directory lives under [profiles/develop](profiles/develop/zsh).
-It's self contained to allow inclusion without the whole of
-[develop](profiles/develop) if one so wished. This provides a wonderful level of
-granularity and control. Put simply: take the best, leave the rest.
-
-In addition, profiles can depend on other profiles. For instance, the
-[graphical](profiles/graphical) profile depends on [develop](profiles/develop)
-simply by importing it. This is to ensure my terminal configuration is always
-available from within a graphical session.
-
-Optionally, you may choose to export your profiles via the flake output. If
-you include it in the list defined in [profiles/default.nix](profiles/default.nix),
-it will be available to other flakes via `nixosModules.profiles`.
-
-## Users
-User declarations belong in the `users` directory, created on entering `nix-shell`.
-These are actually just a special case of [profiles](#profiles). Any profile that
-makes a declaration defining, or referencing a specific interactive user or uid
-belongs in  here. That way profiles stay general, and all our idiosyncratic data
-has a clean home.
-
-For convenience, [home-manager][home-manager] is available automatically for
-home directory setup and should only be used from this directory.
-
-## Lib
-The [lib](lib) directory contains a file `utils.nix` which is an attribute set
-meant to consist mainly of utility functions you might want to write and use
-throughout the configuration. They are available via a new `usr` attribute
-passed to every NixOS module, eg:
-
-```
-# hosts/some-host.nix
-{ usr, ... }:
-let data = usr.myFunction # ...
-in
-{
-  # NixOS configuration
-}
-```
-
-## Secrets
-Anything you wish to keep encrypted goes in the `secrets` directory, which is
-created on first entering a `nix-shell`.
-
-Be sure to run `git crypt init`, before committing anything to this directory.
-Be sure to check out git-crypt's [documentation](https://github.com/AGWA/git-crypt)
-if your not familiar. The filter is already set up to encrypt everything in this
-folder by default.
-
-To keep [profiles](profiles) reusable across configurations, secrets should
-only be imported from the `users` or [`hosts`](hosts) directory.
-
-## Modules, Packages and Overlays
-All expressions in both [modules/default.nix](modules/default.nix) and
-[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the
-repo. They are additionally included in the `nixosModules` and `overlay` flake
-outputs, respectively. Packages can manually be added to [flake.nix](flake.nix)
-for inclusion in the `packages` output as well.
-
-The directory structure is identical to nixpkgs to provide a kind of staging area
-for any modules or packages we might be wanting to merge there later. If your not
-familiar or can't be bothered, simply dropping a valid nix file and pointing the
-`default.nix` to it, is all that's really required.
-
-As for overlays, they should be defined in the [overlays](overlays) directory.
-They will be automatically pulled in for use by all configurations. Nix command
-line tools will be able to read overlays from here as well since it is set as
-`nixpkgs-overlays` in `NIX_PATH`. And of course they will be exported via the
-flake output `overlays` as well.
 
 # License
 
@@ -204,8 +117,8 @@ which they apply. The aforementioned artifacts are all covered by the
 licenses of the respective packages.
 
 [direnv]: https://direnv.net
-[home-manager]: https://github.com/rycee/home-manager
 [NixOS]: https://nixos.org
+[nur]: https://github.com/nix-community/NUR
 [old]: https://github.com/nrdxp/nixos
 [pr]:  https://github.com/NixOS/nixpkgs/pull/68897
 [rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md

hosts/NixOS.nix

@@ -1,10 +1,9 @@
 {
-  imports = [ ];
+  ### root password is empty by default ###
+  imports = [ ../users/nixos ../users/root ];
 
-  # Use the systemd-boot EFI boot loader.
   boot.loader.systemd-boot.enable = true;
   boot.loader.efi.canTouchEfiVariables = true;
 
   networking.networkmanager.enable = true;
-  users.users.root.password = "";
 }

hosts/default.nix

@@ -1,38 +1,44 @@
 args@{ home, nixpkgs, self, ... }:
 let
-  utils = import ../lib/utils.nix { lib = nixpkgs.lib; };
+  inherit (nixpkgs) lib;
+
+  utils = import ../lib/utils.nix { inherit lib; };
 
   inherit (utils) recImport;
 
   inherit (builtins) attrValues removeAttrs;
 
-  config = this:
+  config = hostName:
-    nixpkgs.lib.nixosSystem rec {
+    lib.nixosSystem rec {
       system = "x86_64-linux";
 
-      specialArgs.usr = utils;
+      specialArgs.usr = { inherit utils; };
 
       modules = let
+        inherit (home.nixosModules) home-manager;
+
         core = ../profiles/core.nix;
 
         global = {
-          networking.hostName = this;
+          networking.hostName = hostName;
           nix.nixPath = [
             "nixpkgs=${nixpkgs}"
             "nixos-config=/etc/nixos/configuration.nix"
             "nixpkgs-overlays=/etc/nixos/overlays"
           ];
+
           system.configurationRevision = self.rev;
 
           nixpkgs.overlays = self.overlays;
         };
 
-        local = import "${toString ./.}/${this}.nix";
+        local = import "${toString ./.}/${hostName}.nix";
 
-        flakeModules = removeAttrs self.nixosModules [ "profiles" ];
+        # Everything in `./modules/list.nix`.
+        flakeModules =
+          attrValues (removeAttrs self.nixosModules [ "profiles" ]);
 
-      in attrValues flakeModules
+      in flakeModules ++ [ core global local home-manager ];
-      ++ [ core global local home.nixosModules.home-manager ];
 
     };
 

shell.nix

@@ -20,7 +20,6 @@ in pkgs.mkShell {
 
   shellHook = ''
     mkdir -p secrets
-    mkdir -p users
   '';
 
   NIX_CONF_DIR = let

users/nixos/default.nix

@@ -0,0 +1,16 @@
+{
+  imports = [ ../../profiles/develop ];
+
+  users.users.nixos = {
+    uid = 1000;
+    password = "nixos";
+    description = "default";
+    isNormalUser = true;
+    extraGroups = [ "wheel" ];
+  };
+
+  # to avoid zsh startup message
+  home-manager.users.nrd.home.file.".zshrc" = ''
+    #
+  '';
+}

users/root/default.nix

@@ -0,0 +1,4 @@
+# recommend using `hashedPassword`
+{
+  users.users.root.password = "";
+}