os/README.md

Introduction

This project is under construction as a rewrite of my legacy NixOS configuration using the experimental flakes mechanism. Its aim is to provide a generic template repository which neatly separates concerns and allows one to get up and running with NixOS faster than ever.

Flakes are still an experimental feature, but once they finally get merged even more will become possible, including nixops support.

Flake Talk

Usage

Enter a nix-shell either manually or automatically using direnv. This will set up the experimental nix features that need to be available to use flakes.

Start a new branch based on the template branch:

git checkout -b <new_branch> template

You may want to use a generated hardware config for your machine:

nixos-generate-config --show-hardware-config > ./hosts/<new_host>.nix

A basic rebuild command is included in the shell to replace nixos-rebuild for now:

Usage: rebuild [host] {switch|boot|test}

#example using above generated config
rebuild <new_host> switch

You can specify one of the host configurations from the hosts directory. If omitted, it will default to your systems current hostname.

And now you should be ready to start writing your nix configuration or import some of the already existing profiles. Review contributing below on how to structure your expressions. And be sure to update the locale.nix for your region.

You can always check out my personal branch nrdxp, for concrete examples.

Additional Capabilities

Making iso images:

rebuild iso

Will make a minimal and bootable iso image of the niximg configuration. You can customize the image by editing this file.

You can also install the packages declared in pkgs without needing to install NixOS. For example:

# from top-level
nix profile install ".#packages.x86_64-linux.purs"

A similar mechanism exists to import the modules and overlays declared in the flake to allow for seamless sharing between configurations.

Structure and Layout

The purpose of this repository is to provide a standardized template structure for NixOS machine expressions, thus enabling simpler sharing and reuse of nix expressions.

Say your friend and you are using this repository, each with your own unique nix expressions. By simply importing your friends flake from flake.nix as an input, you can have access to all of the packages, modules, overlays, and even entire system configurations your friend has defined!

Hosts

Distributions for particular machines should be stored in the hosts directory. Every file in this directory will be added automatically to the the nixosConfigurations flake output. See the default.nix for the implementation details.

Profiles

More abstract configurations suitable for reuse by multiple machines should go in the profiles directory. A distinction is made between a module and profile, in that a profile is simply a regular NixOS module, without any new option declarations. If you want to declare new options, create an expression under the modules directory instead.

Every profile should have a default.nix to easily import it. You can also stick things in the profile's subdirectory which are not automatically imported, but are meant to be manually imported from a host (useful for less common, or specialized configurations).

Importantly, every subdirectory in a profile should be independently importable. For example, a zsh directory lives under profiles/develop. It's written in a generic way to allow in to be imported without the entire develop if one so wished. This provides a wonderful level of granularity.

In addition, profiles can depend on other profiles. For example, The graphical profile depends on develop simply by importing it in its default.nix.

You can, optionally, choose to export your profiles via the flake output. If you add it to the list in profiles/default.nix, then it will become available to other flakes via nixosModules.profiles.<filename>.

Users

User declaration belongs in the users directory. Everything related to your user should be declared here. For convenience, home-manager is available automatically for home directory setup and should only be used from this directory.

Secrets

Anything you wish to keep encrypted goes in the secrets directory, which is created on first entering a nix-shell.

Be sure to run git crypt init, before committing anything to this directory. Be sure to check out git-crypt's documentation if your not familiar. The filter is already set up to encrypt everything in this folder by default.

To keep profiles reusable across configurations, secrets should only be imported from the users directory.

Modules and Packages

All modules and pkgs are available for every configuration automatically. Simply add an expression to one of these directories declaring your module or package, and update the corresponding default.nix to point to it. Now you can use your new module or install your new package as usual from any profile.

Doing this will also add them to the flake's nixosModules or overlays outputs to import them easily into an external NixOS configuration as well.

License

This software is licensed under the MIT License.

Note: MIT license does not apply to the packages built by this configuration, merely to the files in this repository (the Nix expressions, build scripts, NixOS modules, etc.). It also might not apply to patches included here, which may be derivative works of the packages to which they apply. The aforementioned artifacts are all covered by the licenses of the respective packages.