.github/ISSUE_TEMPLATE | ||
hosts | ||
lib | ||
local | ||
modules | ||
pkgs | ||
profiles | ||
.envrc | ||
.gitattributes | ||
.gitignore | ||
configuration.nix | ||
CONTRIBUTING.md | ||
COPYING | ||
flake.lock | ||
flake.nix | ||
README.md | ||
shell.nix |
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
Usage
# 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
# wrapper for `nix build` bypassing `nixos-rebuild`
# Usage: rebuild [([host] {switch|boot|test|dry-activate})|iso]
# You can specify any of the host configurations living in the ./hosts
# directory. If omitted, it will default to your systems current hostname.
rebuild $new_host switch
And now you should be ready to start writing your nix configuration or import your current one. Review 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
nrdxp
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 overlays and modules as well:
# external flake.nix
{
# ...
inputs.nixflk.url = "github:nrdxp/nixflk";
outputs = { self, nixpkgs, nixflk }: {
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. An additional bonus of is the ability to trivially swap or combine profiles.
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 deployable. See the
default.nix
for the implementation details.
Profiles
More abstract expressions suitable for reuse by deployments should live 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.
Every directory here is a profile and should have a default.nix
to import it.
Profiles can have subprofiles which are just subdirectories with a default.nix
.
There's no hard rule that everything in the folder must be imported by its
default.nix
so you can also store relevant configurations that may not be used
as often and just import them directly from a host when needed.
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.