Merge pull request #113 from nrdxp/doc
doc: begin work on new documentation
This commit is contained in:
commit
b54e5e6b61
43 changed files with 776 additions and 375 deletions
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
|
||||
hosts/up-*
|
||||
.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
|
||||
Herein lies a [NixOS][NixOS] configuration template using the new [flakes][wiki]
|
||||
mechanism. Its aim is to provide a generic repository which neatly separates
|
||||
concerns and allows one to get up and running with NixOS faster than ever, while
|
||||
keeping your code clean and organized.
|
||||
Nixflk is a template which grants a simple way to use, deploy and manage
|
||||
[NixOS][nixos] systems for personal and productive use. It does this by
|
||||
providing a sane repository structure, integrating several popular projects
|
||||
like [home-manager][home-manager], setting clear guidelines, offering useful
|
||||
conveniences, and eliminating boilerplate so you can focus on deploying your
|
||||
systems.
|
||||
|
||||
Some key advantages include:
|
||||
* A single home for all your Nix expressions, easily sharable and portable!
|
||||
* Skip the boilerplate, simply use the included [nix-shell](./shell.nix) or
|
||||
[direnv][direnv] profile and get up and running with flakes right away.
|
||||
* Thanks to flakes, the entire system is more [deterministic](./flake.lock).
|
||||
* Systems defined under [hosts](./hosts) are automatically imported into
|
||||
`nixosConfigurations`, ready to deploy.
|
||||
* [Profiles](./profiles/list.nix) are a simple mechanism for using portable
|
||||
code across machines.
|
||||
* Defined [packages](./pkgs/default.nix) and
|
||||
[modules](./modules/list.nix), are automatically wired and available from
|
||||
anywhere. They are _also_ sharable via their respective flake outputs.
|
||||
* Easily [override](./unstable/default.nix) packages from different nixpkgs
|
||||
versions.
|
||||
* Keep [user](./users) configuration isolated and easily reusable by taking
|
||||
advantage of [user profiles](./users/profiles) and [home-manager][home-manager].
|
||||
* [Overlay](./overlays) files are automatically available and sharable.
|
||||
* Automatic [NUR][nur] support.
|
||||
## Getting Started
|
||||
Check out the [guide](https://flk.nrdxp.dev/doc/start) to get up and running.
|
||||
|
||||
For a more detailed explanation of the code structure, check out the
|
||||
[docs](./DOC.md).
|
||||
## Motivation
|
||||
NixOS provides an amazing abstraction to manage our computers, but that new
|
||||
power can sometimes bring feelings of overwhelm and confusion. Having a turing
|
||||
complete programming language can add an unlimited potential for complexity if
|
||||
we do it wrong. Instead, we should have a community consensus on how to manage
|
||||
a NixOS system — consider this a first attempt.
|
||||
|
||||
### ⚠ Advisory
|
||||
Flakes are still new, so not everything works yet. However, it has been to
|
||||
merged in [nixpkgs][nixpkgs] via [`pkgs.nixFlakes`][nixFlakes]. Thus, this
|
||||
project should be considered _experimental_, until flakes become the default.
|
||||
___The future is declarative! 🎉___
|
||||
|
||||
Also, flakes are meant to deprecate nix-channels. It's recommended not to
|
||||
install any. If your really want them, they should work if you hook them into
|
||||
`NIX_PATH`.
|
||||
## Community Profiles
|
||||
There are two branches from which to choose: [core][core] and
|
||||
[community][community]. The community branch builds on core and includes
|
||||
several ready-made profiles for discretionary use.
|
||||
|
||||
# Setup
|
||||
There are a few ways to get up and running. You can fork this repo or use it as
|
||||
a template. There is a [community][community] branch with a bunch of useful
|
||||
profiles, modules, overlays, etc, already configured for you to use. Please
|
||||
consider adding your own expressions there if you feel they would be helpful
|
||||
for others.
|
||||
|
||||
The only hard requirement is nix itself. The `shell.nix` will pull in
|
||||
everything else.
|
||||
|
||||
## Flake Templates
|
||||
If you already have [nix-command][nix-command] setup you can:
|
||||
```sh
|
||||
# for the core template with no profiles
|
||||
nix flake new -t "github:nrdxp/nixflk" flk
|
||||
|
||||
# for the community template
|
||||
nix flake new -t "github:nrdxp/nixflk/community" flk
|
||||
```
|
||||
|
||||
## Nix Only
|
||||
Once you have this repo, you'll want to __move or symlink__ it to `/etc/nixos`
|
||||
for ease of use. Once inside:
|
||||
```sh
|
||||
# probably want to use a separate branch for you config
|
||||
git checkout -b my-branch
|
||||
|
||||
# This will setup nix-command and pull in the needed tools
|
||||
nix-shell # or `direnv allow` if you prefer
|
||||
|
||||
# use nixos-generate-config to generate a basic config for your system
|
||||
# edit hosts/up-$(hostname).nix to modify.
|
||||
flk up
|
||||
|
||||
# The following should work fine for EFI systems.
|
||||
# boot.loader.systemd-boot.enable = true;
|
||||
# boot.loader.efi.canTouchEfiVariables = true;
|
||||
|
||||
# Set your locale
|
||||
$EDITOR local/locale.nix
|
||||
|
||||
# install NixOS to bare metal
|
||||
flk install yourConfig # deploys hosts/yourConfig.nix
|
||||
|
||||
# if you already have NixOS and just want to deploy your new setup
|
||||
flk yourConfig switch
|
||||
```
|
||||
|
||||
### Note on `flk up`:
|
||||
While the `up` sub-command is provided as a convenience to quickly set up and
|
||||
install a "fresh" NixOS system on current hardware, committing these files is
|
||||
discouraged.
|
||||
|
||||
They are placed in the git staging area automatically because they would be
|
||||
invisible to the flake otherwise, but it is best to move what you need from
|
||||
them directly into your hosts file and commit that instead.
|
||||
|
||||
# Sharing
|
||||
One of the great benefits of flakes is the ability to easily share your user
|
||||
defined packages, modules and other nix expressions without having to merge
|
||||
anything upstream. In that spirit, everything defined in this flake is usable
|
||||
from other flakes. So even if you don't want to use this project as a template,
|
||||
you can still pull in any useful modules, packages or profiles defined here.
|
||||
|
||||
From the command line:
|
||||
```sh
|
||||
# to see what this flake exports
|
||||
nix flake show "github:nrdxp/nixflk"
|
||||
|
||||
# run an app
|
||||
nix run "github:nrdxp/nixflk#someApp"
|
||||
|
||||
# start a dev shell for a given derivation
|
||||
nix develop "github:nrdxp/nixflk#somePackage"
|
||||
|
||||
# a nix shell with the package in scope
|
||||
nix shell "github:nrdxp/nixflk#somePackage"
|
||||
```
|
||||
|
||||
From within a flake:
|
||||
```nix
|
||||
{
|
||||
inputs.nixflk.url = "github:nrdxp/nixflk";
|
||||
|
||||
outputs = { self, nixpkgs, nixflk, ... }:
|
||||
{
|
||||
nixosConfigurations.example = nixpkgs.lib.nixosSystem {
|
||||
# ...
|
||||
modules = [
|
||||
nixflk.nixosModules.someModule
|
||||
({
|
||||
nixpkgs.overlays = [ nixflk.overlay nixflk.overlays.someOverlay ];
|
||||
})
|
||||
# ...
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Home Manager Integration
|
||||
The home-manager nixos module is available for each host. It is meant
|
||||
to be used in the user profiles, you can find an example in the nixos user profile
|
||||
|
||||
The home-manager configuration for each user in each system is available in the
|
||||
outputs as homeConfigurations and the activation packages in hmActivationPackages.
|
||||
|
||||
This allows you to just build the home-manager environment without the rest of the
|
||||
system configuration. The feature is useful on systems without nixos or root access.
|
||||
|
||||
Lets say you want to activate the home configuration for the user `nixos` in the
|
||||
host `NixOS`.
|
||||
|
||||
With the flk script:
|
||||
```sh
|
||||
# You can build it using
|
||||
flk home NixOS nixos
|
||||
# and activate with
|
||||
./result/activate
|
||||
|
||||
# Or do both like this
|
||||
flk home NixOS nixos switch
|
||||
```
|
||||
|
||||
## Build an ISO
|
||||
|
||||
You can make an ISO out of any config:
|
||||
```sh
|
||||
flk iso yourConfig # build an iso for hosts/yourConfig.nix
|
||||
```
|
||||
|
||||
## Hardware Specific Profile for a Single Host
|
||||
|
||||
Find out the fitting
|
||||
[nixos-hardware profile](https://github.com/NixOS/nixos-hardware#list-of-profiles)
|
||||
for the hardware of your host, then find the corresponding modules in the
|
||||
[flake](https://github.com/NixOS/nixos-hardware/blob/master/flake.nix) and add
|
||||
it to the configuration. For example for a Dell XPS 13 9370 the host
|
||||
configuration would contain:
|
||||
```nix
|
||||
{ hardware, ... }:
|
||||
{
|
||||
imports = [ hardware.dell-xps-13-9370 ... ];
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Use a Package from NUR
|
||||
|
||||
NUR is wired in from the start. For safety, nothing is added from it by default,
|
||||
but you can easily pull packages from inside your configuration like so:
|
||||
```nix
|
||||
{ pkgs, ... }:
|
||||
{
|
||||
environment.systemPackages = with pkgs; [ nur.repos.<owner>.<package> ];
|
||||
}
|
||||
```
|
||||
# Resources
|
||||
|
||||
## Links
|
||||
* [Example Repo](https://github.com/colemickens/nixos-flake-example)
|
||||
* [Tweag.io _Flakes_ Blog Series](https://www.tweag.io/blog/2020-05-25-flakes)
|
||||
* [NixOS _Flakes_ Wiki](https://nixos.wiki/wiki/Flakes)
|
||||
* [Zimbatm's _Flakes_ Blog](https://zimbatm.com/NixFlakes)
|
||||
* [Original RFC](https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md)
|
||||
|
||||
## Flake Talk:
|
||||
[![Flake talk at NixConf][thumb]][video]
|
||||
Every package and NixOS profile declared in community is uploaded to
|
||||
[cachix](./cachix), so everything provided is available without building
|
||||
anything. This is especially useful for the packages that are
|
||||
[overridden](./overrides) from master, as without the cache, rebuilds are
|
||||
quite frequent.
|
||||
|
||||
> #### ⚠ Advisory ⚠
|
||||
> Nixflk leverages the [flakes][flakes] feature available via an _experimental_
|
||||
> branch of [nix][nix]. Until nix 3.0 is released, this project should be
|
||||
> considered unstable.
|
||||
|
||||
# License
|
||||
Nixflk is licensed under the [MIT License](https://mit-license.org).
|
||||
|
||||
This software is licensed under the [MIT License](COPYING).
|
||||
|
||||
Note: MIT license does not apply to the packages built by this configuration,
|
||||
merely to the files in this repository (the Nix expressions, build
|
||||
scripts, NixOS modules, etc.). It also might not apply to patches
|
||||
included here, which may be derivative works of the packages to
|
||||
which they apply. The aforementioned artifacts are all covered by the
|
||||
licenses of the respective packages.
|
||||
|
||||
[nix]: https://nixos.org/manual/nix/stable
|
||||
[nixos]: https://nixos.org/manual/nixos/stable
|
||||
[home-manager]: https://nix-community.github.io/home-manager
|
||||
[flakes]: https://nixos.wiki/wiki/Flakes
|
||||
[core]: https://github.com/nrdxp/nixflk
|
||||
[community]: https://github.com/nrdxp/nixflk/tree/community
|
||||
[direnv]: https://direnv.net
|
||||
[home-manager]: https://github.com/nix-community/home-manager
|
||||
[nix-command]: https://nixos.wiki/wiki/Nix_command
|
||||
[nixFlakes]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/package-management/nix/default.nix#L211
|
||||
[NixOS]: https://nixos.org
|
||||
[nixpkgs]: https://github.com/NixOS/nixpkgs
|
||||
[nur]: https://github.com/nix-community/NUR
|
||||
[wiki]: https://nixos.wiki/wiki/Flakes
|
||||
[thumb]: https://img.youtube.com/vi/UeBX7Ide5a0/hqdefault.jpg
|
||||
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0
|
||||
[nur]: https://github.com/nix-community/NUR
|
||||
|
|
26
SUMMARY.md
Normal file
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
|
||||
If making a change to core, or adding a feature, please be sure to update the
|
||||
relevant docs. Each directory contains its own README.md, which will
|
||||
automatically be pulled into the [mdbook](https://flk.nrdxp.dev). The book is
|
||||
rendered on every change, so the docs should always be up to date.
|
||||
|
||||
|
||||
## Community PRs
|
||||
While much of your work in this template may be idiosyncratic in nature. Anything
|
||||
that might be generally useful to the broader NixOS community can be synced to
|
||||
the `template` branch to provide a host of useful NixOS configurations available
|
||||
"out of the box". If you wish to contribute such an expression please follow
|
||||
these guidelines:
|
||||
the `community` branch to provide a host of useful NixOS configurations available
|
||||
"out of the box".
|
||||
|
||||
# Style
|
||||
If you wish to contribute please follow these guidelines:
|
||||
|
||||
* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
|
||||
includes a pre-commit hook that does this for you.
|
10
doc/flk/get.md
Normal file
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
|
||||
specialArgs = {
|
||||
unstableModulesPath = "${master}/nixos/modules";
|
||||
overrideModulesPath = "${override}/nixos/modules";
|
||||
hardware = nixos-hardware.nixosModules;
|
||||
};
|
||||
}
|
||||
|
|
|
@ -7,7 +7,7 @@
|
|||
"nixos"
|
||||
],
|
||||
"nixos-unstable": [
|
||||
"master"
|
||||
"override"
|
||||
],
|
||||
"pre-commit-hooks-nix": "pre-commit-hooks-nix"
|
||||
},
|
||||
|
@ -93,7 +93,7 @@
|
|||
"type": "github"
|
||||
}
|
||||
},
|
||||
"master": {
|
||||
"override": {
|
||||
"locked": {
|
||||
"lastModified": 1612717294,
|
||||
"narHash": "sha256-V3j1rA4a3Lzf5pdbFHzs9jUcOKB91MFO3X8nMY+lK5c=",
|
||||
|
@ -174,7 +174,7 @@
|
|||
"devshell": "devshell",
|
||||
"flake-utils": "flake-utils",
|
||||
"home": "home",
|
||||
"master": "master",
|
||||
"override": "override",
|
||||
"nixos": "nixos",
|
||||
"nixos-hardware": "nixos-hardware",
|
||||
"nur": "nur"
|
||||
|
|
|
@ -3,9 +3,7 @@
|
|||
|
||||
inputs =
|
||||
{
|
||||
# Once desired, bump master's locked revision:
|
||||
# nix flake update --update-input master
|
||||
master.url = "nixpkgs/master";
|
||||
override.url = "nixpkgs/master";
|
||||
nixos.url = "nixpkgs/release-20.09";
|
||||
home.url = "github:nix-community/home-manager/release-20.09";
|
||||
home.inputs.nixpkgs.follows = "nixos";
|
||||
|
@ -14,7 +12,7 @@
|
|||
nixos-hardware.url = "github:nixos/nixos-hardware";
|
||||
ci-agent.url = "github:hercules-ci/hercules-ci-agent";
|
||||
ci-agent.inputs.nixos-20_09.follows = "nixos";
|
||||
ci-agent.inputs.nixos-unstable.follows = "master";
|
||||
ci-agent.inputs.nixos-unstable.follows = "override";
|
||||
};
|
||||
|
||||
outputs =
|
||||
|
@ -22,7 +20,7 @@
|
|||
, ci-agent
|
||||
, home
|
||||
, nixos
|
||||
, master
|
||||
, override
|
||||
, flake-utils
|
||||
, nur
|
||||
, devshell
|
||||
|
|
43
hosts/README.md
Normal file
43
hosts/README.md
Normal file
|
@ -0,0 +1,43 @@
|
|||
# Hosts
|
||||
|
||||
Nix flakes contain an output called `nixosConfigurations` declaring an
|
||||
attribute set of valid NixOS systems. To simplify the management and creation
|
||||
of these hosts, nixflk automatically imports every _.nix_ file inside this
|
||||
directory to the mentioned attribute set, applying the projects defaults to
|
||||
each. The only hard requirement is that the file contain a valid NixOS module.
|
||||
|
||||
As an example, a file `hosts/system.nix` will be available via the flake
|
||||
output `nixosConfigurations.system`. You can have as many hosts as you want
|
||||
and all of them will be automatically imported based on their name.
|
||||
|
||||
For each host, the configuration automatically sets the `networking.hostName`
|
||||
attribute to the name of the file minus the _.nix_ extension. This is for
|
||||
convenience, since `nixos-rebuild` automatically searches for a configuration
|
||||
matching the current systems hostname if one is not specified explicitly.
|
||||
|
||||
It is recommended that the host modules only contain configuration information
|
||||
specific to a particular piece of hardware. Anything reusable across machines
|
||||
is best saved for [profile modules](../profiles).
|
||||
|
||||
This is a good place to import sets of profiles, called [suites](../suites),
|
||||
that you intend to use on your machine.
|
||||
|
||||
Additionally, this is the perfect place to import anything you might need from
|
||||
the [nixos-hardware][nixos-hardware] repository.
|
||||
|
||||
## Example
|
||||
|
||||
hosts/librem.nix:
|
||||
```nix
|
||||
{ suites, hardware, ... }:
|
||||
{
|
||||
imports = suites.laptop ++ [ hardware.purism-librem-13v3 ];
|
||||
|
||||
boot.loader.systemd-boot.enable = true;
|
||||
boot.loader.efi.canTouchEfiVariables = true;
|
||||
|
||||
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
|
||||
}
|
||||
```
|
||||
|
||||
[nixos-hardware]: https://github.com/NixOS/nixos-hardware
|
|
@ -1,11 +1,12 @@
|
|||
{ lib
|
||||
{ extern
|
||||
, home
|
||||
, lib
|
||||
, nixos
|
||||
, master
|
||||
, nixos-hardware
|
||||
, override
|
||||
, pkgs
|
||||
, self
|
||||
, system
|
||||
, extern
|
||||
, ...
|
||||
}:
|
||||
let
|
||||
|
@ -24,37 +25,64 @@ let
|
|||
let
|
||||
core = import ../profiles/core;
|
||||
|
||||
modOverrides = { config, unstableModulesPath, ... }:
|
||||
modOverrides = { config, overrideModulesPath, ... }:
|
||||
let
|
||||
unstable = import ../unstable;
|
||||
inherit (unstable) modules disabledModules;
|
||||
overrides = import ../overrides;
|
||||
inherit (overrides) modules disabledModules;
|
||||
in
|
||||
{
|
||||
disabledModules = modules ++ disabledModules;
|
||||
imports = map
|
||||
(path: "${unstableModulesPath}/${path}")
|
||||
(path: "${overrideModulesPath}/${path}")
|
||||
modules;
|
||||
};
|
||||
|
||||
global = {
|
||||
global =
|
||||
let
|
||||
inherit (lock) nodes;
|
||||
|
||||
lock = builtins.fromJSON (builtins.readFile ../flake.lock);
|
||||
in
|
||||
{
|
||||
home-manager.useGlobalPkgs = true;
|
||||
home-manager.useUserPackages = true;
|
||||
|
||||
hardware.enableRedistributableFirmware = lib.mkDefault true;
|
||||
|
||||
networking.hostName = hostName;
|
||||
|
||||
nix.nixPath = [
|
||||
"nixos-unstable=${master}"
|
||||
"nixos=${nixos}"
|
||||
"nixpkgs=${nixos}"
|
||||
"nixos-config=${self}/compat/nixos"
|
||||
"home-manager=${home}"
|
||||
];
|
||||
|
||||
nixpkgs = { inherit pkgs; };
|
||||
|
||||
nix.registry = {
|
||||
master.flake = master;
|
||||
nixflk.flake = self;
|
||||
nixpkgs.flake = nixos;
|
||||
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;
|
||||
|
|
|
@ -83,11 +83,11 @@ in
|
|||
(system:
|
||||
let
|
||||
extern = import ../extern { inherit inputs; };
|
||||
unstable = pkgImport inputs.master [ ] system;
|
||||
overrides = (import ../unstable).packages;
|
||||
overridePkgs = pkgImport inputs.override [ ] system;
|
||||
overridesOverlay = (import ../overrides).packages;
|
||||
|
||||
overlays = [
|
||||
(overrides unstable)
|
||||
(overridesOverlay overridePkgs)
|
||||
self.overlay
|
||||
(final: prev: {
|
||||
lib = (prev.lib or { }) // {
|
||||
|
@ -173,7 +173,7 @@ in
|
|||
cachixAttrs = { inherit cachix; };
|
||||
|
||||
# modules
|
||||
moduleList = import ../modules/list.nix;
|
||||
moduleList = import ../modules/module-list.nix;
|
||||
modulesAttrs = pathsToImportedAttrs moduleList;
|
||||
|
||||
in
|
||||
|
|
79
modules/README.md
Normal file
79
modules/README.md
Normal file
|
@ -0,0 +1,79 @@
|
|||
# Modules
|
||||
The modules directory is a replica of nixpkg's NixOS [modules][nixpkgs-modules]
|
||||
, and follows the same semantics. This allows for trivial upstreaming into
|
||||
nixpkgs proper once your module is sufficiently stable.
|
||||
|
||||
All modules linked in _module-list.nix_ are automatically exported via
|
||||
`nixosModules.<file-basename>`, and imported into all [hosts](../hosts).
|
||||
|
||||
|
||||
> ##### _Note:_
|
||||
> This is reserved for declaring brand new module options. If you just want to
|
||||
> declare a coherent configuration of already existing and related NixOS options
|
||||
> , use [profiles](../profiles) instead.
|
||||
|
||||
## Semantics
|
||||
In case you've never written a module for nixpkgs before, here is a brief
|
||||
outline of the process.
|
||||
|
||||
### Declaration
|
||||
modules/services/service-category/my-service.nix:
|
||||
```nix
|
||||
{ config, lib, ... }:
|
||||
let
|
||||
cfg = config.services.myService;
|
||||
in
|
||||
{
|
||||
options.services.myService = {
|
||||
enable = lib.mkEnableOption "Description of my new service.";
|
||||
|
||||
# additional options ...
|
||||
};
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
# implementation ...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Import
|
||||
modules/module-list.nix:
|
||||
```nix
|
||||
[
|
||||
./services/service-category/my-service.nix
|
||||
]
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Internal
|
||||
profiles/profile-category/my-profile.nix:
|
||||
```nix
|
||||
{ ... }:
|
||||
{
|
||||
services.MyService.enable = true;
|
||||
}
|
||||
```
|
||||
|
||||
### External
|
||||
flake.nix:
|
||||
```nix
|
||||
{
|
||||
# inputs omitted
|
||||
|
||||
outputs = { self, nixflk, nixpkgs, ... }: {
|
||||
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
|
||||
system = "...";
|
||||
|
||||
modules = [
|
||||
nixflk.nixosModules.my-service
|
||||
({ ... }: {
|
||||
services.MyService.enable = true;
|
||||
})
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules
|
25
overlays/README.md
Normal file
25
overlays/README.md
Normal file
|
@ -0,0 +1,25 @@
|
|||
# Overlays
|
||||
Writing overlays is a common occurence when using a NixOS system. Therefore,
|
||||
we want to keep the process as simple and straightforward as possible.
|
||||
|
||||
Any _.nix_ files declared in this directory will be assumed to be a valid
|
||||
overlay, and will be automatically imported into all [hosts](../hosts), and
|
||||
exported via `overlays.<file-basename>` _as well as_
|
||||
`packages.<system>.<pkgName>` (for valid systems), so all you have to do is
|
||||
write it.
|
||||
|
||||
## Example
|
||||
overlays/kakoune.nix:
|
||||
```nix
|
||||
final: prev: {
|
||||
kakoune = prev.kakoune.override {
|
||||
configure.plugins = with final.kakounePlugins; [
|
||||
(kak-fzf.override { fzf = final.skim; })
|
||||
kak-auto-pairs
|
||||
kak-buffers
|
||||
kak-powerline
|
||||
kak-vertical-selection
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
46
overrides/README.md
Normal file
46
overrides/README.md
Normal file
|
@ -0,0 +1,46 @@
|
|||
# Overrides
|
||||
By default, the NixOS systems are based on the latest release. While it is
|
||||
trivial to change this to nixos-unstable or any other branch of nixpkgs by
|
||||
changing the flake url, sometimes all we want is a single package from another
|
||||
branch.
|
||||
|
||||
This is what the overrides are for. By default, they are pulled directly from
|
||||
nixpkgs/master, but you can change the `override` flake input url to
|
||||
nixos-unstable, or even a specific sha revision.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
### Packages
|
||||
The override packages are defined as a regular overlay with an extra arguement
|
||||
`pkgs`. This refers to the packages built from the `override` flake.
|
||||
|
||||
Pulling the manix package from the override flake:
|
||||
```nix
|
||||
{
|
||||
packages = pkgs: final: prev: {
|
||||
inherit (pkgs) manix;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Modules
|
||||
|
||||
You can also pull modules from override. Simply specify their path relative to
|
||||
the nixpkgs [modules][nixpkgs-modules] directory. The old version will be added
|
||||
to `disabledModules` and the new version imported into the configuration.
|
||||
|
||||
Pulling the zsh module from the override flake:
|
||||
```nix
|
||||
{
|
||||
modules = [ "programs/zsh/zsh.nix" ];
|
||||
}
|
||||
```
|
||||
|
||||
> ##### _Note:_
|
||||
> Sometimes a modules name will change from one branch to another. This is what
|
||||
> the `disabledModules` list is for. If the module name changes, the old
|
||||
> version will not automatically be disabled, so simply put it's old name in
|
||||
> this list to disable it.
|
||||
|
||||
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules
|
|
@ -1,11 +1,12 @@
|
|||
# override defaults to nixpkgs/master
|
||||
{
|
||||
# modules to pull from master, stable version is automatically disabled
|
||||
# modules to pull from override, stable version is automatically disabled
|
||||
modules = [ ];
|
||||
|
||||
# if a modules name changed in master, add the old name here
|
||||
# if a modules name changed in override, add the old name here
|
||||
disabledModules = [ ];
|
||||
|
||||
# packages pulled from master
|
||||
# packages pulled from override
|
||||
packages = pkgs: final: prev: {
|
||||
inherit (pkgs)
|
||||
dhall
|
59
pkgs/README.md
Normal file
59
pkgs/README.md
Normal file
|
@ -0,0 +1,59 @@
|
|||
# Packages
|
||||
Similar to [modules](../modules), the pkgs directory mirrors the upstream
|
||||
[nixpkgs/pkgs][pkgs], and for the same reason; if you ever want to upstream
|
||||
your package, it's as simple as dropping it into the nixpkgs/pkgs directory.
|
||||
|
||||
The only minor difference is that, instead of adding the `callPackage` call to
|
||||
`all-packages.nix`, you just add it the the _default.nix_ in this directory,
|
||||
which is defined as a simple overlay.
|
||||
|
||||
This overlay is set as the default `overlay` output attribute for the flake.
|
||||
And all the packages are exported via `packages.<system>.<pkg-name>`, for all
|
||||
the supported systems listed in the package's `meta.platforms` attribute.
|
||||
|
||||
And, as usual, every package in the overlay is also available to any NixOS
|
||||
[host](../hosts).
|
||||
|
||||
## Example
|
||||
pkgs/development/libraries/libinih/default.nix:
|
||||
```nix
|
||||
{ stdenv, meson, ninja, fetchFromGitHub, ... }:
|
||||
let version = "r50";
|
||||
in
|
||||
stdenv.mkDerivation {
|
||||
pname = "libinih";
|
||||
inherit version;
|
||||
|
||||
src = fetchFromGitHub {
|
||||
owner = "benhoyt";
|
||||
repo = "inih";
|
||||
rev = "${version}";
|
||||
hash = "sha256-GF+TVEysaXJxSBBjMsTr2IQvRKlzdEu3rlPQ88PE3nI=";
|
||||
};
|
||||
|
||||
buildInputs = [ meson ninja ];
|
||||
|
||||
mesonFlags = ''
|
||||
-Ddefault_library=shared
|
||||
-Ddistro_install=true
|
||||
'';
|
||||
|
||||
meta = with stdenv.lib; {
|
||||
description = "Simple .INI file parser in C";
|
||||
homepage = "https://github.com/benhoyt/inih";
|
||||
maintainers = [ maintainers.nrdxp ];
|
||||
license = licenses.bsd3;
|
||||
platforms = platforms.all;
|
||||
inherit version;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
pkgs/default.nix:
|
||||
```nix
|
||||
final: prev: {
|
||||
libinih = prev.callPackage ./development/libraries/libinih { };
|
||||
}
|
||||
```
|
||||
|
||||
[pkgs]: https://github.com/NixOS/nixpkgs/tree/master/pkgs
|
48
profiles/README.md
Normal file
48
profiles/README.md
Normal file
|
@ -0,0 +1,48 @@
|
|||
# Profiles
|
||||
Profiles are simply NixOS modules which contain generic expressions suitable
|
||||
for any host. A good example is the configuration for a text editor, or
|
||||
window manager. If you need some concrete examples, just checkout the
|
||||
community [branch](https://github.com/nrdxp/nixflk/tree/community/profiles).
|
||||
|
||||
## Constraints
|
||||
For the sake of consistency, there are a few minor constraints. First of all, a
|
||||
profile should always be defined in a `default.nix`, and it should always be a
|
||||
a function taking a single attribute set as an argument, and returning a NixOS
|
||||
module which does not define any new module options. If you need to make new
|
||||
module option declarations, just use [modules](../modules).
|
||||
|
||||
These restrictions help simplify the import logic used to pass profles to
|
||||
[suites](../suites).
|
||||
|
||||
### Example
|
||||
#### Correct ✔
|
||||
profiles/develop/default.nix:
|
||||
```nix
|
||||
{ ... }:
|
||||
{
|
||||
programs.zsh.enable = true;
|
||||
}
|
||||
```
|
||||
|
||||
#### Incorrect ❌
|
||||
profiles/develop.nix:
|
||||
```nix
|
||||
{
|
||||
options = {};
|
||||
}
|
||||
```
|
||||
|
||||
## Subprofiles
|
||||
Profiles can also define subprofiles. They follow the same constraints outlined
|
||||
above. A good top level profile should be a high level concern, such a your
|
||||
personal development environment, and the subprofiles should be more concrete
|
||||
program configurations such as your text editor, and shell configs. This way,
|
||||
you can either pull in the whole development profile, or pick and choose
|
||||
individual programs.
|
||||
|
||||
## Conclusion
|
||||
Profiles are the most important concept in nixflk. They allow us to keep our
|
||||
nix expressions self contained and modular. This way we can maximize reuse
|
||||
while minimizing boilerplate. Always strive to keep your profiles as generic
|
||||
and modular as possible. Anything machine specific belongs in your
|
||||
[host](../hosts) files.
|
|
@ -65,8 +65,8 @@ in
|
|||
nr = "np remove";
|
||||
ns = "n search --no-update-lock-file";
|
||||
nf = "n flake";
|
||||
nepl = "n repl '<nixos>'";
|
||||
srch = "ns nixpkgs";
|
||||
nepl = "n repl '<nixpkgs>'";
|
||||
srch = "nsni";
|
||||
nrb = ifSudo "sudo nixos-rebuild";
|
||||
mn = ''
|
||||
manix "" | grep '^# ' | sed 's/^# \(.*\) (.*/\1/;s/ (.*//;s/^# //' | sk --preview="manix '{}'" | xargs manix
|
||||
|
@ -93,7 +93,20 @@ in
|
|||
dn = ifSudo "s systemctl stop";
|
||||
jtl = "journalctl";
|
||||
|
||||
};
|
||||
} // lib.mapAttrs'
|
||||
(n: v:
|
||||
let
|
||||
prefix = lib.concatStrings (lib.take 2 (lib.stringToCharacters n));
|
||||
ref = from:
|
||||
if from ? ref
|
||||
then "ns ${from.id}/${from.ref}"
|
||||
else "ns ${from.id}";
|
||||
in
|
||||
lib.nameValuePair
|
||||
"ns${prefix}"
|
||||
(ref v.from)
|
||||
)
|
||||
config.nix.registry;
|
||||
|
||||
};
|
||||
|
||||
|
|
1
secrets/.gitattributes
vendored
1
secrets/.gitattributes
vendored
|
@ -1,2 +1,3 @@
|
|||
* filter=git-crypt diff=git-crypt
|
||||
.gitattributes !filter !diff
|
||||
README.md !filter !diff
|
||||
|
|
18
secrets/README.md
Normal file
18
secrets/README.md
Normal file
|
@ -0,0 +1,18 @@
|
|||
# Secrets
|
||||
Secrets are managed using [git-crypt][git-crypt] so you can keep your flake in
|
||||
a public repository like GitHub without exposing your password or other
|
||||
sensitive data.
|
||||
|
||||
By default, everything in the secrets folder is automatically encrypted. Just
|
||||
be sure to run `git-crypt init` before putting anything in here.
|
||||
|
||||
> ##### _Note:_
|
||||
> Currently, there is [no mechanism][secrets-issue] in nix to deploy secrets
|
||||
> within the nix/store so, if they end up in the nix/store after deployment, they
|
||||
> will be world readable on that machine.
|
||||
>
|
||||
> The author of nixflk intends to implement a workaround for this situation in
|
||||
> the near future, but for the time being, simple be aware of this.
|
||||
|
||||
[git-crypt]: https://github.com/AGWA/git-crypt
|
||||
[secrets-issue]: https://github.com/NixOS/nix/issues/8
|
|
@ -23,7 +23,6 @@ pkgs.devshell.mkShell {
|
|||
nixos-install
|
||||
nixos-generate-config
|
||||
nixos-enter
|
||||
mdbook
|
||||
];
|
||||
|
||||
env = { inherit name; };
|
||||
|
|
24
suites/README.md
Normal file
24
suites/README.md
Normal file
|
@ -0,0 +1,24 @@
|
|||
# Suites
|
||||
Suites provide a mechanism for users to easily combine and name collecitons of
|
||||
profiles. For good examples, check out the suites defined in the community
|
||||
[branch](https://github.com/nrdxp/nixflk/blob/community/suites/default.nix).
|
||||
|
||||
In the future, we will use suites as a mechanism for deploying various machine
|
||||
types which don't depend on hardware, such as vm's and containers.
|
||||
|
||||
## Definition
|
||||
```nix
|
||||
rec {
|
||||
workstation = [ profiles.develop profiles.graphical users.nixos ];
|
||||
mobileWS = workstation ++ [ profiles.laptop ];
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
`hosts/my-laptop.nix`:
|
||||
```nix
|
||||
{ suites, ... }:
|
||||
{
|
||||
imports = suites.mobileWS;
|
||||
}
|
||||
```
|
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 a new issue