teutat3s/os
2
0
Fork 0
forked from pub-solar/os
Code Pull requests Activity

Merge pull request #113 from nrdxp/doc

Browse source 
doc: begin work on new documentation
This commit is contained in:
Timothy DeHerrera 2021-02-14 17:48:01 -07:00 committed by GitHub
parent 4e582b1ff5 b9bcbab130
commit b54e5e6b61
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
43 changed files with 776 additions and 375 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
.github/workflows/mdbook_docs.yml vendored Normal file
View file

@ -0,0 +1,26 @@
name: Deploy Docs to GitHub Pages
on:
push:
branches:
- core
jobs:
deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: 'latest'
- run: mdbook build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: gh-pages
publish_dir: ./book

1
.gitignore vendored
View file

@ -2,3 +2,4 @@ result
up
hosts/up-*
.direnv
book

105
DOC.md
View file

@ -1,105 +0,0 @@
## Hosts
Module declarations dependant on 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 and thus becomes deployable via
`nixos-rebuild` and `flk`.
See [`hosts/default.nix`](hosts/default.nix) for the implementation.
## Profiles
A profile is any directory under [profiles](profiles) containing a `default.nix`
defining a function that returns a valid NixOS module, with the added restriction
that no new declarations to the `options` _or_ `config` attributes are allowed
(use [modules](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. i.e:
```nix
{
# importing `profile` without implicitly importing `some`
imports = [ ./profiles/some/profile ];
}
```
It is okay for profiles to depend on other profiles so long as they are
explicitly loaded via `imports`.
## Suites
[Suites](./suites/default.nix) are simple collections of profiles that can be
directly imported from any host like so:
```
{ suites, ... }:
{
imports = suites.mySuite;
}
```
You can declare any combination of users and profiles that you wish, providing
a nice abstraction, free from the idiosyncratic concerns of specific hardware.
## Users
User declarations belong in the `users` directory.
These are actually just a special case of [profiles](#profiles) attached to
a particular interactive user. Its primarily for declarations to
`users.users.<new-user>` where `<new-user>.isNormalUser` is true.
This is a convenient place to import your profiles such that a particular user
always has a reliable stack. Also [user profiles](./users/profiles) are
available to create reusable configs across different users.
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` or [`hosts`](hosts) directory.
## Cachix
When using:
```
cachix use <your-cachix>
```
A file with be created in `/etc/nixos/cachix/your-cachix.nix`. Simply add this
file to git, and it will be exported so others can use your binary cache
directly from this flake via `nixosModules.cachix.<your-cachix>`.
## Modules, Packages and Overlays
All expressions in both [modules/list.nix](modules/list.nix) and
[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the
repo. They are additionally included in the `nixosModules` and `overlay` flake
outputs, respectively. Packages are automatically included 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](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.
If you wish to use an overlay from an external flake, simply add it to the
`externOverlays` list in the `let` block of the `outputs` attribute in
[flake.nix](flake.nix). Same for external modules, add them to `externModules`.
[home-manager]: https://github.com/nix-community/home-manager

256
README.md
View file

@ -1,233 +1,45 @@
> Since flakes are still quite new, I've listed some learning resources
> [below](#resources).
# Introduction
Herein lies a [NixOS][NixOS] configuration template using the new [flakes][wiki]
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, while
keeping your code clean and organized.
Nixflk is a template which grants a simple way to use, deploy and manage
[NixOS][nixos] systems for personal and productive use. It does this by
providing a sane repository structure, integrating several popular projects
like [home-manager][home-manager], setting clear guidelines, offering useful
conveniences, and eliminating boilerplate so you can focus on deploying your
systems.
Some key advantages include:
* A single home for all your Nix expressions, easily sharable and portable!
* Skip the boilerplate, simply use the included [nix-shell](./shell.nix) or
[direnv][direnv] profile and get up and running with flakes right away.
* Thanks to flakes, the entire system is more [deterministic](./flake.lock).
* Systems defined under [hosts](./hosts) are automatically imported into
`nixosConfigurations`, ready to deploy.
* [Profiles](./profiles/list.nix) are a simple mechanism for using portable
code across machines.
* Defined [packages](./pkgs/default.nix) and
[modules](./modules/list.nix), are automatically wired and available from
anywhere. They are _also_ sharable via their respective flake outputs.
* Easily [override](./unstable/default.nix) packages from different nixpkgs
versions.
* Keep [user](./users) configuration isolated and easily reusable by taking
advantage of [user profiles](./users/profiles) and [home-manager][home-manager].
* [Overlay](./overlays) files are automatically available and sharable.
* Automatic [NUR][nur] support.
## Getting Started
Check out the [guide](https://flk.nrdxp.dev/doc/start) to get up and running.
For a more detailed explanation of the code structure, check out the
[docs](./DOC.md).
## Motivation
NixOS provides an amazing abstraction to manage our computers, but that new
power can sometimes bring feelings of overwhelm and confusion. Having a turing
complete programming language can add an unlimited potential for complexity if
we do it wrong. Instead, we should have a community consensus on how to manage
a NixOS system — consider this a first attempt.
### ⚠ Advisory
Flakes are still new, so not everything works yet. However, it has been to
merged in [nixpkgs][nixpkgs] via [`pkgs.nixFlakes`][nixFlakes]. Thus, this
project should be considered _experimental_, until flakes become the default.
___The future is declarative! 🎉___
Also, flakes are meant to deprecate nix-channels. It's recommended not to
install any. If your really want them, they should work if you hook them into
`NIX_PATH`.
## Community Profiles
There are two branches from which to choose: [core][core] and
[community][community]. The community branch builds on core and includes
several ready-made profiles for discretionary use.
# Setup
There are a few ways to get up and running. You can fork this repo or use it as
a template. There is a [community][community] branch with a bunch of useful
profiles, modules, overlays, etc, already configured for you to use. Please
consider adding your own expressions there if you feel they would be helpful
for others.
The only hard requirement is nix itself. The `shell.nix` will pull in
everything else.
## Flake Templates
If you already have [nix-command][nix-command] setup you can:
```sh
# for the core template with no profiles
nix flake new -t "github:nrdxp/nixflk" flk
# for the community template
nix flake new -t "github:nrdxp/nixflk/community" flk
```
## Nix Only
Once you have this repo, you'll want to __move or symlink__ it to `/etc/nixos`
for ease of use. Once inside:
```sh
# probably want to use a separate branch for you config
git checkout -b my-branch
# This will setup nix-command and pull in the needed tools
nix-shell # or `direnv allow` if you prefer
# use nixos-generate-config to generate a basic config for your system
# edit hosts/up-$(hostname).nix to modify.
flk up
# The following should work fine for EFI systems.
# boot.loader.systemd-boot.enable = true;
# boot.loader.efi.canTouchEfiVariables = true;
# Set your locale
$EDITOR local/locale.nix
# install NixOS to bare metal
flk install yourConfig # deploys hosts/yourConfig.nix
# if you already have NixOS and just want to deploy your new setup
flk yourConfig switch
```
### Note on `flk up`:
While the `up` sub-command is provided as a convenience to quickly set up and
install a "fresh" NixOS system on current hardware, committing these files is
discouraged.
They are placed in the git staging area automatically because they would be
invisible to the flake otherwise, but it is best to move what you need from
them directly into your hosts file and commit that instead.
# Sharing
One of the great benefits of flakes is the ability to easily share your user
defined packages, modules and other nix expressions without having to merge
anything upstream. In that spirit, everything defined in this flake is usable
from other flakes. So even if you don't want to use this project as a template,
you can still pull in any useful modules, packages or profiles defined here.
From the command line:
```sh
# to see what this flake exports
nix flake show "github:nrdxp/nixflk"
# run an app
nix run "github:nrdxp/nixflk#someApp"
# start a dev shell for a given derivation
nix develop "github:nrdxp/nixflk#somePackage"
# a nix shell with the package in scope
nix shell "github:nrdxp/nixflk#somePackage"
```
From within a flake:
```nix
{
inputs.nixflk.url = "github:nrdxp/nixflk";
outputs = { self, nixpkgs, nixflk, ... }:
{
nixosConfigurations.example = nixpkgs.lib.nixosSystem {
# ...
modules = [
nixflk.nixosModules.someModule
({
nixpkgs.overlays = [ nixflk.overlay nixflk.overlays.someOverlay ];
})
# ...
];
};
};
}
```
## Home Manager Integration
The home-manager nixos module is available for each host. It is meant
to be used in the user profiles, you can find an example in the nixos user profile
The home-manager configuration for each user in each system is available in the
outputs as homeConfigurations and the activation packages in hmActivationPackages.
This allows you to just build the home-manager environment without the rest of the
system configuration. The feature is useful on systems without nixos or root access.
Lets say you want to activate the home configuration for the user `nixos` in the
host `NixOS`.
With the flk script:
```sh
# You can build it using
flk home NixOS nixos
# and activate with
./result/activate
# Or do both like this
flk home NixOS nixos switch
```
## Build an ISO
You can make an ISO out of any config:
```sh
flk iso yourConfig # build an iso for hosts/yourConfig.nix
```
## Hardware Specific Profile for a Single Host
Find out the fitting
[nixos-hardware profile](https://github.com/NixOS/nixos-hardware#list-of-profiles)
for the hardware of your host, then find the corresponding modules in the
[flake](https://github.com/NixOS/nixos-hardware/blob/master/flake.nix) and add
it to the configuration. For example for a Dell XPS 13 9370 the host
configuration would contain:
```nix
{ hardware, ... }:
{
imports = [ hardware.dell-xps-13-9370 ... ];
...
}
```
## Use a Package from NUR
NUR is wired in from the start. For safety, nothing is added from it by default,
but you can easily pull packages from inside your configuration like so:
```nix
{ pkgs, ... }:
{
environment.systemPackages = with pkgs; [ nur.repos.<owner>.<package> ];
}
```
# Resources
## Links
* [Example Repo](https://github.com/colemickens/nixos-flake-example)
* [Tweag.io _Flakes_ Blog Series](https://www.tweag.io/blog/2020-05-25-flakes)
* [NixOS _Flakes_ Wiki](https://nixos.wiki/wiki/Flakes)
* [Zimbatm's _Flakes_ Blog](https://zimbatm.com/NixFlakes)
* [Original RFC](https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md)
## Flake Talk:
[![Flake talk at NixConf][thumb]][video]
Every package and NixOS profile declared in community is uploaded to
[cachix](./cachix), so everything provided is available without building
anything. This is especially useful for the packages that are
[overridden](./overrides) from master, as without the cache, rebuilds are
quite frequent.
> #### ⚠ Advisory ⚠
> Nixflk leverages the [flakes][flakes] feature available via an _experimental_
> branch of [nix][nix]. Until nix 3.0 is released, this project should be
> considered unstable.
# License
Nixflk is licensed under the [MIT License](https://mit-license.org).
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.
[nix]: https://nixos.org/manual/nix/stable
[nixos]: https://nixos.org/manual/nixos/stable
[home-manager]: https://nix-community.github.io/home-manager
[flakes]: https://nixos.wiki/wiki/Flakes
[core]: https://github.com/nrdxp/nixflk
[community]: https://github.com/nrdxp/nixflk/tree/community
[direnv]: https://direnv.net
[home-manager]: https://github.com/nix-community/home-manager
[nix-command]: https://nixos.wiki/wiki/Nix_command
[nixFlakes]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/package-management/nix/default.nix#L211
[NixOS]: https://nixos.org
[nixpkgs]: https://github.com/NixOS/nixpkgs
[nur]: https://github.com/nix-community/NUR
[wiki]: https://nixos.wiki/wiki/Flakes
[thumb]: https://img.youtube.com/vi/UeBX7Ide5a0/hqdefault.jpg
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0
[nur]: https://github.com/nix-community/NUR

26
SUMMARY.md Normal file
View file

@ -0,0 +1,26 @@
# Summary
- [Introduction](./README.md)
- [Quick Start](./doc/start/index.md)
- [ISO](./doc/start/iso.md)
- [From NixOS](./doc/start/from-nixos.md)
- [Layout](./doc/layout.md)
- [Cachix](./cachix/README.md)
- [Extern](./extern/README.md)
- [Hosts](./hosts/README.md)
- [Modules](./modules/README.md)
- [Overlays](./overlays/README.md)
- [Overrides](./overrides/README.md)
- [Packages](./pkgs/README.md)
- [Profiles](./profiles/README.md)
- [Secrets](./secrets/README.md)
- [Suites](./suites/README.md)
- [Users](./users/README.md)
- [flk](./doc/flk/index.md)
- [up](./doc/flk/up.md)
- [update](./doc/flk/update.md)
- [get](./doc/flk/get.md)
- [iso](./doc/flk/iso.md)
- [install](./doc/flk/install.md)
- [home](./doc/flk/home.md)
- [Contributing](./doc/README.md)

9
book.toml Normal file
View file

@ -0,0 +1,9 @@
[book]
authors = ["Timothy DeHerrera"]
language = "en"
multilingual = false
src = "."
title = "nixflk docs"
[output.html]
site-url = "/nixflk/"

12
cachix/README.md Normal file
View file

@ -0,0 +1,12 @@
# Cachix
The cachix directory simple captures the output of `sudo cachix use` for the
developers personal cache, as well as the nix-community cache. You can easily
add your own cache, assuming the template lives in /etc/nixos, by simply
running `sudo cachix use yourcache`.
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.

1
doc/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
book

1
doc/CONTRIBUTING.md Normal file
View file

@ -0,0 +1 @@
# Contributing

14
CONTRIBUTING.md → doc/README.md
View file

@ -1,10 +1,18 @@
# Pull Requests
If making a change to core, or adding a feature, please be sure to update the
relevant docs. Each directory contains its own README.md, which will
automatically be pulled into the [mdbook](https://flk.nrdxp.dev). The book is
rendered on every change, so the docs should always be up to date.
## Community PRs
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:
the `community` branch to provide a host of useful NixOS configurations available
"out of the box".
# Style
If you wish to contribute please follow these guidelines:
* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
includes a pre-commit hook that does this for you.

10
doc/flk/get.md Normal file
View file

@ -0,0 +1,10 @@
# get
The `get` subcommand is useful for getting a bare copy of nixflk without the
git history. You can pull either the core or community branches.
## Usage
```sh
flk get BRANCH DEST-DIR
```
If DEST-DIR is ommitted, it defaults to _./flk_.

8
doc/flk/home.md Normal file
View file

@ -0,0 +1,8 @@
# home
The `home` subcommand is for using your home-manager configurations outside of
NixOS, providing an awesome mechanism for keeping your environments
synchronized, even when using other systems.
## Usage
The [users](../../users/index.md#external-usage) page contains a good usage
example.

20
doc/flk/index.md Normal file
View file

@ -0,0 +1,20 @@
# flk command
The devshell for the project incudes a convenient script for managing your
system called `flk`. Each of the following chapters is a reference for one of
its subcommands.
## Rebuild
Without any of the subcommands, `flk` acts as a convenient shortcut for
`nixos-rebuild`:
```sh
flk NixOS build
```
Will build _hosts/NixOS.nix_. You can change out `build` for `switch`, `test`,
etc. Any additional arguments are passed through to the call to
`nixos-rebuild`.
## Usage
```sh
flk help
```

12
doc/flk/install.md Normal file
View file

@ -0,0 +1,12 @@
# install
The `install` subcommand is a simple convenience for `nixos-install`, similar
to the shortcut for `nixos-rebuild`, all additional arguments are passed
through.
## Example
```sh
flk install NixOS
```
This will install _hosts/NixOS.nix_ to /mnt. You can override this directory
using standard `nixos-install` args.

1
doc/flk/iso.md Symbolic link
View file

@ -0,0 +1 @@
../start/iso.md

4
doc/flk/up.md Normal file
View file

@ -0,0 +1,4 @@
# up
The `up` subcommand is a simple shortcut for `nixos-generate-config` that is
compatible with nixflk. There is a short explanation in the the getting started
[guide](../start/from-nixos.md#generate-configuration).

6
doc/flk/update.md Normal file
View file

@ -0,0 +1,6 @@
# update
The `update` subcommand is a simple alias for:
```sh
nix flake update --recreate-lock-file --commit-lock-file
```
As it sounds, this will update your lock file, and commit it.

4
doc/layout.md Normal file
View file

@ -0,0 +1,4 @@
# Layout
Each of the following sections is a directory in the root of the project
serving a singular purpose. Select a chapter to read more about its purpose
and usage.

47
doc/start/from-nixos.md Normal file
View file

@ -0,0 +1,47 @@
# From NixOS
## Generate Configuration
Assuming your happy with your existing partition layout, you can generate a
basic NixOS configuration for your system using:
```sh
flk up
```
This will make a new file `hosts/up-$(hostname).nix`, which you can edit to
your liking.
Make sure your `i18n.defaultLocale` and `time.timeZone` are set properly for
your region. Keep in mind that `networking.hostName` with be automatically
set to the filename of your hosts file, so `hosts/my-host.nix` will have the
hostname `my-host`.
Now might be a good time to read the docs on [suites](../../suites) and
[profiles](../../profiles) and add or create any that you need.
> ##### _Note:_
> While the `up` sub-command is provided as a convenience to quickly set up and
> install a "fresh" NixOS system on current hardware, committing these files is
> discouraged.
>
> They are placed in the git staging area automatically because they would be
> invisible to the flake otherwise, but it is best to move what you need from
> them directly into a host module of your own making, and commit that instead.
# Installation
Once your ready to deploy `hosts/my-host.nix`:
```sh
flk my-host switch
```
This calls `nixos-rebuild` with sudo to build and install your configuration.
> ##### _Notes:_
> - Instead of `switch`, you can pass `build`, `test`, `boot`, etc just as with
> `nixos-rebuild`.
>
> - It is convenient to have the template living at `/etc/nixos` so you can
> simply `sudo nixos-rebuild switch` from anywhere on the system, but it is
> not required.

38
doc/start/index.md Normal file
View file

@ -0,0 +1,38 @@
# Quick Start
The only dependency is nix, so make sure you have it [installed][install-nix].
## Get the Template
Here is a snippet that will get you the template without the git history:
```sh
nix-shell https://github.com/nrdxp/nixflk/archive/core.tar.gz -A shell \
--run "flk get core"
cd flk
nix-shell
git init
git add .
git commit -m init
cachix use nrdxp
```
This will place you in a new folder named `flk` with git initialized, and a
nix-shell that provides all the dependencies, including the unstable nix
version required.
In addition, the [binary cache](../../cachix) is added for faster deployment.
> ##### _Notes:_
> - You can change `core` to [`community`](../../index.md#community-profiles)
> in the call to `flk get`
> - Flakes ignore files that have not been added to git, so be sure to stage new
> files before building the system.
## Next Steps:
- [Make installable ISO](./iso.md)
- [Already on NixOS](./from-nixos.md)
[install-nix]: https://nixos.org/manual/nix/stable/#sect-multi-user-installation

11
doc/start/iso.md Normal file
View file

@ -0,0 +1,11 @@
# ISO
Making and writing an installable iso for `hosts/NixOS.nix` is as simple as:
```sh
flk iso NixOS
dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
status=progress oflag=sync
```
This works for any file matching `hosts/*.nix` excluding `default.nix`.

10
extern/README.md vendored Normal file
View file

@ -0,0 +1,10 @@
# External Art
When you need to use a module, overlay, or pass a value from one of your inputs
to the rest of your NixOS configuration, [extern][extern] is where you do it.
Modules and overlays are self explanatory, and the `specialArgs` attribute is
used to extend the arguments passed to all NixOS modules, allowing for
arbitrary values to be passed from flake inputs to the rest of your
configuration.
[extern]: https://github.com/nrdxp/nixflk/tree/core/extern/default.nix

2
extern/default.nix vendored
View file

@ -12,7 +12,7 @@
# passed to all nixos modules
specialArgs = {
unstableModulesPath = "${master}/nixos/modules";
overrideModulesPath = "${override}/nixos/modules";
hardware = nixos-hardware.nixosModules;
};
}

6
flake.lock
View file

@ -7,7 +7,7 @@
"nixos"
],
"nixos-unstable": [
"master"
"override"
],
"pre-commit-hooks-nix": "pre-commit-hooks-nix"
},
@ -93,7 +93,7 @@
"type": "github"
}
},
"master": {
"override": {
"locked": {
"lastModified": 1612717294,
"narHash": "sha256-V3j1rA4a3Lzf5pdbFHzs9jUcOKB91MFO3X8nMY+lK5c=",
@ -174,7 +174,7 @@
"devshell": "devshell",
"flake-utils": "flake-utils",
"home": "home",
"master": "master",
"override": "override",
"nixos": "nixos",
"nixos-hardware": "nixos-hardware",
"nur": "nur"

8
flake.nix
View file

@ -3,9 +3,7 @@
inputs =
{
# Once desired, bump master's locked revision:
# nix flake update --update-input master
master.url = "nixpkgs/master";
override.url = "nixpkgs/master";
nixos.url = "nixpkgs/release-20.09";
home.url = "github:nix-community/home-manager/release-20.09";
home.inputs.nixpkgs.follows = "nixos";
@ -14,7 +12,7 @@
nixos-hardware.url = "github:nixos/nixos-hardware";
ci-agent.url = "github:hercules-ci/hercules-ci-agent";
ci-agent.inputs.nixos-20_09.follows = "nixos";
ci-agent.inputs.nixos-unstable.follows = "master";
ci-agent.inputs.nixos-unstable.follows = "override";
};
outputs =
@ -22,7 +20,7 @@
, ci-agent
, home
, nixos
, master
, override
, flake-utils
, nur
, devshell

43
hosts/README.md Normal file
View file

@ -0,0 +1,43 @@
# 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, nixflk 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` 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 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.
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](../profiles).
This is a good place to import sets of profiles, called [suites](../suites),
that you intend to use on your machine.
Additionally, this is the perfect place to import anything you might need from
the [nixos-hardware][nixos-hardware] repository.
## Example
hosts/librem.nix:
```nix
{ suites, hardware, ... }:
{
imports = suites.laptop ++ [ hardware.purism-librem-13v3 ];
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
}
```
[nixos-hardware]: https://github.com/NixOS/nixos-hardware

78
hosts/default.nix
View file

@ -1,11 +1,12 @@
{ lib
{ extern
, home
, lib
, nixos
, master
, nixos-hardware
, override
, pkgs
, self
, system
, extern
, ...
}:
let
@ -24,42 +25,69 @@ let
let
core = import ../profiles/core;
modOverrides = { config, unstableModulesPath, ... }:
modOverrides = { config, overrideModulesPath, ... }:
let
unstable = import ../unstable;
inherit (unstable) modules disabledModules;
overrides = import ../overrides;
inherit (overrides) modules disabledModules;
in
{
disabledModules = modules ++ disabledModules;
imports = map
(path: "${unstableModulesPath}/${path}")
(path: "${overrideModulesPath}/${path}")
modules;
};
global = {
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
global =
let
inherit (lock) nodes;
hardware.enableRedistributableFirmware = lib.mkDefault true;
lock = builtins.fromJSON (builtins.readFile ../flake.lock);
in
{
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
networking.hostName = hostName;
nix.nixPath = [
"nixos-unstable=${master}"
"nixos=${nixos}"
"nixpkgs=${nixos}"
];
hardware.enableRedistributableFirmware = lib.mkDefault true;
nixpkgs = { inherit pkgs; };
networking.hostName = hostName;
nix.registry = {
master.flake = master;
nixflk.flake = self;
nixpkgs.flake = nixos;
nix.nixPath = [
"nixpkgs=${nixos}"
"nixos-config=${self}/compat/nixos"
"home-manager=${home}"
];
nixpkgs = { inherit pkgs; };
nix.registry = {
flk.flake = self;
nixos = {
exact = true;
from = nodes.nixos.original;
to = {
inherit (nixos) lastModified narHash rev;
path = override.outPath;
type = "path";
};
};
override = {
exact = true;
from = nodes.override.original;
to = {
inherit (override) lastModified narHash rev;
path = override.outPath;
type = "path";
};
};
};
system.configurationRevision = lib.mkIf (self ? rev) self.rev;
};
system.configurationRevision = lib.mkIf (self ? rev) self.rev;
};
local = {
require = [
(import "${toString ./.}/${hostName}.nix")

8
lib/default.nix
View file

@ -83,11 +83,11 @@ in
(system:
let
extern = import ../extern { inherit inputs; };
unstable = pkgImport inputs.master [ ] system;
overrides = (import ../unstable).packages;
overridePkgs = pkgImport inputs.override [ ] system;
overridesOverlay = (import ../overrides).packages;
overlays = [
(overrides unstable)
(overridesOverlay overridePkgs)
self.overlay
(final: prev: {
lib = (prev.lib or { }) // {
@ -173,7 +173,7 @@ in
cachixAttrs = { inherit cachix; };
# modules
moduleList = import ../modules/list.nix;
moduleList = import ../modules/module-list.nix;
modulesAttrs = pathsToImportedAttrs moduleList;
in

79
modules/README.md Normal file
View file

@ -0,0 +1,79 @@
# Modules
The modules directory is a replica of nixpkg's NixOS [modules][nixpkgs-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](../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](../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:
```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:
```nix
[
./services/service-category/my-service.nix
]
```
## Usage
### Internal
profiles/profile-category/my-profile.nix:
```nix
{ ... }:
{
services.MyService.enable = true;
}
```
### External
flake.nix:
```nix
{
# inputs omitted
outputs = { self, nixflk, nixpkgs, ... }: {
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "...";
modules = [
nixflk.nixosModules.my-service
({ ... }: {
services.MyService.enable = true;
})
];
};
};
}
```
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

0
modules/list.nix → modules/module-list.nix
View file

0
overlays/.gitkeep
View file

25
overlays/README.md Normal file
View file

@ -0,0 +1,25 @@
# 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](../hosts), and
exported via `overlays.<file-basename>` _as well as_
`packages.<system>.<pkgName>` (for valid systems), so all you have to do is
write it.
## Example
overlays/kakoune.nix:
```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
];
};
}
```

46
overrides/README.md Normal file
View file

@ -0,0 +1,46 @@
# Overrides
By default, the NixOS systems are based on the latest release. While it is
trivial to change this to nixos-unstable or any other branch of nixpkgs by
changing the flake url, sometimes all we want is a single package from another
branch.
This is what the overrides are for. By default, they are pulled directly from
nixpkgs/master, but you can change the `override` flake input url to
nixos-unstable, or even a specific sha revision.
## Example
### Packages
The override packages are defined as a regular overlay with an extra arguement
`pkgs`. This refers to the packages built from the `override` flake.
Pulling the manix package from the override flake:
```nix
{
packages = pkgs: final: prev: {
inherit (pkgs) manix;
};
}
```
### Modules
You can also pull modules from override. Simply specify their path relative to
the nixpkgs [modules][nixpkgs-modules] directory. The old version will be added
to `disabledModules` and the new version imported into the configuration.
Pulling the zsh module from the override flake:
```nix
{
modules = [ "programs/zsh/zsh.nix" ];
}
```
> ##### _Note:_
> Sometimes a modules name will change from one branch to another. This is what
> the `disabledModules` list is for. If the module name changes, the old
> version will not automatically be disabled, so simply put it's old name in
> this list to disable it.
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

7
unstable/default.nix → overrides/default.nix
View file

@ -1,11 +1,12 @@
# override defaults to nixpkgs/master
{
# modules to pull from master, stable version is automatically disabled
# modules to pull from override, stable version is automatically disabled
modules = [ ];
# if a modules name changed in master, add the old name here
# if a modules name changed in override, add the old name here
disabledModules = [ ];
# packages pulled from master
# packages pulled from override
packages = pkgs: final: prev: {
inherit (pkgs)
dhall

59
pkgs/README.md Normal file
View file

@ -0,0 +1,59 @@
# Packages
Similar to [modules](../modules), the pkgs directory mirrors the upstream
[nixpkgs/pkgs][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.
This overlay is set as the default `overlay` output attribute for the flake.
And 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](../hosts).
## Example
pkgs/development/libraries/libinih/default.nix:
```nix
{ stdenv, meson, ninja, fetchFromGitHub, ... }:
let version = "r50";
in
stdenv.mkDerivation {
pname = "libinih";
inherit version;
src = fetchFromGitHub {
owner = "benhoyt";
repo = "inih";
rev = "${version}";
hash = "sha256-GF+TVEysaXJxSBBjMsTr2IQvRKlzdEu3rlPQ88PE3nI=";
};
buildInputs = [ meson ninja ];
mesonFlags = ''
-Ddefault_library=shared
-Ddistro_install=true
'';
meta = with stdenv.lib; {
description = "Simple .INI file parser in C";
homepage = "https://github.com/benhoyt/inih";
maintainers = [ maintainers.nrdxp ];
license = licenses.bsd3;
platforms = platforms.all;
inherit version;
};
}
```
pkgs/default.nix:
```nix
final: prev: {
libinih = prev.callPackage ./development/libraries/libinih { };
}
```
[pkgs]: https://github.com/NixOS/nixpkgs/tree/master/pkgs

48
profiles/README.md Normal file
View file

@ -0,0 +1,48 @@
# Profiles
Profiles are simply NixOS modules which contain generic expressions suitable
for any host. A good example is the configuration for a text editor, or
window manager. If you need some concrete examples, just checkout the
community [branch](https://github.com/nrdxp/nixflk/tree/community/profiles).
## Constraints
For the sake of consistency, there are a few minor constraints. First of all, a
profile should always be defined in a `default.nix`, and it should always be a
a function taking a single attribute set as an argument, and returning a NixOS
module which does not define any new module options. If you need to make new
module option declarations, just use [modules](../modules).
These restrictions help simplify the import logic used to pass profles to
[suites](../suites).
### Example
#### Correct ✔
profiles/develop/default.nix:
```nix
{ ... }:
{
programs.zsh.enable = true;
}
```
#### Incorrect ❌
profiles/develop.nix:
```nix
{
options = {};
}
```
## Subprofiles
Profiles can also define subprofiles. They follow the same constraints outlined
above. A good top level profile should be a high level concern, such a your
personal development environment, and the subprofiles should be more concrete
program configurations such as your text editor, and shell configs. This way,
you can either pull in the whole development profile, or pick and choose
individual programs.
## Conclusion
Profiles are the most important concept in nixflk. They allow us to keep our
nix expressions self contained and modular. This way we can maximize reuse
while minimizing boilerplate. Always strive to keep your profiles as generic
and modular as possible. Anything machine specific belongs in your
[host](../hosts) files.

19
profiles/core/default.nix
View file

@ -65,8 +65,8 @@ in
nr = "np remove";
ns = "n search --no-update-lock-file";
nf = "n flake";
nepl = "n repl '<nixos>'";
srch = "ns nixpkgs";
nepl = "n repl '<nixpkgs>'";
srch = "nsni";
nrb = ifSudo "sudo nixos-rebuild";
mn = ''
manix "" | grep '^# ' | sed 's/^# \(.*\) (.*/\1/;s/ (.*//;s/^# //' | sk --preview="manix '{}'" | xargs manix
@ -93,7 +93,20 @@ in
dn = ifSudo "s systemctl stop";
jtl = "journalctl";
};
} // lib.mapAttrs'
(n: v:
let
prefix = lib.concatStrings (lib.take 2 (lib.stringToCharacters n));
ref = from:
if from ? ref
then "ns ${from.id}/${from.ref}"
else "ns ${from.id}";
in
lib.nameValuePair
"ns${prefix}"
(ref v.from)
)
config.nix.registry;
};

1
secrets/.gitattributes vendored
View file

@ -1,2 +1,3 @@
* filter=git-crypt diff=git-crypt
.gitattributes !filter !diff
README.md !filter !diff

18
secrets/README.md Normal file
View file

@ -0,0 +1,18 @@
# Secrets
Secrets are managed using [git-crypt][git-crypt] so you can keep your flake in
a public repository like GitHub without exposing your password or other
sensitive data.
By default, everything in the secrets folder is automatically encrypted. Just
be sure to run `git-crypt init` before putting anything in here.
> ##### _Note:_
> Currently, there is [no mechanism][secrets-issue] in nix to deploy secrets
> within the nix/store so, if they end up in the nix/store after deployment, they
> will be world readable on that machine.
>
> The author of nixflk intends to implement a workaround for this situation in
> the near future, but for the time being, simple be aware of this.
[git-crypt]: https://github.com/AGWA/git-crypt
[secrets-issue]: https://github.com/NixOS/nix/issues/8

1
shell/default.nix
View file

@ -23,7 +23,6 @@ pkgs.devshell.mkShell {
nixos-install
nixos-generate-config
nixos-enter
mdbook
];
env = { inherit name; };

24
suites/README.md Normal file
View file

@ -0,0 +1,24 @@
# Suites
Suites provide a mechanism for users to easily combine and name collecitons of
profiles. For good examples, check out the suites defined in the community
[branch](https://github.com/nrdxp/nixflk/blob/community/suites/default.nix).
In the future, we will use suites as a mechanism for deploying various machine
types which don't depend on hardware, such as vm's and containers.
## Definition
```nix
rec {
workstation = [ profiles.develop profiles.graphical users.nixos ];
mobileWS = workstation ++ [ profiles.laptop ];
}
```
## Usage
`hosts/my-laptop.nix`:
```nix
{ suites, ... }:
{
imports = suites.mobileWS;
}
```

6
theme/highlight.js Normal file
View file

File diff suppressed because one or more lines are too long

51
users/README.md Normal file
View file

@ -0,0 +1,51 @@
# Users
Users are a special case of [profiles](../profiles) that define system
users and [home-manager][home-manager] configurations. For your convenience,
home manager is wired in by default so all you have to worry about is declaring
your users. For a fully fleshed out example, check out the developers personal
[branch](https://github.com/nrdxp/nixflk/tree/nrd/users/nrd/default.nix).
## Basic Usage
`users/myuser/default.nix`:
```nix
{ ... }:
{
users.users.myuser = {
isNormalUser = true;
};
home-manager.users.myuser = {
programs.mpv.enable = true;
};
}
```
## External Usage
You can easily use the defined home-manager configurations outside of NixOS
using the `hmActivations` meta-package defined in the flakes `legacyPackages`
output. The [flk](../doc/flk) helper script makes this even easier.
This is great for keeping your environment consistent across Unix systems,
including OSX.
### From within the projects devshell:
```sh
# builds the nixos user defined in the NixOS host
flk home NixOS nixos
# build and activate
flk home NixOS nixos switch
```
### Manually from outside the project:
```sh
# build
nix build "github:nrdxp/nixflk#hmActivationPackages.NixOS.nixos"
# activate
./result/activate && unlink result
```
[home-manager]: https://nix-community.github.io/home-manager