more complete example

README.md

@@ -1,8 +1,8 @@
-# Nix Starter Config (Minimal version)
+# Nix Starter Config (Full version)
 
 This is a simple nix flake for getting started with NixOS + home-manager.
 
-[**Looking for the full version?**](https://github.com/Misterio77/nix-starter-config/tree/main)
+**[Looking for the minimal version?](https://github.com/Misterio77/nix-starter-config/tree/minimal)**
 
 # What this provides
 
@@ -10,6 +10,11 @@ This is a simple nix flake for getting started with NixOS + home-manager.
   `nixos-rebuild --flake .`
 - Home-manager configuration on `home-manager/home.nix`, accessible via
   `home-manager --flake .`
+- Basic boilerplate for adding custom packages (under `pkgs`) and overlays
+  (under `overlay`). Accessible on your system, home config, as well as `nix
+  build .#package-name`
+- Boilerplate for custom NixOS (`modules/nixos`) and home-manager
+  (`modules/home-manager`) modules
 
 # Getting started
 
@@ -17,6 +22,19 @@ Assuming you have a basic NixOS booted up (either live or installed, anything
 works). [Here's a link to the latest NixOS downloads, just for
 you](https://nixos.org/download#download-nixos).
 
+## I like your funny words, magic man
+
+Not sure what this all means?
+
+Take a look at [the learn hub on the NixOS
+website](https://nixos.org/learn.html) (scroll down to guides, the manuals, and
+the other awesome learning resources).
+
+Learning the basics of what Nix (the package manager) is, how the Nix language
+works, and a bit of NixOS basics should get you up and running. Don't worry if
+it seems a little confusing at first. Get confortable with the basic concepts
+and come back here to get your feet wet, it's the best way to learn!
+
 ## The repo
 
 - [Install git](https://nixos.wiki/wiki/git)
@@ -42,11 +60,11 @@ you](https://nixos.org/download#download-nixos).
 
 ## Bootstrapping
 
-To get everything up and running, you need flake-enabled nix and/or home-manager.
+To get everything up and running, you need flake-enabled nix and/or
+home-manager.
 
-For simplicity, this minimal version does not include a bootstrap shell.
+Simple, just run `nix develop` (if you've already enabled flakes) or
-
+`nix-shell`. You should be good to go now.
-Check the [NixOS wiki](https://nixos.wiki/wiki/Flakes) for information on how to enable flakes.
 
 ## Usage
 
@@ -57,10 +75,121 @@ Check the [NixOS wiki](https://nixos.wiki/wiki/Flakes) for information on how to
 - Run `home-manager switch --flake .#username@hostname` to apply your home
   configuration.
 
+And that's it, really! You're ready to have fun with your configurations using
+the latest and greatest nix3 flake-enabled command UX.
+
 # What next?
 
-## Full version
+## User password and secrets
 
-Once you're confortable with this flake, take a look at the [full
+You have basically two ways of setting up default passwords:
-version](https://github.com/Misterio77/nix-starter-config/tree/main), it includes
+- By default, you'll be prompted for a root password when installing with
-boilerplate for overlays, custom packages, and more.
+  `nixos-install`. After you reboot, be sure to add a password to your own
+  account and lock root using `sudo passwd -l root`.
+- Alternatively, you can specify `initialPassword` for your user. This will
+  give your account a default password, be sure to change it after rebooting!
+  If you do, you should pass `--no-root-passwd` to `nixos-install`, to skip
+  setting a password on the root account.
+
+If you don't want to set your password imperatively, you can also use
+`passwordFile` for safely and declaratively setting a password from a file
+outside the nix store.
+
+There's also [more advanced options for secret
+management](https://nixos.wiki/wiki/Comparison_of_secret_managing_schemes),
+including some that can include them (encrypted) into your config repo and/or
+nix store, be sure to check them out if you're interested.
+
+## Dotfile management with home-manager
+
+Besides just adding packages to your environment, home-manager can also manage
+your dotfiles. I strongly recommend you do, it's awesome!
+
+For full nix goodness, check out the home-manager options with `man
+home-configuration.nix`. Using them, you'll be able to fully configure any
+program with nix syntax and its powerful abstractions.
+
+Alternatively, if you're still not ready to rewrite all your configs to nix
+syntax, there's home-manager options (such as `xdg.configFile`) for including
+files from your config repository into your usual dot directories. Add your
+existing dotfiles to this repo and try it out!
+
+## Try opt-in persistance
+
+You might have noticed that there's impurity in your NixOS system, in the form
+of configuration files and other cruft your system generates when running. What
+if you change them in a whim to get something working and forget about it?
+Boom, your system is not fully reproductible anymore.
+
+You can instead fully delete your `/` and `/home` on every boot! Nix is okay
+with a empty root on boot (all you need is `/boot` and `/nix`), and will
+happily reapply your configurations.
+
+There's two main approaches to this: mount a `tmpfs` (RAM disk) to `/`, or
+(using a filesystem such as btrfs or zfs) mount a blank snapshot and reset it
+on boot.
+
+For stuff that can't be managed through nix (such as games downloaded from
+steam, or logs), use [impermanence](https://github.com/nix-community/impermanence)
+for mounting stuff you to keep to a separate partition/volume (such as
+`/nix/persist` or `/persist`). This makes everything vanish by default, and you
+can keep track of what you specifically asked to be kept.
+
+Here's some awesome blog posts about it:
+- [Erase your darlings](https://grahamc.com/blog/erase-your-darlings)
+- [Encrypted BTRFS with Opt-In State on
+  NixOS](https://mt-caret.github.io/blog/posts/2020-06-29-optin-state.html)
+- [NixOS: tmpfs as root](https://elis.nu/blog/2020/05/nixos-tmpfs-as-root/) and
+  [tmpfs as home](https://elis.nu/blog/2020/06/nixos-tmpfs-as-home/)
+
+## Adding custom packages
+
+Something you want to use that's not in nixpkgs yet? You can easily build and
+iterate on a derivation (package) from this very repository.
+
+Create a folder with the desired name inside `pkgs`, and add a `default.nix`
+file containing a derivation. Be sure to also `callPackage` them on
+`pkgs/default.nix`.
+
+You'll be able to refer to that package from anywhere on your
+home-manager/nixos configurations, build them with `nix build .#package-name`,
+or bring them into your shell with `nix shell .#package-name`.
+
+See [the manual](https://nixos.org/manual/nixpkgs/stable/) for some tips on how
+to package stuff.
+
+## Adding overlays
+
+Found some outdated package on nixpkgs you need the latest version of? Perhaps
+you want to apply a patch to fix a behaviour you don't like? Nix makes it easy
+and manageble with overlays!
+
+Use the `overlay/default.nix` file for this.
+
+If you're creating patches, you can keep them on the `overlay` folder as well.
+
+See [the wiki article](https://nixos.wiki/wiki/Overlays) to see how it all
+works.
+
+## Adding your own modules
+
+Got some configurations you want to create an abstraction of? Modules are the
+answer. These awesome files can expose _options_ and implement _configurations_
+based on how the options are set.
+
+Create a file for them on either `modules/nixos` or `modules/home-manager`. Be
+sure to also add them to the listing at `modules/nixos/default.nix` or
+`modules/home-manager/default.nix`.
+
+See [the wiki article](https://nixos.wiki/wiki/Module) to learn more about
+them.
+
+## Adding more hosts or users
+
+You can organize them by hostname and username on `nixos` and `home-manager`
+directories, be sure to also add them to `flake.nix`.
+
+NixOS makes it easy to share common configuration between hosts (you might want
+to create a common directory for these), while keeping everything in sync.
+home-manager can help you sync your environment (from editor to WM and
+everything in between) anywhere you use it. Have fun!

flake.nix

@@ -13,13 +13,55 @@
     # TODO: Add any other flake you might need
   };
 
-  outputs = { nixpkgs, home-manager, ... }@inputs: {
+  outputs = { nixpkgs, home-manager, ... }@inputs:
+    let
+      forAllSystems = nixpkgs.lib.genAttrs systems;
+      systems = [
+        "aarch64-linux"
+        "i686-linux"
+        "x86_64-linux"
+        "aarch64-darwin"
+        "x86_64-darwin"
+      ];
+    in
+    rec {
+      # Your custom packages and modifications
+      overlays = {
+        default = import ./overlay { inherit inputs; };
+      };
+
+      # Reusable nixos modules you might want to export
+      # These are usually stuff you would upstream into nixpkgs
+      nixosModules = import ./modules/nixos;
+      # Reusable home-manager modules you might want to export
+      # These are usually stuff you would upstream into home-manager
+      homeManagerModules = import ./modules/home-manager;
+
+      # Devshell for bootstrapping
+      # Acessible through 'nix develop' or 'nix-shell' (legacy)
+      devShells = forAllSystems (system: {
+        default = legacyPackages.${system}.callPackage ./shell.nix { };
+      });
+
+      # Reexport nixpkgs with our overlays applied
+      # Acessible on our configurations, and through nix build, shell, run, etc.
+      legacyPackages = forAllSystems (system:
+        import inputs.nixpkgs {
+          inherit system;
+          overlays = builtins.attrValues overlays;
+        }
+      );
+
       nixosConfigurations = {
         # FIXME replace with your hostname
         your-hostname = nixpkgs.lib.nixosSystem {
-        pkgs = nixpkgs.legacyPackages.x86_64-linux;
+          pkgs = legacyPackages.x86_64-linux;
+
+          modules = [
+            # > Our main nixos configuration file <
+            ./nixos/configuration.nix
+          ] ++ (builtins.attrValues nixosModules); # Import our reusable nixos modules
 
-        modules = [ ./nixos/configuration.nix ];
           # Pass inputs down to our config, so that they can consume flake inputs
           specialArgs = { inherit inputs; };
         };
@@ -28,9 +70,14 @@
       homeConfigurations = {
         # FIXME replace with your username@hostname
         "your-name@your-hostname" = home-manager.lib.homeManagerConfiguration {
-        pkgs = nixpkgs.legacyPackages.x86_64-linux;
+          pkgs = legacyPackages.x86_64-linux;
+
+          modules = [
+            # > Our main home-manager configuration file <
+            ./home-manager/home.nix
+            # Import our reusable home-manager modules
+          ] ++ (builtins.attrValues homeManagerModules); # Import our reusable home-manager modules
 
-        modules = [ ./home-manager/home.nix ];
           # Pass inputs down to our config, so that they can consume flake inputs
           extraSpecialArgs = { inherit inputs; };
         };

modules/home-manager/default.nix

@@ -0,0 +1,7 @@
+# Add your reusable home-manager modules to this directory, on their own file (https://nixos.wiki/wiki/Module).
+# These should be stuff you would like to share with others, not your personal configurations.
+
+{
+  # List your module files here
+  # my-module = import ./my-module.nix;
+}

modules/nixos/default.nix

@@ -0,0 +1,7 @@
+# Add your reusable NixOS modules to this directory, on their own file (https://nixos.wiki/wiki/Module).
+# These should be stuff you would like to share with others, not your personal configurations.
+
+{
+  # List your module files here
+  # my-module = import ./my-module.nix;
+}

overlay/default.nix

@@ -0,0 +1,16 @@
+# This file defines two overlays and composes them
+{ inputs, ... }:
+let
+  # This one brings our custom packages from the 'pkgs' directory
+  additions = final: _prev: import ../pkgs { pkgs = final; };
+
+  # This one contains whatever you want to overlay
+  # You can change versions, add patches, set compilation flags, anything really.
+  # https://nixos.wiki/wiki/Overlays
+  modifications = final: prev: {
+    # example = prev.example.overrideAttrs (oldAttrs: rec {
+    # ...
+    # });
+  };
+in
+inputs.nixpkgs.lib.composeManyExtensions [ additions modifications ]

pkgs/default.nix

@@ -0,0 +1,5 @@
+# When you add custom packages, list them here
+# These are similar to nixpkgs packages
+{ pkgs }: {
+  # example = pkgs.callPackage ./example { };
+}

shell.nix

@@ -0,0 +1,18 @@
+# Shell for bootstrapping flake-enabled nix and home-manager
+{ pkgs ? let
+    # If pkgs is not defined, instanciate nixpkgs from locked commit
+    lock = (builtins.fromJSON (builtins.readFile ./flake.lock)).nodes.nixpkgs.locked;
+    nixpkgs = fetchTarball {
+      url = "https://github.com/nixos/nixpkgs/archive/${lock.rev}.tar.gz";
+      sha256 = lock.narHash;
+    };
+    system = builtins.currentSystem;
+    overlays = [ ]; # Explicit blank overlay to avoid interference
+  in
+  import nixpkgs { inherit system overlays; }
+, ...
+}: pkgs.mkShell {
+  # Enable experimental features without having to specify the argument
+  NIX_CONFIG = "experimental-features = nix-command flakes";
+  nativeBuildInputs = with pkgs; [ nix home-manager git ];
+}