8.2 KiB
Introduction
A NixOS configuration template using the experimental flakes mechanism. Its aim is to provide a generic 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, i.e. nixops support.
Flake Talk:
Keep in mind that flakes are meant to deprecate nix-channels. I'd recommend not
installing any. If your really want them, they should work if you wire them
up with your NIX_PATH.
Setup
# not needed if using direnv
nix-shell
git checkout -b $new_branch template
# generate hardware config
nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
# Edit the new file, removing `not-detected.nix` from the imports.
# In order to maintain purity flakes cannot resolve from the NIX_PATH.
# You may also want to import ./hosts/NixOS.nix from here which sets up
# an efi bootloader, enables Network Manager and sets an empty root password.
# Otherwise you'll need to set the bootloader, network and password yourself.
# Also ensure your file systems are set the way you want. And import
# any ./profiles you may wish to try out.
$EDITOR ./hosts/${new_host}.nix
# backup existing config and ensure configuration lives in expected location
mv /etc/nixos /etc/nixos.old
ln -s $PWD /etc/nixos
# a flake is vcs based, so only git aware files are bundled
# adding a new file to staging is enough
git add ./hosts/${new_host}.nix
# `rebuild` wrapper for `nix build` bypassing `nixos-rebuild`
# Usage: rebuild [host] {switch|boot|test|dry-activate}
# You can specify any of the host configurations living in the ./hosts
# directory. If omitted, it will default to your systems current hostname.
# This will be run as root.
rebuild $new_host switch
And now you should be ready to start writing your nix configuration or import your current one. Review the structure below on how to build your layout. And be sure to update the locale.nix for your region.
You can always checkout my personal branch for more concrete examples.
Additional Capabilities
# make an iso image based on ./hosts/niximg.nix
rebuild iso
# install any package the flake exports
nix profile install ".#packages.x86_64-linux.myPackage"
this flake exports multiple outputs for use in other flakes:
# external flake.nix
{
# ...
inputs.nixflk.url = "github:nrdxp/nixflk";
outputs = { self, nixpkgs, nixflk }: {
nixosConfigurations.newConfig = nixflk.nixosConfigurations.someConfig;
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{ nixpkgs.overlays = nixflk.overlays; }
nixflk.nixosModules.myModule
];
};
};
}
Structure
The structure is here to keep things simple and clean. Anything sufficiently generic can ultimately be exported for use in other flakes without getting tied up in user concerns. As an added bonus, one can now trivially swap or combine profiles, creating a custom config in mere moments.
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 and thus becomes deployable. See the
default.nix for the implementation details.
Profiles
A profile is any directory under profiles containing a default.nix
defining a valid NixOS module, with the added restriction that no new
delclarations to the options or config attributes are allowed
(use modules instead). Their purpose is to provide abstract
expressions suitable for reuse by multiple deployments. They are perhaps the
key mechanism by which we keep this repo maintainable.
Profiles can have subprofiles which are themselves just profiles that live under
another. There's no hard rule that everything in the folder must be imported by
its default.nix, so you can also store relevant code that is useful but not
wanted by default in, say, an alt.nix. Importantly, every subdirectory in a
profile should be independent of its parent.
For example, a zsh directory lives under profiles/develop. It's self contained to allow inclusion without the whole of develop if one so wished. This provides a wonderful level of granularity and control. Put simply: take the best, leave the rest.
In addition, profiles can depend on other profiles. For instance, the graphical profile depends on develop simply by importing it. This is to ensure my terminal configuration is always available from within a graphical session.
Optionally, you may choose to export your profiles via the flake output. If
you include it in the list defined in profiles/default.nix,
it will be available to other flakes via nixosModules.profiles.
Users
User declarations belong in the users directory, created on entering nix-shell.
These are actually just a special case of profiles. Any profile that
makes a declaration defining, or referencing a specific interactive user or uid
belongs in here. That way profiles stay general, and all our idiosyncratic data
has a clean home.
For convenience, home-manager is available automatically for home directory setup and should only be used from this directory.
Lib
The lib directory contains a file utils.nix which is an attribute set
meant to consist mainly of utility functions you might want to write and use
throughout the configuration. They are available via a new usr attribute
passed to every NixOS module, eg:
# hosts/some-host.nix
{ usr, ... }:
let data = usr.myFunction # ...
in
{
# NixOS configuration
}
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 or hosts directory.
Modules, Packages and Overlays
All expressions in both modules/default.nix and
pkgs/default.nix are available globally, anywhere else in the
repo. They are additionally included in the nixosModules and overlay flake
outputs, respectively. Packages can manually be added to flake.nix
for inclusion in the packages output as well.
The directory structure is identical to nixpkgs to provide a kind of staging area
for any modules or packages we might be wanting to merge there later. If your not
familiar or can't be bothered, simply dropping a valid nix file and pointing the
default.nix to it, is all that's really required.
As for overlays, they should be defined in the overlays directory.
They will be automatically pulled in for use by all configurations. Nix command
line tools will be able to read overlays from here as well since it is set as
nixpkgs-overlays in NIX_PATH. And of course they will be exported via the
flake output overlays 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.