doc: new mdbook documentation

This commit is contained in:
Timothy DeHerrera 2021-02-13 19:38:20 -07:00
parent 4e582b1ff5
commit bf34d2071f
No known key found for this signature in database
GPG key ID: 8985725DB5B0C122
34 changed files with 627 additions and 147 deletions

26
.github/workflows/mdbook_docs.yml vendored Normal file
View file

@ -0,0 +1,26 @@
name: Deploy Docs to GitHub Pages
on:
push:
branches:
- doc
jobs:
deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: 'latest'
- run: mdbook build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: gh-pages
publish_dir: ./book

1
.gitignore vendored
View file

@ -2,3 +2,4 @@ result
up up
hosts/up-* hosts/up-*
.direnv .direnv
book

View file

@ -1,18 +0,0 @@
# Pull Requests
While much of your work in this template may be idiosyncratic in nature. Anything
that might be generally useful to the broader NixOS community can be synced to
the `template` branch to provide a host of useful NixOS configurations available
"out of the box". If you wish to contribute such an expression please follow
these guidelines:
* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
includes a pre-commit hook that does this for you.
* The commit message follows the same semantics as [nixpkgs][nixpkgs].
* You can use a `#` symbol to specify ambiguities. For example,
`develop#zsh: <rest of commit message>` would tell me that your updating the
`zsh` subprofile living under the `develop` profile.
[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
[nixpkgs]: https://github.com/NixOS/nixpkgs

105
DOC.md
View file

@ -1,105 +0,0 @@
## Hosts
Module declarations dependant on particular machines should be stored in the
[hosts](hosts) directory. Every file in this directory will be added automatically
to the the `nixosConfigurations` flake output and thus becomes deployable via
`nixos-rebuild` and `flk`.
See [`hosts/default.nix`](hosts/default.nix) for the implementation.
## Profiles
A profile is any directory under [profiles](profiles) containing a `default.nix`
defining a function that returns a valid NixOS module, with the added restriction
that no new declarations to the `options` _or_ `config` attributes are allowed
(use [modules](modules) instead). Their purpose is to provide abstract
expressions suitable for reuse by multiple deployments. They are perhaps _the_
key mechanism by which we keep this repo maintainable.
Profiles can have subprofiles which are themselves just profiles that live under
another. There's no hard rule that everything in the folder must be imported by
its `default.nix`, so you can also store relevant code that is useful but not
wanted by default in, say, an `alt.nix`. Importantly, every subdirectory in a
profile should be independent of its parent. i.e:
```nix
{
# importing `profile` without implicitly importing `some`
imports = [ ./profiles/some/profile ];
}
```
It is okay for profiles to depend on other profiles so long as they are
explicitly loaded via `imports`.
## Suites
[Suites](./suites/default.nix) are simple collections of profiles that can be
directly imported from any host like so:
```
{ suites, ... }:
{
imports = suites.mySuite;
}
```
You can declare any combination of users and profiles that you wish, providing
a nice abstraction, free from the idiosyncratic concerns of specific hardware.
## Users
User declarations belong in the `users` directory.
These are actually just a special case of [profiles](#profiles) attached to
a particular interactive user. Its primarily for declarations to
`users.users.<new-user>` where `<new-user>.isNormalUser` is true.
This is a convenient place to import your profiles such that a particular user
always has a reliable stack. Also [user profiles](./users/profiles) are
available to create reusable configs across different users.
For convenience, [home-manager][home-manager] is available automatically for
home directory setup and should only be used from this directory.
## Secrets
Anything you wish to keep encrypted goes in the `secrets` directory, which is
created on first entering a `nix-shell`.
Be sure to run `git crypt init`, before committing anything to this directory.
Be sure to check out git-crypt's [documentation](https://github.com/AGWA/git-crypt)
if your not familiar. The filter is already set up to encrypt everything in this
folder by default.
To keep [profiles](profiles) reusable across configurations, secrets should
only be imported from the `users` or [`hosts`](hosts) directory.
## Cachix
When using:
```
cachix use <your-cachix>
```
A file with be created in `/etc/nixos/cachix/your-cachix.nix`. Simply add this
file to git, and it will be exported so others can use your binary cache
directly from this flake via `nixosModules.cachix.<your-cachix>`.
## Modules, Packages and Overlays
All expressions in both [modules/list.nix](modules/list.nix) and
[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the
repo. They are additionally included in the `nixosModules` and `overlay` flake
outputs, respectively. Packages are automatically included in the `packages`
output as well.
The directory structure is identical to nixpkgs to provide a kind of staging area
for any modules or packages we might be wanting to merge there later. If your not
familiar or can't be bothered, simply dropping a valid nix file and pointing the
`default.nix` to it, is all that's really required.
As for overlays, they should be defined in the [overlays](overlays) directory.
They will be automatically pulled in for use by all configurations. Nix command
line tools will be able to read overlays from here as well since it is set as
`nixpkgs-overlays` in `NIX_PATH`. And of course they will be exported via the
flake output `overlays` as well.
If you wish to use an overlay from an external flake, simply add it to the
`externOverlays` list in the `let` block of the `outputs` attribute in
[flake.nix](flake.nix). Same for external modules, add them to `externModules`.
[home-manager]: https://github.com/nix-community/home-manager

19
SUMMARY.md Normal file
View file

@ -0,0 +1,19 @@
# Summary
- [Introduction](./doc/introduction.md)
- [Quick Start](./doc/start/index.md)
- [ISO](./doc/start/iso.md)
- [From NixOS](./doc/start/from-nixos.md)
- [Layout](./doc/layout.md)
- [Cachix](./cachix/README.md)
- [Extern](./extern/README.md)
- [Hosts](./hosts/README.md)
- [Modules](./modules/README.md)
- [Overlays](./overlays/README.md)
- [Overrides](./overrides/README.md)
- [Packages](./pkgs/README.md)
- [Profiles](./profiles/README.md)
- [Secrets](./secrets/README.md)
- [Suites](./suites/README.md)
- [Users](./users/README.md)
- [flk command](./doc/flk/index.md)

9
book.toml Normal file
View 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
View 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
View file

@ -0,0 +1 @@
book

1
doc/flk/index.md Normal file
View file

@ -0,0 +1 @@
# flk command

33
doc/introduction.md Normal file
View file

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

4
doc/layout.md Normal file
View 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
View 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
View file

@ -0,0 +1,38 @@
# Quick Start
The only dependency is nix, so make sure you have it [installed][install-nix].
## Get the Template
Here is a snippet that will get you the template without the git history:
```sh
nix-shell https://github.com/nrdxp/nixflk/archive/core.tar.gz -A shell \
--run "flk get core"
cd flk
nix-shell
git init
git add .
git commit -m init
cachix use nrdxp
```
This will place you in a new folder named `flk` with git initialized, and a
nix-shell that provides all the dependencies, including the unstable nix
version required.
In addition, the [binary cache](../../cachix) is added for faster deployment.
> ##### _Notes:_
> - You can change `core` to [`community`](../introduction.md#community-profiles)
> in the call to `flk get`
> - Flakes ignore files that have not been added to git, so be sure to stage new
> files before building the system.
## Next Steps:
- [Make installable ISO](./iso.md)
- [Already on NixOS](./from-nixos.md)
[install-nix]: https://nixos.org/manual/nix/stable/#sect-multi-user-installation

11
doc/start/iso.md Normal file
View 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
View 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
View file

@ -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;
}; };
} }

