181 lines
7.1 KiB
Markdown
181 lines
7.1 KiB
Markdown
# Introduction
|
|
|
|
This project is under construction as a rewrite of my [legacy][old]
|
|
NixOS configuration using the experimental [flakes][rfc] 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](https://nixos.org/nixops)
|
|
support.
|
|
|
|
|
|
#### [Flake Talk][video]
|
|
|
|
# Usage
|
|
|
|
Enter a nix-shell either manually or automatically using [direnv][direnv]. This
|
|
will set up the experimental nix features that need to be available to use
|
|
[flakes][pr].
|
|
|
|
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](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](#contributing)
|
|
below on how to structure your expressions. And be sure to update the
|
|
[locale.nix](local/locale.nix) for your region.
|
|
|
|
You can always check out my personal branch
|
|
[`nrdxp`](https://github.com/nrdxp/nixflk/tree/nrdxp), for concrete examples.
|
|
|
|
## Additional Capabilities
|
|
|
|
Making iso images:
|
|
```
|
|
rebuild iso
|
|
```
|
|
|
|
Will make a minimal and bootable iso image of the [niximg](hosts/niximg.nix)
|
|
configuration. You can customize the image by editing this file.
|
|
|
|
You can also install the packages declared in [pkgs](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.
|
|
|
|
# Contributing
|
|
|
|
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](hosts)
|
|
directory. Every file in this directory will be added automatically to the
|
|
the `nixosConfigurations` flake output. See the
|
|
[`default.nix`](hosts/default.nix) for the implementation details.
|
|
|
|
## Profiles
|
|
More abstract configurations suitable for reuse by multiple machines should
|
|
go in the [profiles](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](https://nixos.org/nixos/manual/options.html), create an expression
|
|
under the [modules](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](profiles/develop/zsh).
|
|
It's written in a generic way to allow in to be imported without the entire
|
|
[develop](profiles/develop) if one so wished. This provides a wonderful level of
|
|
granularity.
|
|
|
|
In addition, profiles can depend on other profiles. For example, The
|
|
[graphical](profiles/graphical) profile depends on [develop](profiles/develop)
|
|
simply by importing it in its [`default.nix`](profiles/graphical/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](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][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](https://github.com/AGWA/git-crypt)
|
|
if your not familiar. The filter is already set up to encrypt everything in this
|
|
folder by default.
|
|
|
|
To keep [profiles](profiles) reusable across configurations, secrets should
|
|
only be imported from the `users` directory.
|
|
|
|
## Modules and Packages
|
|
All [modules](modules/default.nix) and [pkgs](pkgs/default.nix) 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.
|
|
|
|
## Pull Requests
|
|
|
|
While much of your work in this template may be idiosyncratic in nature. Anything
|
|
that might be generally useful to the broader NixOS community can be synced to
|
|
the `template` branch to provide a host of useful NixOS configurations available
|
|
"out of the box". If you wish to contribute such an expression please follow
|
|
these guidelines:
|
|
|
|
* format your code with [`nixfmt`][nixfmt]
|
|
* The commit message follows the same semantics as [nixpkgs][nixpkgs].
|
|
* You can use a `#` symbol to specify ambiguities. For example,
|
|
`develop#zsh: <rest of commit message>` would tell me that your updating the
|
|
`zsh` subprofile living under the `develop` profile.
|
|
|
|
|
|
|
|
# License
|
|
|
|
This software is licensed under the [MIT License](COPYING).
|
|
|
|
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.
|
|
|
|
[direnv]: https://direnv.net
|
|
[home-manager]: https://github.com/rycee/home-manager
|
|
[NixOS]: https://nixos.org
|
|
[nixfmt]: https://github.com/serokell/nixfmt
|
|
[nixpkgs]: https://github.com/NixOS/nixpkgs
|
|
[old]: https://github.com/nrdxp/nixos
|
|
[pr]: https://github.com/NixOS/nixpkgs/pull/68897
|
|
[rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md
|
|
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0
|