MIT License NixOS Chat

Digga — slangy German for "good friend" — is a flake utility library that helps you declaratively craft and manage all three layers of your system environment within a single nix flakes repository:

This library is based on flake-utils-plus.

Status: Beta

Although this project has already matured quite a bit, a fair amount of api polishing is still expected. There are unstable versions (0.x.x) to help users keep track of changes and progress.

Usage

The best way to make use of library is with the Official template. Check out the guide to get up and running. Also have a look at devos's flake.nix. If anything is not immediately discoverable via our mkFlake, please file a bug report.

Examples

Make sure to check out all the examples to see the different ways to make use of the digga api.

In the Wild

You can also see digga being actually used:

Philosophy

In it's lib.mkFlake function, Digga implements a well-specified API interface comprising four API containers that allow you to:

  1. configure nixpkgs channels including internal and external overlays,

  2. define NixOS hosts including internal and external NixOS modules as well as host defaults that apply to all hosts in the environment,

  3. specify user home environments including internal and external home-manager modules, and

  4. setup & combine a series of devshells that you like to have available in your projects.

Modules, Profiles & Suites

For NixOS- & home-manager-modules, Digga allows you to distinguish between modules, profiles and suites.

  • Modules are abstract configurations that, while holding the implementation, do not set any system state.

  • Profiles are concrete configurations that set system state within the profile domain.

  • Suites are a composable, clean and discoverable mechanism for profile aggregation.

Internal Art vs External Art

Overlays and modules can be defined internally coming from your repo or externally coming from an upstream flake. This distinction serves the library to only export your own work as the public flake output.

Downstream consumers of your flake can now more easily tell your art apart from other upstream art.

Contributing

We encourage contributions of any kind. The simplest way to get involved is to join the chat or report problems and ideas on the issue thread.

To craft well thought out APIs we need all the thoughts regarding new ideas.

Pull Requests are just as amazing.

Why flakes?

Flakes are a part of an explicit push to improve Nix's UX, and have become an integral part of that effort.

They also make Nix expressions easier to distribute and reuse with convient flake references for building or using packages, modules, and whole systems.

Shoulders

This work does not reinvent the wheel. It stands on the shoulders of the following giants:

:onion: — like the layers of an onion

:family: — like family

:heart:

Inspiration & Art

Divnix

The divnix org is an open space that spontaneously formed out of "the Nix". It is really just a place where otherwise unrelated people work together and get stuff done.

It's a place to stop "geeking out in isolation" (or within company boundaries). A place to experiment, learn together, and iterate quickly on best practices. That's what it is.

It might eventually become a non-profit if that's not too complicated or, if those goals are sufficiently upstreamed into "the Nix", dissolved.

License

Digga is licensed under the MIT License.

Quick Start

The only dependency is nix, so make sure you have it installed.

Get the Template

If you currently don't have flakes setup, you can utilize the digga shell to pull the template:

nix-shell "https://github.com/divnix/digga/archive/main.tar.gz" \
  --run "nix flake init -t github:divnix/digga"

If you already have flakes support, you can directly pull the template:

nix flake init -t github:divnix/digga

Then make sure to create the git repository:

git init
git add .
git commit

Finally, run nix-shell to get to an interactive shell with all the dependencies, including the unstable nix version required. You can run menu to confirm that you are using digga (expected output includes [docs], [general commands], [linter], etc.).

In addition, the binary cache is added for faster deployment.

Notes:

  • Flakes ignore files that have not been added to git, so be sure to stage new files before building the system.
  • You can choose to simply clone the repo with git if you want to follow upstream changes.
  • If the nix-shell -p cachix --run "cachix use nrdxp" line doesn't work you can try with sudo: sudo nix-shell -p cachix --run "cachix use nrdxp"

Next Steps

Installation Media

This project leverages nix-community/nixos-generators for building machine images. In most cases, you'll probably want to use the install-iso format.

Making an installable ISO for hosts/bootstrap.nix is as simple as:

nix run github:nix-community/nixos-generators -- \
  --format install-iso \
  --flake '.#bootstrap'

Then "burn" the ISO to your USB stick (or CD-R if you like!) following the instructions in the NixOS manual (or using your preferred USB burner).

You can also swap out the --format for any of the others supported by nixos-generators.

Continue by following the usual installation instructions in the NixOS manual.

