diff --git a/README.md b/README.md index 40c4a1a..8293395 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ +> [!IMPORTANT] +> This repo might become slightly out of date as things change fast. Please check official documentation for NixOS and home-manager to make sure you're doing things right. See https://github.com/Misterio77/nix-starter-configs/issues/86 for more info and additional learning resources you might be interested in :D + # Nix Starter Config This repo contains a few a simple nix flake templates for getting started with @@ -48,22 +51,20 @@ 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 +it seems a little confusing at first. Get comfortable 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), if you haven't already. +- [Install git](https://wiki.nixos.org/wiki/git), if you haven't already. - Create a repository for your config, for example: ```bash cd ~/Documents git init nix-config cd nix-config ``` -- Make sure you're running Nix 2.4+, and opt into the experimental `flakes` and `nix-command` features: +- Opt into the experimental `flakes` and `nix-command` features: ```bash -# Should be 2.4+ -nix --version export NIX_CONFIG="experimental-features = nix-command flakes" ``` - Get the template: @@ -87,6 +88,8 @@ nix flake init -t github:misterio77/nix-starter-config#standard 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) +- Update your flake lock with `nix flake update`, so you get the latest + packages and modules - `git add` and `git push` your changes! Or at least copy them somewhere if you're on a live medium. @@ -105,14 +108,50 @@ the latest and greatest nix3 flake-enabled command UX. # What next? -## Multiple nixpkgs channels +## Use home-manager as a NixOS module -`multi-nixpkgs` shows how to setup multiple nixpkgs channels. For example, using the stable channel you can add the unstable version of neovim like: +If you prefer to build your home configuration together with your NixOS one, +it's pretty simple. +Simply remove the `homeConfigurations` block from the `flake.nix` file; then +add this to your NixOS configuration (either directly on +`nixos/configuration.nix` or on a separate file and import it): + +```nix +{ inputs, ... }: { + imports = [ + # Import home-manager's NixOS module + inputs.home-manager.nixosModules.home-manager + ]; + + home-manager = { + extraSpecialArgs = { inherit inputs; }; + users = { + # Import your home-manager configuration + your-username = import ../home-manager/home.nix; + }; + }; +} ``` -home.packages = with pkgs; [ - unstable.neovim -]; + +In this setup, the `home-manager` tool will not be installed (see +[nix-community/home-manager#4342](https://github.com/nix-community/home-manager/pull/4342)). +To rebuild your home configuration, use `nixos-rebuild` instead. + +But if you want to install the `home-manager` tool anyways, you can add the +package into your configuration: + +```nix +# To install it for a specific user +users.users = { + your-username = { + packages = [ inputs.home-manager.packages.${pkgs.system}.default ]; + }; +}; + +# To install it globally +environment.systemPackages = + [ inputs.home-manager.packages.${pkgs.system}.default ]; ``` ## Adding more hosts or users @@ -144,7 +183,7 @@ If you don't want to set your password imperatively, you can also use outside the nix store. There's also [more advanced options for secret -management](https://nixos.wiki/wiki/Comparison_of_secret_managing_schemes), +management](https://wiki.nixos.org/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. @@ -190,6 +229,9 @@ Here's some awesome blog posts about it: - [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/) +Note that for `home-manager` to work correctly here, you need to set up its +NixOS module, as described in the [previous section](#use-home-manager-as-a-nixos-module). + ## Adding custom packages Something you want to use that's not in nixpkgs yet? You can easily build and @@ -216,7 +258,7 @@ Use the `overlays/default.nix` file for this. If you're creating patches, you can keep them on the `overlays` folder as well. -See [the wiki article](https://nixos.wiki/wiki/Overlays) to see how it all +See [the wiki article](https://wiki.nixos.org/wiki/Overlays) to see how it all works. ## Adding your own modules @@ -229,7 +271,7 @@ 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 +See [the wiki article](https://wiki.nixos.org/wiki/Module) to learn more about them. # Troubleshooting / FAQ @@ -245,6 +287,14 @@ and you should be good to go. Files on `.gitignore`, of course, are invisible to nix - this is to guarantee your build won't depend on anything that is not on your repo. +## Nix installs the wrong version of software/fails to find new software + +The nix dependencies (such as `nixpkgs`) used by your configuration will +strictly follow the `flake.lock` file, using the commits written into it when +you (re)generated. + +To update your flake inputs, simply use `nix flake update`. +