Table of Contents

• Getting started
  • Precautions
• Project structure
• Hosts
• Themes

This is the configuration setup for my NixOS instance. This setup is stolen from hlissner’s NixOS config ^[1]. The whole setup is mostly intended for single-user systems but you can easily configure it for multi-user systems.

Getting started

You can replace your NixOS configuration with this bad boi.

To install, you have to do the following first:

• Set up your partitions.

• Copy this setup (either with git or what-have-you) to /etc/dotfiles.

• Install GNU Make.

Then simply run make install. It is equivalent to the following command:

USER=foo-dogsquared HOST=zilch make --directory /etc/dotfiles install

As of 2020-08-28, it wouldn’t work since it assumes the installation root is at / rather than /mnt. To correct this behavior, simply configure the PREFIX variable (e.g., PREFIX=/mnt make install).

For more information, simply inspect the ./Makefile.

Assuming you did install, your project will have the following stuff.

• Add the nixpkgs unstable channel as nixpkgs-unstable (i.e., nix-channels --update https://nixos.org/channels/nixos-unstable).

• Have the home-manager installed with the stable release.

• You start with the TTY and nothing else is installed (i.e., bare installation similar in spirit to Arch Linux). To setup your graphical installation, see the Themes section.

Precautions

There are some things you need to keep in mind when using this setup.

• This setup is not meant to be fully reproducible. It is a personal setup for a person who wants to live on the bleeding edge, personally. Despite being a NixOS setup which should be reproducible on paper, it mainly uses the unstable versions of the channels and packages. If we’re to install this setup at separate times, the full list of installed packages with their depedencies and versions wouldn’t be the same.

• It may use third-party channels for certain versions of the packages, hammering the first precaution even further regarding reproducibility.

Project structure

The project structure should look like the following:

nixos-config
├── config/
├── hosts/
├── modules/
├── packages/
├── templates/
├── default.nix*
├── Makefile*
└── README.adoc*

• The entrypoint of this setup is ./default.nix (which is like index.html for webpages). It contains a function that accepts two arguments: the name of the host and the username of the main user. The host should exist at ./hosts/$HOST/ (see Hosts for more info). Meanwhile, the main user is primarily referred with the my attribute defined at ./modules/default.nix.

• The directory paid with the most attention would most likely be the modules/ folder which contains cluster-wide ^[2] modules intended to be used in each device.

  • Another folder worthy of attention is the modules/themes which sets up a complete desktop environment for you so you don’t have to. For more information, see the Themes section.

• The config/ directory is simply the all-seeing cluster-wide ad hoc configuration of several programs. In this case, it is my dotfiles directory.

• The hosts/ contains the machine-specific configurations of the machine (I’ve only one but I plan to install NixOS for my new ones). It is also used on the installation phase (from make install) by setting the HOST variable (i.e., HOST=zilch make -C /etc/install) with the folder name as the argument. See the Hosts section for more details.

• The packages/ folder is my custom packages either the new ones that haven’t made into nixpkgs yet or packages with overrides. Also contains third-party package repositories and overlays such as the NUR, unstable branch of Emacs, or the unstable branch of nixpkgs.

• The templates/ directory is a bunch of Cookiecutter templates intended for easy creation/deployment of customized systems (e.g., graphical desktop environments, customized modules).

Hosts

Each machine is represented with a directory in ./hosts with the name of the directory as the name of the machine. ^[3]

Each host should have an entrypoint at ./hosts/$HOST/default.nix which is then used from the entrypoint of this setup at ./default.nix (i.e., import /etc/dotfiles "$HOST" "$USER"). It may contain machine-specific configurations (e.g., specific systemd units, Recoll index building, GNU Nano configurations), other Nix modules for modularity, and other sorts of knick-knacks (e.g., other wallpapers, machine-specific scripts).

For best practice, you may want to follow the following project structure:

./hosts/$HOST
├── config/
├── modules/
├── default.nix*
├── hardware-configuration.nix*
└── README.adoc

• config/ contains the specific config files.

• modules/ stores the other Nix modules to be used in default.nix.

• default.nix is the entrypoint for our host module. It contains configuration of our ./modules, NixOS (i.e., man configuration.nix), home-manager (i.e., man home-configuration.nix), and other things you might want to include in the host-specific $HOST/modules/ folder.

• hardware-configuration.nix is there for hardware configurations…​ (I plan to remove this one since it should use the dynamically generated hardware config at /etc/nixos/hardware-configuration.nix.)

• A README file in whatever format you prefer. (I just choose Asciidoctor with the .adoc file extension since it’s my go-to document format.)

Themes

My setup feature themes as a NixOS module (in modules/themes) which sets up a complete graphical environment. This lets me easily switch my graphical setup with a simple toggle (i.e., theme.$THEME_NAME.enable = true;) in my machine configuration (i.e., ./hosts/$HOST/default.nix). For safety from conflicting modules and configuration, you should have a bare installation ala-Arch Linux.

As you can see in the default.nix of the modules/theme directory, a theme should also pass in certain data to modules.theme as if it’s enabled. The following is an example metadata object of a theme.

{
  name = "Fair and square";
  version = "0.1.0";
  path = ./.;
  wallpaper = "${config.modules.theme.path}/config/wallpaper";
}

For best practice, the general project structure of a theme should look like the following:

$THEME_NAME
├── config/
│   ├── PROGRAM_1/
│   ├── PROGRAM_2/
│   ├── PROGRAM_3/
│   └── wallpaper*
├── default.nix*
└── README.adoc*

• The config/ folder is where all of the specific configurations will go. Each program to be configured is stored in its own folder (e.g., polybar, bspwm, sxhkd). A wallpaper can be placed at config/wallpaper for convenience.

• default.nix is simply the entry point for our theme module. This is where you can add certain packages, enable certain settings, setup your files to the home directory, and pass the theme metadata.

• For convenience, you should make the NixOS theme module as a Cookiecutter template to easily replace the color schemes, fonts, and what-have-you. Then, edit modules/themes/default.nix to add the theme to the selection. I have my theme templates stored in ./templates as an example.

---

1. The author and one-man maintainer of Doom Emacs.

2. Whenever I say 'cluster-wide', I really mean my laptop (which I have none at the moment) and desktop (which I have only one at the moment).

3. It is basically using the pets approach (from pets versus cattle thing).