ISO Nix Store and Cache

The ISO image holds the Nix store for the live environment and also acts as a binary cache to the installer. To considerably speed things up, the image already includes all flake inputs as well as the devshell closures.

While you could provision any NixOS machine with the same USB stick, an ISO custom-made for your target host will maximise those local cache hits. For hosts that don't differ too much, a single USB stick might be ok, whereas when there are bigger differences, a custom-made USB stick will be considerably faster.

Key Concepts

Key concepts are derived from digga. Please refer to its docs for more details.

This section is dedicated to helping you develop a more hands on understanding of them them.

Hosts

Nix flakes contain an output called nixosConfigurations declaring an attribute set of valid NixOS systems. To simplify the management and creation of these hosts, devos automatically imports every .nix file inside this directory to the mentioned attribute set, applying the projects defaults to each. The only hard requirement is that the file contain a valid NixOS module.

As an example, a file hosts/system.nix or hosts/system/default.nix will be available via the flake output nixosConfigurations.system. You can have as many hosts as you want and all of them will be automatically imported based on their name.

For each host, the configuration automatically sets the networking.hostName attribute to the folder name or name of the file minus the .nix extension. This is for convenience, since nixos-rebuild automatically searches for a configuration matching the current systems hostname if one is not specified explicitly.

You can set channels, systems, and add extra modules to each host by editing the nixos.hosts argument in flake.nix. This is the perfect place to import host specific modules from external sources, such as the nixos-hardware repository.

It is recommended that the host modules only contain configuration information specific to a particular piece of hardware. Anything reusable across machines is best saved for profile modules.

This is a good place to import sets of profiles, called suites, that you intend to use on your machine.

Example

flake.nix:

{
  nixos = {
    imports = [ (devos.lib.importHosts ./hosts) ];
    hosts = {
      librem = {
        channelName = "latest";
        modules = [ nixos-hardware.nixosModules.purism-librem-13v3 ];
      };
    };
  };
}

hosts/librem.nix:

{ suites, ... }:
{
  imports = suites.laptop;

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
}

Overrides

Each NixOS host follows one channel. But many times it is useful to get packages or modules from different channels.

Packages

You can make use of overlays/overrides.nix to override specific packages in the default channel to be pulled from other channels. That file is simply an example of how any overlay can get channels as their first argument.

You can add overlays to any channel to override packages from other channels.

Pulling the manix package from the latest channel:

channels: final: prev: {
  __dontExport = true;
  inherit (pkgs.latest) manix;
}

It is recommended to set the __dontExport property for override specific overlays. overlays/overrides.nix is the best place to consolidate all package overrides and the property is already set for you.

Modules

You can also pull modules from other channels. All modules have access to the modulesPath for each channel as <channelName>ModulesPath. And you can use disabledModules to remove modules from the current channel.

To pull zsh module from the latest channel this code can be placed in any module, whether its your host file, a profile, or a module in ./modules etc:

{ latestModulesPath }:
{
  imports = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
  disabledModules = [ "programs/zsh/zsh.nix" ];
}
Note:

Sometimes a modules name will change from one branch to another.

Profiles

Profiles are a convenient shorthand for the definition of options in contrast to their declaration. They're built into the NixOS module system for a reason: to elegantly provide a clear separation of concerns.

Creation

Profiles are created with the rakeLeaves function which recursively collects .nix files from within a folder. The recursion stops at folders with a default.nix in them. You end up with an attribute set with leaves(paths to profiles) or nodes(attrsets leading to more nodes or leaves).

A profile is used for quick modularization of interelated bits.

Notes:
  • For declaring module options, there's the modules directory.
  • This directory takes inspiration from upstream .

Nested profiles

Profiles can be nested in attribute sets due to the recursive nature of rakeLeaves. This can be useful to have a set of profiles created for a specific purpose. It is sometimes useful to have a common profile that has high level concerns related to all its sister profiles.

Example

profiles/develop/common.nix:

{
  imports = [ ./zsh ];
  # some generic development concerns ...
}

profiles/develop/zsh.nix:

{  ... }:
{
  programs.zsh.enable = true;
  # zsh specific options ...
}

The examples above will end up with a profiles set like this:

{
  develop = {
    common = ./profiles/develop/common.nix;
    zsh = ./profiles/develop/zsh.nix;
  };
}

