doc: finish flk reference

This commit is contained in:
Timothy DeHerrera 2021-02-14 17:41:15 -07:00
parent 3a735ce70b
commit 0405949ec6
No known key found for this signature in database
GPG key ID: 8985725DB5B0C122
15 changed files with 138 additions and 259 deletions

256
README.md
View file

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

View file

@ -1,6 +1,6 @@
# Summary
- [Introduction](./doc/introduction.md)
- [Introduction](./README.md)
- [Quick Start](./doc/start/index.md)
- [ISO](./doc/start/iso.md)
- [From NixOS](./doc/start/from-nixos.md)
@ -16,4 +16,11 @@
- [Secrets](./secrets/README.md)
- [Suites](./suites/README.md)
- [Users](./users/README.md)
- [flk command](./doc/flk/index.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)

1
doc/CONTRIBUTING.md Normal file
View file

@ -0,0 +1 @@
# Contributing

26
doc/README.md Normal file
View file

@ -0,0 +1,26 @@
# 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 `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.
* The commit message follows the same semantics as [nixpkgs][nixpkgs].
* You can use a `#` symbol to specify ambiguities. For example,
`develop#zsh: <rest of commit message>` would tell me that your updating the
`zsh` subprofile living under the `develop` profile.
[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
[nixpkgs]: https://github.com/NixOS/nixpkgs

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

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

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

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

View file

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

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

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

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

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

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

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

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

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

View file

@ -1,33 +0,0 @@
# Introduction
Nixflk is a template which grants a simple way to use, deploy and manage
[NixOS][nixos] systems for personal and productive use. It does this by
providing a sane repository structure, integrating several popular projects
like [home-manager][home-manager], setting clear guidelines, offering useful
conveniences, and eliminating boilerplate so you can focus on deploying your
systems.
## Community Profiles
There are two branches from which to choose: [core][core] and
[community][community]. The community branch builds on core and includes
several ready-made profiles for discretionary use.
Every package and NixOS profile declared in community is uploaded to
[cachix](../cachix), so everything provided is available without building
anything. This is especially useful for the packages that are
[overridden](../overrides) from master, as without the cache, rebuilds are
quite frequent.
### ⚠ Advisory
Nixflk leverages the [flakes][flakes] feature available via an _experimental_
branch of [nix][nix]. Until nix 3.0 is released, this project should be
considered unstable.
# License
Nixflk is licensed under the [MIT License](https://mit-license.org).
[nix]: https://nixos.org/manual/nix/stable
[nixos]: https://nixos.org/manual/nixos/stable
[home-manager]: https://nix-community.github.io/home-manager
[flakes]: https://nixos.wiki/wiki/Flakes
[core]: https://github.com/nrdxp/nixflk
[community]: https://github.com/nrdxp/nixflk/tree/community

View file

@ -25,7 +25,7 @@ version required.
In addition, the [binary cache](../../cachix) is added for faster deployment.
> ##### _Notes:_
> - You can change `core` to [`community`](../introduction.md#community-profiles)
> - 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.

View file

@ -27,7 +27,7 @@ the [nixos-hardware][nixos-hardware] repository.
## Example
`hosts/librem.nix`:
hosts/librem.nix:
```nix
{ suites, hardware, ... }:
{

6
theme/highlight.js Normal file

File diff suppressed because one or more lines are too long