Merge pull request #113 from nrdxp/doc
doc: begin work on new documentation
This commit is contained in:
Timothy DeHerrera
GitHub
commit
b54e5e6b61
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:
|
||||||
|
- 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
1
.gitignore
vendored
@ -2,3 +2,4 @@ result
|
|||||||
up
|
up
|
||||||
hosts/up-*
|
hosts/up-*
|
||||||
.direnv
|
.direnv
|
||||||
|
book
|
||||||
|
|||||||
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
|
|
||||||
256
README.md
256
README.md
@ -1,233 +1,45 @@
|
|||||||
> Since flakes are still quite new, I've listed some learning resources
|
|
||||||
> [below](#resources).
|
|
||||||
|
|
||||||
# Introduction
|
# Introduction
|
||||||
Herein lies a [NixOS][NixOS] configuration template using the new [flakes][wiki]
|
Nixflk is a template which grants a simple way to use, deploy and manage
|
||||||
mechanism. Its aim is to provide a generic repository which neatly separates
|
[NixOS][nixos] systems for personal and productive use. It does this by
|
||||||
concerns and allows one to get up and running with NixOS faster than ever, while
|
providing a sane repository structure, integrating several popular projects
|
||||||
keeping your code clean and organized.
|
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:
|
## Getting Started
|
||||||
* A single home for all your Nix expressions, easily sharable and portable!
|
Check out the [guide](https://flk.nrdxp.dev/doc/start) to get up and running.
|
||||||
* 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.
|
|
||||||
|
|
||||||
For a more detailed explanation of the code structure, check out the
|
## Motivation
|
||||||
[docs](./DOC.md).
|
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
|
___The future is declarative! 🎉___
|
||||||
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.
|
|
||||||
|
|
||||||
Also, flakes are meant to deprecate nix-channels. It's recommended not to
|
## Community Profiles
|
||||||
install any. If your really want them, they should work if you hook them into
|
There are two branches from which to choose: [core][core] and
|
||||||
`NIX_PATH`.
|
[community][community]. The community branch builds on core and includes
|
||||||
|
several ready-made profiles for discretionary use.
|
||||||
|
|
||||||
# Setup
|
Every package and NixOS profile declared in community is uploaded to
|
||||||
There are a few ways to get up and running. You can fork this repo or use it as
|
[cachix](./cachix), so everything provided is available without building
|
||||||
a template. There is a [community][community] branch with a bunch of useful
|
anything. This is especially useful for the packages that are
|
||||||
profiles, modules, overlays, etc, already configured for you to use. Please
|
[overridden](./overrides) from master, as without the cache, rebuilds are
|
||||||
consider adding your own expressions there if you feel they would be helpful
|
quite frequent.
|
||||||
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]
|
|
||||||
|
|
||||||
|
> #### ⚠ 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
|
# License
|
||||||
|
Nixflk is licensed under the [MIT License](https://mit-license.org).
|
||||||
|
|
||||||
This software is licensed under the [MIT License](COPYING).
|
[nix]: https://nixos.org/manual/nix/stable
|
||||||
|
[nixos]: https://nixos.org/manual/nixos/stable
|
||||||
Note: MIT license does not apply to the packages built by this configuration,
|
[home-manager]: https://nix-community.github.io/home-manager
|
||||||
merely to the files in this repository (the Nix expressions, build
|
[flakes]: https://nixos.wiki/wiki/Flakes
|
||||||
scripts, NixOS modules, etc.). It also might not apply to patches
|
[core]: https://github.com/nrdxp/nixflk
|
||||||
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.
|
|
||||||
|
|
||||||
[community]: https://github.com/nrdxp/nixflk/tree/community
|
[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
26
SUMMARY.md
Normal 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
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/CONTRIBUTING.md
Normal file
1
doc/CONTRIBUTING.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Contributing
|
||||||
@ -1,10 +1,18 @@
|
|||||||
# Pull Requests
|
# 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
|
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
|
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
|
the `community` branch to provide a host of useful NixOS configurations available
|
||||||
"out of the box". If you wish to contribute such an expression please follow
|
"out of the box".
|
||||||
these guidelines:
|
|
||||||
|
# Style
|
||||||
|
If you wish to contribute please follow these guidelines:
|
||||||
|
|
||||||
* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
|
* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
|
||||||
includes a pre-commit hook that does this for you.
|
includes a pre-commit hook that does this for you.
|
||||||
10
doc/flk/get.md
Normal file
10
doc/flk/get.md
Normal 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
8
doc/flk/home.md
Normal 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
20
doc/flk/index.md
Normal 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
12
doc/flk/install.md
Normal 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
1
doc/flk/iso.md
Symbolic link
@ -0,0 +1 @@
|
|||||||
|
../start/iso.md
|
||||||
4
doc/flk/up.md
Normal file
4
doc/flk/up.md
Normal 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
6
doc/flk/update.md
Normal 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
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`](../../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
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,11 +1,12 @@
|
|||||||
{ lib
|
{ extern
|
||||||
|
, home
|
||||||
|
, lib
|
||||||
, nixos
|
, nixos
|
||||||
, master
|
|
||||||
, nixos-hardware
|
, nixos-hardware
|
||||||
|
, override
|
||||||
, pkgs
|
, pkgs
|
||||||
, self
|
, self
|
||||||
, system
|
, system
|
||||||
, extern
|
|
||||||
, ...
|
, ...
|
||||||
}:
|
}:
|
||||||
let
|
let
|
||||||
@ -24,42 +25,69 @@ 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;
|
||||||
};
|
};
|
||||||
|
|
||||||
global = {
|
global =
|
||||||
home-manager.useGlobalPkgs = true;
|
let
|
||||||
home-manager.useUserPackages = true;
|
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;
|
hardware.enableRedistributableFirmware = lib.mkDefault true;
|
||||||
nix.nixPath = [
|
|
||||||
"nixos-unstable=${master}"
|
|
||||||
"nixos=${nixos}"
|
|
||||||
"nixpkgs=${nixos}"
|
|
||||||
];
|
|
||||||
|
|
||||||
nixpkgs = { inherit pkgs; };
|
networking.hostName = hostName;
|
||||||
|
|
||||||
nix.registry = {
|
nix.nixPath = [
|
||||||
master.flake = master;
|
"nixpkgs=${nixos}"
|
||||||
nixflk.flake = self;
|
"nixos-config=${self}/compat/nixos"
|
||||||
nixpkgs.flake = 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 = {
|
local = {
|
||||||
require = [
|
require = [
|
||||||
(import "${toString ./.}/${hostName}.nix")
|
(import "${toString ./.}/${hostName}.nix")
|
||||||
|
|||||||
@ -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.
|
||||||
@ -65,8 +65,8 @@ in
|
|||||||
nr = "np remove";
|
nr = "np remove";
|
||||||
ns = "n search --no-update-lock-file";
|
ns = "n search --no-update-lock-file";
|
||||||
nf = "n flake";
|
nf = "n flake";
|
||||||
nepl = "n repl '<nixos>'";
|
nepl = "n repl '<nixpkgs>'";
|
||||||
srch = "ns nixpkgs";
|
srch = "nsni";
|
||||||
nrb = ifSudo "sudo nixos-rebuild";
|
nrb = ifSudo "sudo nixos-rebuild";
|
||||||
mn = ''
|
mn = ''
|
||||||
manix "" | grep '^# ' | sed 's/^# \(.*\) (.*/\1/;s/ (.*//;s/^# //' | sk --preview="manix '{}'" | xargs manix
|
manix "" | grep '^# ' | sed 's/^# \(.*\) (.*/\1/;s/ (.*//;s/^# //' | sk --preview="manix '{}'" | xargs manix
|
||||||
@ -93,7 +93,20 @@ in
|
|||||||
dn = ifSudo "s systemctl stop";
|
dn = ifSudo "s systemctl stop";
|
||||||
jtl = "journalctl";
|
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
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;
|
||||||
|
}
|
||||||
|
```
|
||||||
6
theme/highlight.js
Normal file
6
theme/highlight.js
Normal file
File diff suppressed because one or more lines are too long
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