nixos-config/README.adoc

= foo-dogsquared's NixOS config
:toc:

This is the configuration setup for my https://nixos.org[NixOS] instance.
This setup is stolen from https://github.com/hlissner/dotfiles[hlissner's NixOS config] footnote:[The author and one-man maintainer of Doom Emacs.].
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`.
The default behavior of the installation installs my default setup.
It is equivalent to the following command:

[source, shell]
----
PREFIX=/mnt USER=foo-dogsquared HOST=zilch make --directory /etc/dotfiles 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 https://github.com/rycee/home-manager[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:

[source, tree]
----
nixos-config
├── config/
├── hosts/
├── modules/
├── packages/
├── templates/
├── default.nix*
├── Makefile*
└── README.adoc*
----

* The directory paid with the most attention would most likely be the `modules/` folder which contains cluster-wide footnote:[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).]  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 https://github.com/foo-dogsquared/dotflies[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 https://github.com/nix-community/NUR[NUR], https://github.com/nix-community/emacs-overlay[unstable branch of Emacs], or the unstable branch of https://github.com/NixOS/nixpkgs/[nixpkgs].

* The `templates/` directory is a bunch of https://github.com/cookiecutter/cookiecutter/[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 link:./hosts/[`./hosts`] with the name of the directory as the name of the machine.
footnote:[It is basically using the pets approach (from pets versus cattle thing).]

Each host should have an entrypoint at `./hosts/$HOST/default.nix` which is then used from the entrypoint of this setup at link:./default.nix[`./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:

[source, tree]
----
./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 link:./modules[`./modules`], NixOS (i.e., `man configuration.nix`), https://github.com/rycee/home-manager[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 https://asciidoctor.org/[Asciidoctor] with the `.adoc` file extension since it's my go-to document format.)




== Themes

My setup feature themes as a NixOS module (in link:./modules/themes[`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.

[source, nix]
----
{
  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:

[source, tree]
----
$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 https://github.com/cookiecutter/cookiecutter[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 link:./templates[`./templates`] as an example.