Conclusion

Profiles are the most important concept in DevOS. They allow us to keep our Nix expressions self contained and modular. This way we can maximize reuse across hosts while minimizing boilerplate. Remember, anything machine specific belongs in your host files instead.

Suites

Suites provide a mechanism for users to easily combine and name collections of profiles.

suites are defined in the importables argument in either the home or nixos namespace. They are a special case of an importable which is passed as a special argument (one that can be use in an imports line) to your hosts. All lists defined in suites are flattened and type-checked as paths.

Definition

rec {
  workstation = [ profiles.develop profiles.graphical users.nixos ];
  mobileWS = workstation ++ [ profiles.laptop ];
}

Usage

hosts/my-laptop.nix:

{ suites, ... }:
{
  imports = suites.mobileWS;
}
Note:

This section and its semantics need a conceptiual rework. Since recently portable home configurations that are not bound to any specific host are a thing.

Users

Users are a special case of profiles that define system users and home-manager configurations. For your convenience, home manager is wired in by default so all you have to worry about is declaring your users.

Basic Usage

users/myuser/default.nix:

{ ... }:
{
  users.users.myuser = {
    isNormalUser = true;
  };

  home-manager.users.myuser = {
    programs.mpv.enable = true;
  };
}

Home Manager

Home Manager support follows the same principles as regular nixos configurations, it even gets its own namespace in your flake.nix as home.

All modules defined in user modules will be imported to Home Manager. User profiles can be collected in a similar fashion as system ones into a suites argument that gets passed to your home-manager users.

Example

flake.nix

{
  home.users.nixos = { suites, ... }: {
    imports = suites.base;
  };
}

External Usage

You can easily use the defined home-manager configurations outside of NixOS using the homeConfigurations flake output.

This is great for keeping your environment consistent across Unix-like systems, including macOS.

# build
nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPackage"

# activate
./result/activate && unlink result

Layout

Each of the following sections is a directory whose contents are output to the outside world via the flake's outputs. Check each chapter for details.

Modules

The modules directory is a replica of nixpkg's NixOS modules , and follows the same semantics. This allows for trivial upstreaming into nixpkgs proper once your module is sufficiently stable.

All modules linked in module-list.nix are automatically exported via nixosModules.<file-basename>, and imported into all hosts.

Note:

This is reserved for declaring brand new module options. If you just want to declare a coherent configuration of already existing and related NixOS options , use profiles instead.

Semantics

In case you've never written a module for nixpkgs before, here is a brief outline of the process.

Declaration

modules/services/service-category/my-service.nix:

{ config, lib, ... }:
let
  cfg = config.services.myService;
in
{
  options.services.myService = {
    enable = lib.mkEnableOption "Description of my new service.";

    # additional options ...
  };

  config = lib.mkIf cfg.enable {
    # implementation ...
  };
}

Import

modules/module-list.nix:

[
  ./services/service-category/my-service.nix
]

Usage

Internal

profiles/profile-category/my-profile.nix:

{ ... }:
{
  services.MyService.enable = true;
}

External

flake.nix:

{
  # inputs omitted

  outputs = { self, devos, nixpkgs, ... }: {
    nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
      system = "...";

      modules = [
        devos.nixosModules.my-service
        ({ ... }: {
          services.MyService.enable = true;
        })
      ];
    };
  };
}

Overlays

Writing overlays is a common occurence when using a NixOS system. Therefore, we want to keep the process as simple and straightforward as possible.

Any .nix files declared in this directory will be assumed to be a valid overlay, and will be automatically imported into all hosts, and exported via overlays.<channel>/<pkgName> as well as packages.<system>.<pkgName> (for valid systems), so all you have to do is write it.

Example

overlays/kakoune.nix:

final: prev: {
  kakoune = prev.kakoune.override {
    configure.plugins = with final.kakounePlugins; [
      (kak-fzf.override { fzf = final.skim; })
      kak-auto-pairs
      kak-buffers
      kak-powerline
      kak-vertical-selection
    ];
  };
}

Packages

Similar to modules, the pkgs directory mirrors the upstream nixpkgs/pkgs, and for the same reason; if you ever want to upstream your package, it's as simple as dropping it into the nixpkgs/pkgs directory.