View file

@ -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"

View file

@ -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
View 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

View file

@ -1,6 +1,6 @@
{ lib { lib
, nixos , nixos
, master , override
, nixos-hardware , nixos-hardware
, pkgs , pkgs
, self , self
@ -24,15 +24,15 @@ let
let let
core = import ../profiles/core; core = import ../profiles/core;
modOverrides = { config, unstableModulesPath, ... }: modOverrides = { config, overrideModulesPath, ... }:
let let
unstable = import ../unstable; overrides = import ../overrides;
inherit (unstable) modules disabledModules; inherit (overrides) modules disabledModules;
in in
{ {
disabledModules = modules ++ disabledModules; disabledModules = modules ++ disabledModules;
imports = map imports = map
(path: "${unstableModulesPath}/${path}") (path: "${overrideModulesPath}/${path}")
modules; modules;
}; };
@ -44,7 +44,7 @@ let
networking.hostName = hostName; networking.hostName = hostName;
nix.nixPath = [ nix.nixPath = [
"nixos-unstable=${master}" "nixos-unstable=${override}"
"nixos=${nixos}" "nixos=${nixos}"
"nixpkgs=${nixos}" "nixpkgs=${nixos}"
]; ];
@ -52,7 +52,6 @@ let
nixpkgs = { inherit pkgs; }; nixpkgs = { inherit pkgs; };
nix.registry = { nix.registry = {
master.flake = master;
nixflk.flake = self; nixflk.flake = self;
nixpkgs.flake = nixos; nixpkgs.flake = nixos;
}; };

View file

@ -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
View 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

View file

25
overlays/README.md Normal file
View 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
View 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

View file

@ -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
View 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
View 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.

View file

@ -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
View 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

View file

@ -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
View file

@ -0,0 +1,24 @@
# Suites
Suites provide a mechanism for users to easily combine and name collecitons of
profiles. For good examples, check out the suites defined in the community
[branch](https://github.com/nrdxp/nixflk/blob/community/suites/default.nix).
In the future, we will use suites as a mechanism for deploying various machine
types which don't depend on hardware, such as vm's and containers.
## Definition
```nix
rec {
workstation = [ profiles.develop profiles.graphical users.nixos ];
mobileWS = workstation ++ [ profiles.laptop ];
}
```
## Usage
`hosts/my-laptop.nix`:
```nix
{ suites, ... }:
{
imports = suites.mobileWS;
}
```

51
users/README.md Normal file
View 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