forked from pub-solar/os
doc: new mdbook documentation
This commit is contained in:
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
|
up
|
||||||
hosts/up-*
|
hosts/up-*
|
||||||
.direnv
|
.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
|
# passed to all nixos modules
|
||||||
specialArgs = {
|
specialArgs = {
|
||||||
unstableModulesPath = "${master}/nixos/modules";
|
overrideModulesPath = "${override}/nixos/modules";
|
||||||
hardware = nixos-hardware.nixosModules;
|
hardware = nixos-hardware.nixosModules;
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
|
@ -7,7 +7,7 @@
|
||||||
"nixos"
|
"nixos"
|
||||||
],
|
],
|
||||||
"nixos-unstable": [
|
"nixos-unstable": [
|
||||||
"master"
|
"override"
|
||||||
],
|
],
|
||||||
"pre-commit-hooks-nix": "pre-commit-hooks-nix"
|
"pre-commit-hooks-nix": "pre-commit-hooks-nix"
|
||||||
},
|
},
|
||||||
|
@ -93,7 +93,7 @@
|
||||||
"type": "github"
|
"type": "github"
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"master": {
|
"override": {
|
||||||
"locked": {
|
"locked": {
|
||||||
"lastModified": 1612717294,
|
"lastModified": 1612717294,
|
||||||
"narHash": "sha256-V3j1rA4a3Lzf5pdbFHzs9jUcOKB91MFO3X8nMY+lK5c=",
|
"narHash": "sha256-V3j1rA4a3Lzf5pdbFHzs9jUcOKB91MFO3X8nMY+lK5c=",
|
||||||
|
@ -174,7 +174,7 @@
|
||||||
"devshell": "devshell",
|
"devshell": "devshell",
|
||||||
"flake-utils": "flake-utils",
|
"flake-utils": "flake-utils",
|
||||||
"home": "home",
|
"home": "home",
|
||||||
"master": "master",
|
"override": "override",
|
||||||
"nixos": "nixos",
|
"nixos": "nixos",
|
||||||
"nixos-hardware": "nixos-hardware",
|
"nixos-hardware": "nixos-hardware",
|
||||||
"nur": "nur"
|
"nur": "nur"
|
||||||
|
|
|
@ -3,9 +3,7 @@
|
||||||
|
|
||||||
inputs =
|
inputs =
|
||||||
{
|
{
|
||||||
# Once desired, bump master's locked revision:
|
override.url = "nixpkgs/master";
|
||||||
# nix flake update --update-input master
|
|
||||||
master.url = "nixpkgs/master";
|
|
||||||
nixos.url = "nixpkgs/release-20.09";
|
nixos.url = "nixpkgs/release-20.09";
|
||||||
home.url = "github:nix-community/home-manager/release-20.09";
|
home.url = "github:nix-community/home-manager/release-20.09";
|
||||||
home.inputs.nixpkgs.follows = "nixos";
|
home.inputs.nixpkgs.follows = "nixos";
|
||||||
|
@ -14,7 +12,7 @@
|
||||||
nixos-hardware.url = "github:nixos/nixos-hardware";
|
nixos-hardware.url = "github:nixos/nixos-hardware";
|
||||||
ci-agent.url = "github:hercules-ci/hercules-ci-agent";
|
ci-agent.url = "github:hercules-ci/hercules-ci-agent";
|
||||||
ci-agent.inputs.nixos-20_09.follows = "nixos";
|
ci-agent.inputs.nixos-20_09.follows = "nixos";
|
||||||
ci-agent.inputs.nixos-unstable.follows = "master";
|
ci-agent.inputs.nixos-unstable.follows = "override";
|
||||||
};
|
};
|
||||||
|
|
||||||
outputs =
|
outputs =
|
||||||
|
@ -22,7 +20,7 @@
|
||||||
, ci-agent
|
, ci-agent
|
||||||
, home
|
, home
|
||||||
, nixos
|
, nixos
|
||||||
, master
|
, override
|
||||||
, flake-utils
|
, flake-utils
|
||||||
, nur
|
, nur
|
||||||
, devshell
|
, 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
|
{ lib
|
||||||
, nixos
|
, nixos
|
||||||
, master
|
, override
|
||||||
, nixos-hardware
|
, nixos-hardware
|
||||||
, pkgs
|
, pkgs
|
||||||
, self
|
, self
|
||||||
|
@ -24,15 +24,15 @@ let
|
||||||
let
|
let
|
||||||
core = import ../profiles/core;
|
core = import ../profiles/core;
|
||||||
|
|
||||||
modOverrides = { config, unstableModulesPath, ... }:
|
modOverrides = { config, overrideModulesPath, ... }:
|
||||||
let
|
let
|
||||||
unstable = import ../unstable;
|
overrides = import ../overrides;
|
||||||
inherit (unstable) modules disabledModules;
|
inherit (overrides) modules disabledModules;
|
||||||
in
|
in
|
||||||
{
|
{
|
||||||
disabledModules = modules ++ disabledModules;
|
disabledModules = modules ++ disabledModules;
|
||||||
imports = map
|
imports = map
|
||||||
(path: "${unstableModulesPath}/${path}")
|
(path: "${overrideModulesPath}/${path}")
|
||||||
modules;
|
modules;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
@ -44,7 +44,7 @@ let
|
||||||
|
|
||||||
networking.hostName = hostName;
|
networking.hostName = hostName;
|
||||||
nix.nixPath = [
|
nix.nixPath = [
|
||||||
"nixos-unstable=${master}"
|
"nixos-unstable=${override}"
|
||||||
"nixos=${nixos}"
|
"nixos=${nixos}"
|
||||||
"nixpkgs=${nixos}"
|
"nixpkgs=${nixos}"
|
||||||
];
|
];
|
||||||
|
@ -52,7 +52,6 @@ let
|
||||||
nixpkgs = { inherit pkgs; };
|
nixpkgs = { inherit pkgs; };
|
||||||
|
|
||||||
nix.registry = {
|
nix.registry = {
|
||||||
master.flake = master;
|
|
||||||
nixflk.flake = self;
|
nixflk.flake = self;
|
||||||
nixpkgs.flake = nixos;
|
nixpkgs.flake = nixos;
|
||||||
};
|
};
|
||||||
|
|
|
@ -83,11 +83,11 @@ in
|
||||||
(system:
|
(system:
|
||||||
let
|
let
|
||||||
extern = import ../extern { inherit inputs; };
|
extern = import ../extern { inherit inputs; };
|
||||||
unstable = pkgImport inputs.master [ ] system;
|
overridePkgs = pkgImport inputs.override [ ] system;
|
||||||
overrides = (import ../unstable).packages;
|
overridesOverlay = (import ../overrides).packages;
|
||||||
|
|
||||||
overlays = [
|
overlays = [
|
||||||
(overrides unstable)
|
(overridesOverlay overridePkgs)
|
||||||
self.overlay
|
self.overlay
|
||||||
(final: prev: {
|
(final: prev: {
|
||||||
lib = (prev.lib or { }) // {
|
lib = (prev.lib or { }) // {
|
||||||
|
@ -173,7 +173,7 @@ in
|
||||||
cachixAttrs = { inherit cachix; };
|
cachixAttrs = { inherit cachix; };
|
||||||
|
|
||||||
# modules
|
# modules
|
||||||
moduleList = import ../modules/list.nix;
|
moduleList = import ../modules/module-list.nix;
|
||||||
modulesAttrs = pathsToImportedAttrs moduleList;
|
modulesAttrs = pathsToImportedAttrs moduleList;
|
||||||
|
|
||||||
in
|
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 = [ ];
|
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 = [ ];
|
disabledModules = [ ];
|
||||||
|
|
||||||
# packages pulled from master
|
# packages pulled from override
|
||||||
packages = pkgs: final: prev: {
|
packages = pkgs: final: prev: {
|
||||||
inherit (pkgs)
|
inherit (pkgs)
|
||||||
dhall
|
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
|
* filter=git-crypt diff=git-crypt
|
||||||
.gitattributes !filter !diff
|
.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-install
|
||||||
nixos-generate-config
|
nixos-generate-config
|
||||||
nixos-enter
|
nixos-enter
|
||||||
mdbook
|
|
||||||
];
|
];
|
||||||
|
|
||||||
env = { inherit name; };
|
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 a new issue