Go to file
Timothy DeHerrera e7153d31fe
README.md: be more concise
2020-01-05 03:43:28 -07:00
.github/ISSUE_TEMPLATE Update issue templates 2020-01-04 17:21:01 -07:00
hosts change formatter to nixfmt 2020-01-03 22:06:31 -07:00
lib change formatter to nixfmt 2020-01-03 22:06:31 -07:00
local change formatter to nixfmt 2020-01-03 22:06:31 -07:00
modules modules: convert to list to match nixpkg sematics 2020-01-04 16:08:49 -07:00
pkgs change formatter to nixfmt 2020-01-03 22:06:31 -07:00
profiles profiles: convert to list same as modules 2020-01-04 16:23:15 -07:00
.envrc Initialize template branch 2020-01-03 17:47:17 -07:00
.gitattributes setup configurations API 2019-12-05 01:58:40 -07:00
.gitignore setup configurations API 2019-12-05 01:58:40 -07:00
CONTRIBUTING.md CONTRIBUTING.md: break off from README.md 2020-01-04 17:16:59 -07:00
COPYING init 2019-12-02 22:18:30 -07:00
README.md README.md: be more concise 2020-01-05 03:43:28 -07:00
configuration.nix configuration.nix: import module list directly 2020-01-04 16:40:16 -07:00
flake.lock graphical#ffmpeg: build with svt-av1 support 2019-12-30 18:42:36 -07:00
flake.nix profiles: convert to list same as modules 2020-01-04 16:23:15 -07:00
shell.nix change formatter to nixfmt 2020-01-03 22:06:31 -07:00

README.md

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.