major refactor and doc update

This commit completely overhauls the documentation, uses the latest .default nix syntax, and overalls improves the usage experience

README.md

@@ -2,72 +2,187 @@
 
 This is a simple nix flake for getting started with NixOS + home-manager.
 
-## Available versions:
-- [Minimal](https://github.com/Misterio77/nix-starter-config/tree/minimal): Includes just a flake for referring to a `configuration.nix` and a `home.nix`.
-- [Medium](https://github.com/Misterio77/nix-starter-config/tree/medium): Minimal + boilerplate for custom overlays, packages, and nixos/home-manager modules.
-- [Complete](https://github.com/Misterio77/nix-starter-config/tree/complete): Medium + hosts and users are located in their own directories.
-
 ## What this provides
 
-- NixOS configuration on `configuration.nix`, accessible via `nixos-rebuild --flake`
+- NixOS configuration on `nixos/configuration.nix`, accessible via
-- Home-manager configuration on `home.nix`, accessible via `home-manager --flake`
+  `nixos-rebuild --flake`
-- Basic boilerplate for adding custom packages (under `pkgs`) and overlays (under `overlays`). Acessible on your system, home config, as well as `nix build .#package-name`
+- Home-manager configuration on `home-manager/home.nix`, accessible via
-- Boilerplate for custom NixOS (`modules/nixos`) and home-manager (`modules/home-manager`) modules
+  `home-manager --flake`
-- Dev shell for bootstrapping, accessible via `nix develop`
+- Basic boilerplate for adding custom packages (under `pkgs`) and overlays
+  (under `overlays`). Acessible 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
 
-Assuming you have a basic NixOS installation up and running:
+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)
 
 ### The repo
+
 - [Install git](https://nixos.wiki/wiki/git)
-- Clone this repo to somewhere acessible (i usually have a `/dotfiles` folder for this)
+- Clone this repo to somewhere acessible (somewhere in your home directory is
-- Add stuff you currently have on `/etc/nixos/configuration.nix` to `configuration.nix`, and `/etc/nixos/hardware-configuration.nix` to `hardware-configuration.nix`
+  good enough)
-- If you're already using home-manager, add your stuff from `~/.config/nixpkgs/home.nix` to `home.nix`
+
-- Take a look at `flake.nix`, filling out stuff marked by `TODO`s
+- Add stuff you currently have on `/etc/nixos/` to `nixos` (usually
-- Create a remote repo (github, gitlab, sr.ht, etc) and push your changes for safekeeping
+  `configuration.nix` and `hardware-configuration.nix`, when you're starting
+  out).
+    - The included file has some options you might want, specially if you don't
+      have a configuration ready. Make sure you have generated your own
+      `hardware-configuration.nix`; if not, just mount your partitions to
+      `/mnt` and run: `nixos-generate-config --root /mnt`.
+- If you're already using home-manager, add your stuff from `~/.config/nixpkgs`
+  to `home-manager` (probably `home.nix`).
+  - I also include one with some simple options if you need. Feel free to
+    ignore this step if you don't want to use home-manager just yet.
+- Take a look at `flake.nix`, making sure to fill out anything marked with
+  FIXME (required) or TODO (usually tips or optional stuff you might want)
+- Create a remote repo (github, gitlab, sr.ht, etc) and push your changes for
+  safekeeping (or at least copy your directory to somewhere safe, specially if you're on a installation medium)
 
 ### Bootstrapping
-- Run `nix develop --experimental-features "nix-command flakes"` to bootstrap into flake-enabled nix and home-manager.
+To get everything up and running, you need flake-enabled nix and home-manager.
-- Run `sudo nixos-rebuild switch --flake .` to apply system configuration
+
-- Run `home-manager switch --flake .` to apply home configuration
+First off, check your nix version using `nix --version`.
-- Reboot!
+
+#### Version < 2.4
+Bummer, your nix version does not support flakes. But fear not!
+
+You _don't_ need to mess around with channels to get up and running.
+
+Just run:
+```bash
+nix-shell
+```
+
+Wow, that was easy. Our `shell.nix` file will detect you can't evaluate (nor
+lock) the flake, and will grab `nix` and `home-manager` from the latest
+`nixos-unstable` versions, just for you.
+
+Once you're bootstrapped, remember to run `nix flake lock` and commit the
+newly-created `flake.lock` into your repository, this will make future
+bootstraps reproductible.
+
+#### Version >= 2.4
+Congrats, your nix version supports flakes! It's just hidden behind a feature flag.
+
+You can bootstrap with: 
+```bash
+nix develop .#default
+```
+
+This should generate a `flake.lock`. Remember to commit it, as this will make
+future bootstraps reproductible.
+
+### Usage
+
+- Run `sudo nixos-rebuild switch --flake .#hostname` to apply your system
+  configuration.
+    - If you're still on a live installation medium, run `nixos-install --flake
+      .#hostname` instead, and reboot. Ignore the home-manager step for now.
+- 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?
+
+### User password and secrets
+
+For people fresh from installation: Unless you used `--no-root-passwd`,
+`nixos-install` prompted you for a root password. Use it to log into the root
+account, set your own account's password imperatively with `passwd`, and
+disable root login (`sudo passwd -l root`). You can also use `--no-root-passwd`
+and instead set `initialPassword` for your user, for a temporary password upon
+install.
+
+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, 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.
+
+### Include files using 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 modules with `man
+home-configuration.nix`. Using them, you'll be able to fully configure any
+usual dotfile with nix syntax and abstractions (including your own powerful
+modules and functions).
+
+Alternatively, if you're still not ready to rewrite all your configs in nix
+syntax, there's home-manager options (such as `xdg.configFile`) for including
+files from your nix-config repository into your config 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? 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, and will happily reapply your configurations (as
+long as `/nix` is intact).
+
+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.
 
-## How to's
 
 ### Customize your NixOS configuration
 
-Use the `configuration.nix` file.
+Use the `nixos/configuration.nix` file.
 
-For a list of options, see `man configuration.nix`. Also see [the manual](https://nixos.org/manual/nixos/stable/index.html#ch-configuration).
+For a list of options, see `man configuration.nix`. Also see [the
+manual](https://nixos.org/manual/nixos/stable/index.html#ch-configuration).
 
 ### Customize your home-manager configuration
 
-Use the `home.nix` file.
+Use the `home-manager/home.nix` file.
 
-For a list of options, see `man home-configuration.nix`. Also see [the manual](https://rycee.gitlab.io/home-manager/index.html#ch-usage).
+For a list of options, see `man home-configuration.nix`. Also see [the
+manual](https://rycee.gitlab.io/home-manager/index.html#ch-usage).
 
 
 ### Adding packages
 
-Create a folder inside `pkgs`, and add a `default.nix` file containing a derivation. Be sure to also `callPackage` them on `pkgs/default.nix`.
+Create a folder with the package name inside `pkgs`, and add a `default.nix`
+file containing a derivation. Be sure to also `callPackage` them on
+`pkgs/default.nix`.
 
 See [the manual](https://nixos.org/manual/nixpkgs/stable/).
 
 ### Adding overlays
 
-Use the `overlays/default.nix` file. If it gets too big, feel free to split it up.
+Use the `overlay/default.nix` file.
 
-If you're applying patches, i recommend you keep the patches on the `overlays` folder as well.
+If you're applying patches, you can keep them on the `overlay` folder as well.
 
 See [the wiki article](https://nixos.wiki/wiki/Overlays).
 
 ### Adding your own modules
 
-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`.
+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).
 
-### Adding more hosts or users, or multiple files
+### Adding more hosts or users
-
+You can organize them by hostname and username on `nixos` and `home-manager`
-If you're starting to manage more than one host or user (or splitting up a big configuration in multiple files), you might want to create a `hosts` and/or `users` folder, and move your configs there. Be sure to change the path on `flake.nix` as well.
+directories, be sure to also add them to `flake.nix`

flake.nix

@@ -2,95 +2,95 @@
   description = "You new nix config";
 
   inputs = {
-    # Utilities for building flakes
+    # Nixpkgs
-    utils.url = "github:numtide/flake-utils";
-
-    # Core nix flakes
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-    hardware.url = "github:nixos/nixos-hardware";
 
-    # Home manager flake
+    # Home manager
     home-manager.url = "github:nix-community/home-manager";
     home-manager.inputs.nixpkgs.follows = "nixpkgs";
 
-    # Extra community flakes
+    # Utilities for building our flake
-    # Add any cool flakes you need
+    flake-utils.url = "github:numtide/flake-utils";
+
+    # Extra flakes for modules, packages, etc
+    hardware.url = "github:nixos/nixos-hardware"; # Convenience modules for hardware-specific quirks
     # nur.url = "github:nix-community/NUR";              # User contributed pkgs and modules
-    # impermanence.url = "github:riscadoa/impermanence"; # Utilities for opt-in persistance
     # nix-colors.url = "github:misterio77/nix-colors";   # Color schemes for usage with home-manager
+    # impermanence.url = "github:riscadoa/impermanence"; # Utilities for opt-in persistance
+    # TODO: Add any other flakes you need
   };
 
-  outputs = { self, nixpkgs, home-manager, utils, ... }@inputs: {
+  outputs = { nixpkgs, home-manager, flake-utils, ... }@inputs:
-    # Overlayed packages
+    let
-    overlay = (import ./overlays);
+      # Bring some functions into scope (from builtins and other flakes)
-
+      inherit (builtins) attrValues;
-    # This repo's overlay plus any other overlays you use
+      inherit (flake-utils.lib) eachSystemMap defaultSystems;
-    # If you want to use packages from flakes that are not nixpkgs (such as NUR), add their overlays here.
+      inherit (nixpkgs.lib) nixosSystem;
-    overlays = [
+      inherit (home-manager.lib) homeManagerConfiguration;
-      self.overlay
+      eachDefaultSystemMap = eachSystemMap defaultSystems;
-      # nur.overlay
+    in
-    ];
+    rec {
+      # TODO: If you want to use packages exported from other flakes, add their overlays here.
+      # They will be added to your 'pkgs'
+      overlays = {
+        default = import ./overlay; # Our own overlay
+        # nur = nur.overlay
+      };
 
       # System configurations
-    # Accessible via 'nixos-rebuild --flake'
+      # Accessible via 'nixos-rebuild'
       nixosConfigurations = {
-      # TODO: Replace with your hostname
+        # FIXME: Replace with your hostname
-      cool-computer = nixpkgs.lib.nixosSystem {
+        cool-computer = nixosSystem {
           system = "x86_64-linux";
 
           modules = [
-          ./configuration.nix
+            # >> Main NixOS configuration file <<
-          # Adds your overlay and packages to nixpkgs
+            ./nixos/configuration.nix
-          { nixpkgs.overlays = self.overlays; }
+            # Add your custom NixOS modules
-          # Adds your custom nixos modules
             ./modules/nixos
+            # Add overlays
+            { nixpkgs.overlays = attrValues overlays; }
           ];
-        # Pass our flake inputs into the config
+          # Make our inputs available to the config (for importing modules)
           specialArgs = { inherit inputs; };
         };
       };
 
       # Home configurations
-    # Accessible via 'home-manager --flake'
+      # Accessible via 'home-manager'
       homeConfigurations = {
-      # TODO: Replace with your username@hostname
+        # FIXME: Replace with your username@hostname
-      "you@cool-computer" = home-manager.lib.homeManagerConfiguration rec {
+        "you@cool-computer" = homeManagerConfiguration rec {
-        # TODO: Replace with your username
+          # FIXME: Replace with your username
           username = "you";
           homeDirectory = "/home/${username}";
           system = "x86_64-linux";
 
-        configuration = ./home.nix;
+          # >> Main home-manager configuration file <<
+          configuration = ./home-manager/home.nix;
           extraModules = [
-          # Adds your overlay and packages to nixpkgs
+            # Add your custom home-manager modules
-          { nixpkgs.overlays = self.overlays; }
-          # Adds your custom home-manager modules
             ./modules/home-manager
+            # Add overlays
+            { nixpkgs.overlays = attrValues overlays; }
           ];
-        # Pass our flake inputs into the config
+          # Make our inputs available to the config (for importing modules)
           extraSpecialArgs = { inherit inputs; };
         };
       };
-  }
-  // utils.lib.eachDefaultSystem (system:
-    let
-      pkgs = import nixpkgs { inherit system; overlays = self.overlays; };
-      nix = pkgs.writeShellScriptBin "nix" ''
-        exec ${pkgs.nixFlakes}/bin/nix --experimental-features "nix-command flakes" "$@"
-      '';
-      hm = home-manager.defaultPackage."${system}";
-    in
-    {
-      # Your custom packages, plus nixpkgs and overlayed stuff
-      # Accessible via 'nix build .#example' or 'nix build .#nixpkgs.example'
-      packages = {
-        nixpkgs = pkgs;
-      } // (import ./pkgs { inherit pkgs; });
 
-      # Devshell for bootstrapping plus editor utilities (fmt and LSP)
+      # Packages
+      # Accessible via 'nix build'
+      packages = eachDefaultSystemMap (system:
+        # Propagate nixpkgs' packages, with our overlays applied
+        import nixpkgs { inherit system; overlays = attrValues overlays; }
+      );
+
+      # Devshell for bootstrapping
       # Accessible via 'nix develop'
-      devShell = pkgs.mkShell {
+      devShells = eachDefaultSystemMap (system: {
-        buildInputs = with pkgs; [ nix nixfmt rnix-lsp hm ];
+        default = import ./shell.nix { pkgs = packages.${system}; };
-      };
       });
+    };
 }

nixos/configuration.nix

@@ -2,69 +2,74 @@
 # Use this to configure your system environment (it replaces /etc/nixos/configuration.nix)
 
 { inputs, lib, config, pkgs, ... }: {
+
   imports = [
     # If you want to use modules from other flakes (such as nixos-hardware), use something like:
     # inputs.hardware.nixosModules.common-cpu-amd
     # inputs.hardware.nixosModules.common-ssd
+
     # It's strongly recommended you take a look at
     # https://github.com/nixos/nixos-hardware
     # and import modules relevant to your hardware.
 
-    # Import your generated hardware configuration
+    # Import your generated (nixos-generate-config) hardware configuration
     ./hardware-configuration.nix
 
-    # Feel free to split up your configuration and import pieces of it here.
+    # You can also split up your configuration and import pieces of it here.
   ];
 
+  # This will add your inputs as registries, making operations with them (such
+  # as nix shell nixpkgs#name) consistent with your flake inputs.
+  nix.registry = lib.mapAttrs' (n: v: lib.nameValuePair n { flake = v; }) inputs;
+
+  # Will activate home-manager profiles for each user upon login
+  # This is useful when using ephemeral installations
+  environment.loginShellInit = ''
+    [ -d "$HOME/.nix-profile" ] || /nix/var/nix/profiles/per-user/$USER/home-manager/activate &> /dev/null
+  '';
+
+  nix = {
+    # Make sure we have at least nix 2.4
+    # TODO: You can remove me if you're using NixOS 22.05+
+    package = pkgs.nixFlakes;
+    # Enable flakes and new 'nix' command
+    extraOptions = ''
+      experimental-features = nix-command flakes
+    '';
+    autoOptimiseStore = true;
+  };
+
+  # Remove if you wish to disable unfree packages for your system
+  nixpkgs.config.allowUnfree = true;
+
+  # FIXME: Add the rest of your current configuration
+
   # TODO: Set your hostname
   networking.hostName = "cool-computer";
 
   # TODO: This is just an example, be sure to use whatever bootloader you prefer
   boot.loader.systemd-boot.enable = true;
 
-  # TODO: Configure your system-wide user settings (stuff on the user
+  # TODO: Configure your system-wide user settings (groups, etc), add more users as needed.
-  # environment should instead go to home.nix)
   users.users = {
-    # TODO: Replace with your username
+    # FIXME: Replace with your username
     you = {
       isNormalUser = true;
       openssh.authorizedKeys.keys = [
         # TODO: Add your SSH public key(s) here, if you plan on using SSH to connect
       ];
-      # Be sure to add any other groups you need
+      # TODO: Be sure to add any other groups you need (such as networkmanager, audio, docker, etc)
       extraGroups = [ "wheel" ];
     };
   };
 
-  # This setups SSH for the system (with SSH keys ONLY). Feel free to remove if you don't need it.
+  # This setups a SSH server. Very important if you're setting up a headless system.
+  # Feel free to remove if you don't need it.
   services.openssh = {
     enable = true;
-    passwordAuthentication = false;
+    # Forbid root login through SSH.
     permitRootLogin = "no";
+    # Use keys only. Remove if you want to SSH using password (not recommended)
+    passwordAuthentication = false;
   };
-
-  # Remove if you wish to disable unfree packages for your system
-  nixpkgs.config.allowUnfree = true;
-
-  # Enable flakes and new 'nix' command
-  nix = {
-    package = pkgs.nixFlakes;
-    extraOptions = ''
-      experimental-features = nix-command flakes
-    '';
-    autoOptimiseStore = true;
-  };
-
-  # This will make all users activate their home-manager profile upon login, if
-  # it exists and is not activated yet. This is useful for setups with opt-in
-  # persistance, avoiding having to manually activate every reboot.
-  environment.loginShellInit = ''
-    [ -d "$HOME/.nix-profile" ] || /nix/var/nix/profiles/per-user/$USER/home-manager/activate &> /dev/null
-  '';
-
-  # This will add your inputs as registries, making operations with them
-  # consistent with your flake inputs.
-  nix.registry = lib.mapAttrs' (n: v:
-    lib.nameValuePair (n) ({ flake = v; })
-  ) inputs;
 }

overlay/default.nix

@@ -1,7 +1,8 @@
-# Your overlays should go here (https://nixos.wiki/wiki/Overlays)
+# Your overlays go here (see https://nixos.wiki/wiki/Overlays)
+
 final: prev: {
   # example = prev.example.overrideAttrs (oldAttrs: rec {
   # ...
   # });
+# This line adds our custom packages into the overlay.
 } // import ../pkgs { pkgs = final; }
-# This line adds your custom packages into the overlay.

pkgs/example/default.nix

@@ -1,3 +0,0 @@
-# This is a package. You can use the same format any package on nixpkgs uses.
-# Example: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/applications/misc/hello/default.nix
-{}

shell.nix

@@ -0,0 +1,27 @@
+# Shell for bootstrapping flake-enabled nix and home-manager, from any nix version
+{ pkgs ? let
+    system = builtins.currentSystem or "Unknown system";
+
+    nixpkgs =
+      if builtins.pathExists ./flake.lock
+      then
+      # If we have a lock, fetch locked nixpkgs
+        let lock = builtins.fromJSON (builtins.readFile ./flake.lock).nodes.nixpkgs.locked;
+        in
+        fetchTarball {
+          url = "https://github.com/nixos/nixpkgs/archive/${lock.rev}.tar.gz";
+          sha256 = lock.narHash;
+        }
+      else
+      # If not (probably because not flake-enabled), fetch nixos-unstable impurely
+        fetchTarball {
+          url = "https://github.com/nixos/nixpkgs/archive/nixos-unstable.tar.gz";
+        };
+
+  in
+  import nixpkgs { inherit system; }
+, ...
+}:
+pkgs.mkShell {
+  nativeBuildInputs = with pkgs; [ nix home-manager git ];
+}