The only minor difference is that, instead of adding the callPackage call to all-packages.nix, you just add it the the default.nix in this directory, which is defined as a simple overlay.

All the packages are exported via packages.<system>.<pkg-name>, for all the supported systems listed in the package's meta.platforms attribute.

And, as usual, every package in the overlay is also available to any NixOS host.

Another convenient difference is that it is possible to use nvfetcher to keep packages up to date. This is best understood by the simple example below.

Example

It is possible to specify sources separately to keep them up to date semi automatically. The basic rules are specified in pkgs/sources.toml:

# nvfetcher.toml
[libinih]
src.github = "benhoyt/inih"
fetch.github = "benhoyt/inih"

After changes to this file as well as to update the packages specified in there run nvfetcher (for more details see nvfetcher).

The pkgs overlay is managed in pkgs/default.nix:

final: prev: {
  # keep sources first, this makes sources available to the pkgs
  sources = prev.callPackage (import ./_sources/generated.nix) { };

  # then, call packages with `final.callPackage`
  libinih = prev.callPackage ./development/libraries/libinih { };
}

Lastly the example package is in pkgs/development/libraries/libinih/default.nix:

{ stdenv, meson, ninja, lib, sources, ... }:
stdenv.mkDerivation {
  pname = "libinih";

  # version will resolve to the latest available on gitub
  inherit (sources.libinih) version src;

  buildInputs = [ meson ninja ];

  # ...
}

Migration from flake based approach

Previous to nvfetcher it was possible to manage sources via a pkgs/flake.nix, the main changes from there are that sources where in the attribute "srcs" (now "sources") and the contents of the sources where slightly different. In order to switch to the new system, rewrite pkgs/flake.nix to a pkgs/sources.toml file using the documentation of nvfetcher, add the line that calls the sources at the beginning of pkgs/default.nix, and accomodate the small changes in the packages as can be seen from the example.

The example package looked like:

pkgs/flake.nix:

{
  description = "Package sources";

  inputs = {
    libinih.url = "github:benhoyt/inih/r53";
    libinih.flake = false;
  };
}

pkgs/default.nix:

final: prev: {
  # then, call packages with `final.callPackage`
  libinih = prev.callPackage ./development/libraries/libinih { };
}

pkgs/development/libraries/libinih/default.nix:

{ stdenv, meson, ninja, lib, srcs, ... }:
let inherit (srcs) libinih; in
stdenv.mkDerivation {
  pname = "libinih";

  # version will resolve to 53, as specified in the flake.nix file
  inherit (libinih) version;

  src = libinih;

  buildInputs = [ meson ninja ];

  # ...
}

Secrets

Secrets are managed using agenix so you can keep your flake in a public repository like GitHub without exposing your password or other sensitive data.

Agenix

Currently, there is no mechanism in nix itself to deploy secrets within the nix store because it is world-readable.

Most NixOS modules have the ability to set options to files in the system, outside the nix store, that contain sensitive information. You can use agenix to easily setup those secret files declaratively.

agenix encrypts secrets and stores them as .age files in your repository. Age files are encrypted with multiple ssh public keys, so any host or user with a matching ssh private key can read the data. The age module will add those encrypted files to the nix store and decrypt them on activation to /run/agenix.

Setup

All hosts must have openssh enabled, this is done by default in the core profile.

You need to populate your secrets/secrets.nix with the proper ssh public keys. Be extra careful to make sure you only add public keys, you should never share a private key!!

secrets/secrets.nix:

let
  system = "<system ssh key>";
  user = "<user ssh key>";
  allKeys = [ system user ];
in

On most systems, you can get your systems ssh public key from /etc/ssh/ssh_host_ed25519_key.pub. If this file doesn't exist you likely need to enable openssh and rebuild your system.

Your users ssh public key is probably stored in ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub. If you haven't generated a ssh key yet, be sure do so:

ssh-keygen -t ed25519
Note:

The underlying tool used by agenix, rage, doesn't work well with password protected ssh keys. So if you have lots of secrets you might have to type in your password many times.

Secrets

You will need the agenix command to create secrets. DevOS conveniently provides that in the devShell, so just run nix develop whenever you want to edit secrets. Make sure to always run agenix while in the secrets/ folder, so it can pick up your secrets.nix.

To create secrets, simply add lines to your secrets/secrets.nix:

