From e078e7a22943d6ba1bc3a72da212cc2d6182df45 Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Fri, 10 Jan 2020 23:49:18 -0700 Subject: [PATCH] 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 | 99 ++++++++++++++++++++++++++++++++ README.md | 123 ++++++---------------------------------- hosts/NixOS.nix | 5 +- hosts/default.nix | 24 +++++--- shell.nix | 1 - users/nixos/default.nix | 16 ++++++ users/root/default.nix | 4 ++ 7 files changed, 154 insertions(+), 118 deletions(-) create mode 100644 DOC.md create mode 100644 users/nixos/default.nix create mode 100644 users/root/default.nix diff --git a/DOC.md b/DOC.md new file mode 100644 index 0000000..ef13c84 --- /dev/null +++ b/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.` where `.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 diff --git a/README.md b/README.md index f7ff5fd..40707b4 100644 --- a/README.md +++ b/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 -even more will become possible, i.e. [nixops](https://nixos.org/nixops) +Please be advised, flakes are still an experimental feature. +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 -generic can ultimately be exported for use in other flakes without getting -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. +You can use packages, modules and overlays from the +[Nix User Repository][nur]. -## Hosts -Distributions for 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. 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. +Since NUR packages are completely unchecked, they are not included by default. +Check out the NUR [branch](https://github.com/nrdxp/nixflk/tree/NUR) for usage. # 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 diff --git a/hosts/NixOS.nix b/hosts/NixOS.nix index c933bcb..f6e0cb3 100644 --- a/hosts/NixOS.nix +++ b/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 = ""; } diff --git a/hosts/default.nix b/hosts/default.nix index 0ecedae..53d4d83 100644 --- a/hosts/default.nix +++ b/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: - nixpkgs.lib.nixosSystem rec { + config = hostName: + 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 - ++ [ core global local home.nixosModules.home-manager ]; + in flakeModules ++ [ core global local home-manager ]; }; diff --git a/shell.nix b/shell.nix index a8af3c7..0d51f61 100644 --- a/shell.nix +++ b/shell.nix @@ -20,7 +20,6 @@ in pkgs.mkShell { shellHook = '' mkdir -p secrets - mkdir -p users ''; NIX_CONF_DIR = let diff --git a/users/nixos/default.nix b/users/nixos/default.nix new file mode 100644 index 0000000..9ce867a --- /dev/null +++ b/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" = '' + # + ''; +} diff --git a/users/root/default.nix b/users/root/default.nix new file mode 100644 index 0000000..9ca9d34 --- /dev/null +++ b/users/root/default.nix @@ -0,0 +1,4 @@ +# recommend using `hashedPassword` +{ + users.users.root.password = ""; +}