home_manager.md

Getting started with home-manger

1. install nix https://nixos.org/download.html:

sh <(curl -L https://nixos.org/nix/install) --daemon

2. update ~/.config/nix/nix.conf to contain:

experimental-features = nix-command flakes

3. Make a directory to contain your configs (i use a git repo), and make a file called flake.nix which contains:

{
  description = "Home Manager configuration of Jane Doe";

  inputs = {
    # Specify the source of Home Manager and Nixpkgs.
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, home-manager, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;

        # Specify your home configuration modules here, for example,
        # the path to your home.nix.
        modules = [
          ./home.nix
        ];

        # Optionally use extraSpecialArgs
        # to pass through arguments to home.nix
      };
    };
}

4. Make a home.nix file which contains:

{pkgs, config, ...}:
{
  config = {
    home.packages = with pkgs; [
      
      # Any other packages you want here:
      curl
      wget
      jq
      vim

      kubectl

      terraform
      terraform-ls
    ];

    # Configure "programs" here (program options start listed here: https://rycee.gitlab.io/home-manager/options.html#opt-programs.abook.enable )
    # i.e. vim configurations are here: https://rycee.gitlab.io/home-manager/options.html#opt-programs.vim.enable
    programs = {
      home-manager.enable = true;
    };

  };
}

5. Run:

nix run github:nix-community/home-manager#home-manager -- switch --flake ".#jdoe"

(Where jdoe matches the homeConfigurations key in your flake.nix file).

6. Your machine is all configured! Run which <program> to make sure it's being resolved from the nix store, i.e.

> which kubectl
/Users/paul.gray/.nix-profile/bin/kubectl

Doing other stuff:

Searching for packages

Searching for packages on nixpkgs (i.e. what you can put in the list for home.packages = [...]): nix-env -qaP <package> (You can use regex in the package name).

> nix-env -qaP ".*aws.*"
...
nixpkgs.aws-vault                              aws-vault-6.6.0
nixpkgs.aws-workspaces                         aws-workspaces-4.0.1.1302
nixpkgs.awscli                                 awscli-1.22.88
nixpkgs.awscli2                                awscli2-2.5.6
nixpkgs.awsebcli                               awsebcli-3.20.3
...

So you can put awscli2 in home.packages (in home.nix):

{pkgs, config, ...}:
{
  config = {
    home.packages = with pkgs; [
      awscli2
    ];
  };
  ...
}

Another technique is to open a repl where the pkgs variable is available and inspect the attributes:

> nix repl '<nixpkgs>'
nix-repl>

The pkgs variable is imported into the top level, so any keys are available to inspect. Evaluating the expression awscli2 (The package we found in the previous step) shows us that this is a derivation:

nix-repl> awscli2
«derivation /nix/store/6r0zwhkvq5x8m3x7giahfqnzgikjs71q-awscli2-2.5.6.drv»

This technique is useful for inspecting the various things available on pkgs (which is passed into our home.nix file). For instance, we can use the builtin function builtins.attrNames to look at what's available on pkgs.vimPlugins:

nix-repl> builtins.attrNames pkgs.vimPlugins
[ "BetterLua-vim" "BufOnly" "BufOnly-vim" "CSApprox" "CheckAttach" ...

Configuring programs:

On top of installing various packages, home-manager has a notion of "programs" which can be anything from command line tools like direnv, vim, to desktop applications like chrome and vscode.

The various options are listed at: https://rycee.gitlab.io/home-manager/options.html

Here's an example of configuring vim (in home.nix):

{pkgs, config, ...}:
{
  config = {
    # ...
  };
  programs = {
    vim = {
      enable = true;
      plugins = [
        pkgs.vimPlugins.vim-ruby
        # ...
      ];
      extraConfig = ''
        set nocompatible
        set number
      '';
    };
  };
}