let
  ...
  allKeys = [ system user ];
in
{
  "secret.age".publicKeys = allKeys;
}

That would tell agenix to create a secret.age file that is encrypted with the system and user ssh public key.

Then go into the secrets folder and run:

agenix -e secret.age

This will create the secret.age, if it doesn't already exist, and allow you to edit it.

If you ever change the publicKeys entry of any secret make sure to rekey the secrets:

agenix --rekey

Usage

Once you have your secret file encrypted and ready to use, you can utilize the age module to ensure that your secrets end up in /run/secrets.

In any profile that uses a NixOS module that requires a secret you can enable a particular secret like so:

{ self, ... }:
{
  age.secrets.mysecret.file = "${self}/secrets/mysecret.age";
}

Then you can just pass the path /run/agenix/mysecret to the module.

You can make use of the many options provided by the age module to customize where and how secrets get decrypted. You can learn about them by looking at the age module.

Note:

You can take a look at the agenix repository for more information about the tool.

Testing

Testing is always an important aspect of any software development project, and NixOS offers some incredibly powerful tools to write tests for your configuration, and, optionally, run them in CI.

Unit Tests

Unit tests can be created from regular derivations, and they can do almost anything you can imagine. By convention, it is best to test your packages during their check phase. All packages and their tests will be built during CI.

Integration Tests

All your profiles defined in suites can be tested against an individual host. Simply use digga's pre-baked digga.lib.allProfilesTest like so:

{
  hosts = {
    Morty.tests = [ allProfilesTest ];
  };
}

You can write integration tests for one or more NixOS VMs that can, optionally, be networked together, and yes, it's as awesome as it sounds!

Be sure to use the mkTest function from Digga, digga.lib.mkTest which wraps the official testing-python function to ensure that the system is setup exactly as it is for a bare DevOS system. There are already great resources for learning how to use these tests effectively, including the official docs, a fantastic blog post, and the examples in nixpkgs.

Integrations

This section explores some of the optional tools included with devos to provide a solution to common concerns such as ci and remote deployment. An effort is made to choose tools that treat nix, and where possible flakes, as first class citizens.

Cachix

The system will automatically pull a cachix.nix at the root if one exists. This is usually created automatically by a sudo cachix use. If you're more inclined to keep the root clean, you can drop any generated files in the cachix directory into the profiles/cachix directory without further modification.

For example, to add your own cache, assuming the template lives in /etc/nixos, by simply running sudo cachix use yourcache. Then, optionally, move cachix/yourcache.nix to profiles/cachix/yourcache.nix

These caches are only added to the system after a nixos-rebuild switch, so it is recommended to call cachix use nrdxp before the initial deployment, as it will save a lot of build time.

In the future, users will be able to skip this step once the ability to define the nix.conf within the flake is fully fleshed out upstream.

deploy-rs

Deploy-rs is a tool for managing NixOS remote machines. It was chosen for devos after the author experienced some frustrations with the stateful nature of nixops' db. It was also designed from scratch to support flake based deployments, and so is an excellent tool for the job.

By default, all the hosts are also available as deploy-rs nodes, configured with the hostname set to networking.hostName; overridable via the command line.

Usage

Just add your ssh key to the host:

{ ... }:
{
  users.users.${sshUser}.openssh.authorizedKeys.keyFiles = [
    ../secrets/path/to/key.pub
  ];
}

And the private key to your user:

{ ... }:
{
  home-manager.users.${sshUser}.programs.ssh = {
    enable = true;

    matchBlocks = {
      ${host} = {
        host = hostName;
        identityFile = ../secrets/path/to/key;
        extraOptions = { AddKeysToAgent = "yes"; };
      };
    };
  }
}

And run the deployment:

deploy '.#hostName' --hostname host.example.com
Note:

Your user will need passwordless sudo access

Home Manager

Digga's lib.mkDeployNodes provides only system profile. In order to deploy your home-manager configuration you should provide additional profile(s) to deploy-rs config:

