doc: new mdbook documentation
This commit is contained in:
Timothy DeHerrera
parent
4e582b1ff5
commit
bf34d2071f
26
.github/workflows/mdbook_docs.yml
vendored
Normal file
26
.github/workflows/mdbook_docs.yml
vendored
Normal file
@ -0,0 +1,26 @@
|
||||
name: Deploy Docs to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- doc
|
||||
|
||||
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
1
.gitignore
vendored
@ -2,3 +2,4 @@ result
|
||||
up
|
||||
hosts/up-*
|
||||
.direnv
|
||||
book
|
||||
|
||||
@ -1,18 +0,0 @@
|
||||
# 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 [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
|
||||
includes a pre-commit hook that does this for you.
|
||||
|
||||
* 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.
|
||||
|
||||
[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
|
||||
[nixpkgs]: https://github.com/NixOS/nixpkgs
|
||||
105
DOC.md
105
DOC.md
@ -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
|
||||
19
SUMMARY.md
Normal file
19
SUMMARY.md
Normal file
@ -0,0 +1,19 @@
|
||||
# Summary
|
||||
|
||||
- [Introduction](./doc/introduction.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 command](./doc/flk/index.md)
|
||||
9
book.toml
Normal file
9
book.toml
Normal 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
12
cachix/README.md
Normal 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
1
doc/.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
book
|
||||
1
doc/flk/index.md
Normal file
1
doc/flk/index.md
Normal file
@ -0,0 +1 @@
|
||||
# flk command
|
||||
33
doc/introduction.md
Normal file
33
doc/introduction.md
Normal file
@ -0,0 +1,33 @@
|
||||
# Introduction
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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).
|
||||
|
||||
[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
|
||||
4
doc/layout.md
Normal file
4
doc/layout.md
Normal 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
47
doc/start/from-nixos.md
Normal 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
38
doc/start/index.md
Normal 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`](../introduction.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
11
doc/start/iso.md
Normal 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
10
extern/README.md
vendored
Normal 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
2
extern/default.nix
vendored
@ -12,7 +12,7 @@
|
||||
|
||||
# passed to all nixos modules
|
||||
specialArgs = {
|
||||
unstableModulesPath = "${master}/nixos/modules";
|
||||
overrideModulesPath = "${override}/nixos/modules";
|
||||
hardware = nixos-hardware.nixosModules;
|
||||
};
|
||||
}
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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
43
hosts/README.md
Normal 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
|
||||
@ -1,6 +1,6 @@
|
||||
{ lib
|
||||
, nixos
|
||||
, master
|
||||
, override
|
||||
, nixos-hardware
|
||||
, pkgs
|
||||
, self
|
||||
@ -24,15 +24,15 @@ 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;
|
||||
};
|
||||
|
||||
@ -44,7 +44,7 @@ let
|
||||
|
||||
networking.hostName = hostName;
|
||||
nix.nixPath = [
|
||||
"nixos-unstable=${master}"
|
||||
"nixos-unstable=${override}"
|
||||
"nixos=${nixos}"
|
||||
"nixpkgs=${nixos}"
|
||||
];
|
||||
@ -52,7 +52,6 @@ let
|
||||
nixpkgs = { inherit pkgs; };
|
||||
|
||||
nix.registry = {
|
||||
master.flake = master;
|
||||
nixflk.flake = self;
|
||||
nixpkgs.flake = nixos;
|
||||
};
|
||||
|
||||
@ -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
79
modules/README.md
Normal 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
|
||||
25
overlays/README.md
Normal file
25
overlays/README.md
Normal 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
46
overrides/README.md
Normal 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
|
||||
@ -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
59
pkgs/README.md
Normal 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
48
profiles/README.md
Normal 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.
|
||||
1
secrets/.gitattributes
vendored
1
secrets/.gitattributes
vendored
@ -1,2 +1,3 @@
|
||||
* filter=git-crypt diff=git-crypt
|
||||
.gitattributes !filter !diff
|
||||
README.md !filter !diff
|
||||
|
||||
18
secrets/README.md
Normal file
18
secrets/README.md
Normal 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
|
||||
@ -23,7 +23,6 @@ pkgs.devshell.mkShell {
|
||||
nixos-install
|
||||
nixos-generate-config
|
||||
nixos-enter
|
||||
mdbook
|
||||
];
|
||||
|
||||
env = { inherit name; };
|
||||
|
||||
24
suites/README.md
Normal file
24
suites/README.md
Normal 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;
|
||||
}
|
||||
```
|
||||
51
users/README.md
Normal file
51
users/README.md
Normal 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
|
||||
Loading…
Reference in New Issue
Block a user