# Initially, this line looks like this: deploy.nodes = digga.lib.mkDeployNodes self.nixosConfigurations { };
deploy.nodes = digga.lib.mkDeployNodes self.nixosConfigurations
  {
    <HOSTNAME> = {
      profilesOrder = [ "system" "<HM_PROFILE>" "<ANOTHER_HM_PROFILE>"];
      profiles.<HM_PROFILE> = {
        user = "<YOUR_USERNAME>";
        path = deploy.lib.x86_64-linux.activate.home-manager self.homeConfigurationsPortable.x86_64-linux.<YOUR_USERNAME>;
      };
      profiles.<ANOTHER_HM_PROFILE> = {
        user = "<ANOTHER_USERNAME>";
        path = deploy.lib.x86_64-linux.activate.home-manager self.homeConfigurationsPortable.x86_64-linux.<ANOTHER_USERNAME>;
      };
    };
  };

Substitute <HOSTNAME>, <HM_PROFILE> and <YOUR_USERNAME> placeholders (omitting the <>).

<ANOTHER_HM_PROFILE> is there to illustrate deploying multiple home-manager configurations. Either substitute those as well, or remove them altogether. Don't forget the profileOrder variable.

nvfetcher

NvFetcher is a workflow companion for updating nix sources.

You can specify an origin source and an update configuration, and nvfetcher can for example track updates to a specific branch and automatically update your nix sources configuration on each run to the tip of that branch.

All package source declaration is done in sources.toml.

From within the devshell of this repo, run nvfetcher, a wrapped version of nvfetcher that knows where to find and place its files and commit the results.

Usage

Statically fetching (not tracking) a particular tag from a github repo:

[manix]
src.manual = "v0.6.3"
fetch.github = "mlvzk/manix"

Tracking the latest github release from a github repo:

[manix]
src.github = "mlvzk/manix" # responsible for tracking
fetch.github = "mlvzk/manix" # responsible for fetching

Tracking the latest commit of a git repository and fetch from a git repo:

[manix]
src.git = "https://github.com/mlvzk/manix.git" # responsible for tracking
fetch.git = "https://github.com/mlvzk/manix.git" # responsible for fetching
Note:

Please refer to the NvFetcher Readme for more options.

Hercules CI

If you start adding your own packages and configurations, you'll probably have at least a few binary artifacts. With hercules we can build every package in our configuration automatically, on every commit. Additionally, we can have it upload all our build artifacts to a binary cache like cachix.

This will work whether your copy is a fork, or a bare template, as long as your repo is hosted on GitHub.

Setup

Just head over to hercules-ci.com to make an account.

Then follow the docs to set up an agent, if you want to deploy to a binary cache (and of course you do), be sure not to skip the binary-caches.json.

Ready to Use

The repo is already set up with the proper default.nix file, building all declared packages, checks, profiles and shells. So you can see if something breaks, and never build the same package twice!

If you want to get fancy, you could even have hercules deploy your configuration!

Note:

Hercules doesn't have access to anything encrypted in the secrets folder, so none of your secrets will accidentally get pushed to a cache by mistake.

You could pull all your secrets via your user, and then exclude it from allUsers to keep checks passing.

Top Level API

digga's top level API. API Containers are documented in their respective sub-chapter:

channelsConfig

nixpkgs config for all channels

Type: attribute set or path convertible to it

Default

{}

inputs

The flake's inputs

Type: attribute set of nix flakes

outputsBuilder

builder for flake system-spaced outputs The builder gets passed an attrset of all channels

Type: function that evaluates to a(n) attribute set or path convertible to it

Default

"channels: { }"

self

The flake to create the DevOS outputs for

Type: nix flake

supportedSystems

The systems supported by this flake

Type: list of strings

Default

["aarch64-linux","aarch64-darwin","x86_64-darwin","x86_64-linux"]

Channels API Container

Configure your channels that you can use throughout your configurations.

⚠ Gotcha ⚠

Devshell & (non-host-specific) Home-Manager pkgs instances are rendered off the nixos.hostDefaults.channelName (default) channel.

channels

nixpkgs channels to create

Type: attribute set of submodules or path convertible to it

Default

{}

channels.<name>.config

nixpkgs config for this channel

Type: attribute set or path convertible to it

Default

{}

channels.<name>.input

nixpkgs flake input to use for this channel

Type: nix flake

Default

"self.inputs.<name>"

channels.<name>.overlays

overlays to apply to this channel these will get exported under the 'overlays' flake output as <channel>/<name> and any overlay pulled from <inputs> will be filtered out

Type: list of valid Nixpkgs overlay or path convertible to its or anything convertible to it or path convertible to it

Default

[]

channels.<name>.patches

patches to apply to this channel

Type: list of paths

Default

[]

Home-Manager API Container

Configure your home manager modules, profiles & suites.

home

hosts, modules, suites, and profiles for home-manager

Type: submodule or path convertible to it

Default

{}

home.exportedModules

modules to include in all hosts and export to homeModules output

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

home.externalModules

The externalModules option has been removed. Any modules that should be exported should be defined with the exportedModules option and all other modules should just go into the modules option.

Type: list of valid modules or anything convertible to it

Default

[]

home.importables

Packages of paths to be passed to modules as specialArgs.

Type: attribute set

Default

{}

home.importables.suites

collections of profiles

Type: null or attribute set of list of paths or anything convertible to its or path convertible to it

Default

null

home.modules

modules to include that won't be exported meant importing modules from external flakes

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

home.users

HM users that can be deployed portably without a host.

Type: attribute set of HM user configs

Default

{}

Devshell API Container

Configure your devshell module collections of your environment.

devshell

Modules to include in your DevOS shell. the modules argument will be exported under the devshellModules output

Type: submodule or path convertible to it

Default

{}

devshell.exportedModules

modules to include in all hosts and export to devshellModules output

Type: list of valid module or path convertible to its or anything convertible to it

Default

[]

devshell.externalModules

The externalModules option has been removed. Any modules that should be exported should be defined with the exportedModules option and all other modules should just go into the modules option.

Type: list of valid modules or anything convertible to it

Default

[]

devshell.modules

modules to include that won't be exported meant importing modules from external flakes

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

NixOS API Container

Configure your nixos modules, profiles & suites.

nixos

hosts, modules, suites, and profiles for NixOS

Type: submodule or path convertible to it

Default

{}

nixos.hostDefaults

Defaults for all hosts. the modules passed under hostDefaults will be exported to the 'nixosModules' flake output. They will also be added to all hosts.

Type: submodule

Default

{}

nixos.hostDefaults.channelName

Channel this host should follow

Type: channel defined in channels

nixos.hostDefaults.exportedModules

modules to include in all hosts and export to nixosModules output

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

nixos.hostDefaults.externalModules

The externalModules option has been removed. Any modules that should be exported should be defined with the exportedModules option and all other modules should just go into the modules option.

Type: list of valid modules or anything convertible to it

Default

[]

nixos.hostDefaults.modules

modules to include that won't be exported meant importing modules from external flakes

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

nixos.hostDefaults.system

system for this host

Type: null or system defined in supportedSystems

Default

null

nixos.hosts

configurations to include in the nixosConfigurations output

Type: attribute set of submodules

Default

{}

nixos.hosts.<name>.channelName

Channel this host should follow

Type: null or channel defined in channels

Default

null

nixos.hosts.<name>.modules

modules to include

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

nixos.hosts.<name>.system

system for this host

Type: null or system defined in supportedSystems

Default

null

nixos.hosts.<name>.tests

tests to run

Type: list of valid NixOS test or path convertible to its or anything convertible to it

Default

[]

Example

{"_type":"literalExpression","text":"[\n  {\n    name = \"testname1\";\n    machine = { ... };\n    testScript = ''\n      # ...\n    '';\n  }\n  ({ corutils, writers, ... }: {\n    name = \"testname2\";\n    machine = { ... };\n    testScript = ''\n      # ...\n    '';\n  })\n  ./path/to/test.nix\n];\n"}

nixos.importables

Packages of paths to be passed to modules as specialArgs.

Type: attribute set

Default

{}

nixos.importables.suites

collections of profiles

Type: null or attribute set of list of paths or anything convertible to its or path convertible to it

Default

null

TL;DR;

  • Target Branch: main
  • Merge Policy: green check: merge away. yellow circle: have patience. red x: try again.
  • Docs: every change set is expected to contain doc updates
  • Commit Msg: be a poet! Comprehensive and explanatory commit messages should cover the motivation and use case in an easily understandable manner even when read after a few months.
  • Test Driven Development: please default to test driven development you can make use of the ./examples & ./e2e and wire test up in the devshell.

Within the Devshell (nix develop)

  • Hooks: please git commit within the devshell
  • Fail Early: please run check-all from within the devshell on your local machine