dusk/ark
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

DOC.md: split off from README.md

Browse Source 
Keep the README.md lean and use DOC.md for more detailed explanations. While
revising user documentation, a default `nixos` user profile was created, which
serves as a goood base example.
This commit is contained in:
Timothy DeHerrera 2020-01-10 23:49:18 -07:00
parent 9b64b50ee8
commit e078e7a229
No known key found for this signature in database
GPG Key ID: 8985725DB5B0C122
7 changed files with 154 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
DOC.md Normal file
View File

@ -0,0 +1,99 @@
## 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 `rebuild`.
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 valid NixOS module, with the added restriction that no new
delclarations 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`.
Optionally, you may choose to export your profiles via the flake output. If
you include it in the list defined in [profiles/list.nix](profiles/list.nix),
it will be available to other flakes via `nixosModules.profiles`.
## 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.
For convenience, [home-manager][home-manager] is available automatically for
home directory setup and should only be used from this directory.
## Lib
The [lib](lib) directory contains a file `utils.nix` which is an attribute set
meant to consist mainly of utility functions you might want to write and use
throughout the configuration. They are available via a new `usr` attribute
passed to every NixOS module, eg:
```
# hosts/some-host.nix
{ usr, ... }:
let
inherit (usr) utils;
data = utils.myFunction # ...
in
{
# NixOS configuration
}
```
## 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.
## 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 can manually be added to [flake.nix](flake.nix)
for inclusion 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.
[home-manager]: https://github.com/rycee/home-manager

123
README.md
View File

@ -3,8 +3,9 @@ A NixOS configuration template using the experimental [flakes][rfc] 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.
Flakes are still an experimental feature, but once they finally get merged
even more will become possible, i.e. [nixops](https://nixos.org/nixops)
Please be advised, flakes are still an experimental feature.
Presuming they get [merged][rfc], even more will become possible, e.g.
[nixops](https://nixos.org/nixops)/[disnix](https://nixos.org/disnix)
support.
#### Flake Talk:
@ -22,6 +23,9 @@ nix-shell
git checkout -b $new_branch template
# set a root password, preferably with `hashedPassword`
$EDITOR ./users/root/default.nix
# generate hardware config
nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
@ -35,7 +39,6 @@ nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
# any ./profiles you may wish to try out.
$EDITOR ./hosts/${new_host}.nix
# backup existing config and ensure configuration lives in expected location
mv /etc/nixos /etc/nixos.old
ln -s $PWD /etc/nixos
@ -52,15 +55,13 @@ git add ./hosts/${new_host}.nix
# This will be run as root.
rebuild $new_host switch
# you may wish to start by creating a user
mkdir users/new-user && $EDITOR users/new-user/default.nix
```
Best to read the [doc](DOC.md), in order to understand the impetus behind
the directory structure.
And now you should be ready to start writing your nix configuration or import
your current one. Review the [structure](#structure) below on how to build your
layout. And be sure to update the [locale.nix](local/locale.nix) for your
region.
You can always checkout my personal branch for more concrete examples.
## Additional Capabilities
@ -72,7 +73,8 @@ rebuild iso
nix profile install ".#packages.x86_64-linux.myPackage"
```
this flake exports multiple outputs for use in other flakes:
this flake exports multiple outputs for use in other flakes, or forks
of this one:
```nix
# external flake.nix
{
@ -95,102 +97,13 @@ this flake exports multiple outputs for use in other flakes:
```
# Structure
### NUR usage
The structure is here to keep things simple and clean. Anything sufficiently
generic can ultimately be exported for use in other flakes without getting
tied up in user concerns. As an added bonus, one can now trivially swap or
combine [profiles](#profiles), creating a custom config in mere moments.
You can use packages, modules and overlays from the
[Nix User Repository][nur].
## Hosts
Distributions for 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. See the
[`default.nix`](hosts/default.nix) for the implementation details.
## Profiles
A profile is any directory under [profiles](profiles) containing a `default.nix`
defining a valid NixOS module, with the added restriction that no new
delclarations 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.
For example, a zsh directory lives under [profiles/develop](profiles/develop/zsh).
It's self contained to allow inclusion without the whole of
[develop](profiles/develop) if one so wished. This provides a wonderful level of
granularity and control. Put simply: take the best, leave the rest.
In addition, profiles can depend on other profiles. For instance, the
[graphical](profiles/graphical) profile depends on [develop](profiles/develop)
simply by importing it. This is to ensure my terminal configuration is always
available from within a graphical session.
Optionally, you may choose to export your profiles via the flake output. If
you include it in the list defined in [profiles/default.nix](profiles/default.nix),
it will be available to other flakes via `nixosModules.profiles`.
## Users
User declarations belong in the `users` directory, created on entering `nix-shell`.
These are actually just a special case of [profiles](#profiles). Any profile that
makes a declaration defining, or referencing a specific interactive user or uid
belongs in here. That way profiles stay general, and all our idiosyncratic data
has a clean home.
For convenience, [home-manager][home-manager] is available automatically for
home directory setup and should only be used from this directory.
## Lib
The [lib](lib) directory contains a file `utils.nix` which is an attribute set
meant to consist mainly of utility functions you might want to write and use
throughout the configuration. They are available via a new `usr` attribute
passed to every NixOS module, eg:
```
# hosts/some-host.nix
{ usr, ... }:
let data = usr.myFunction # ...
in
{
# NixOS configuration
}
```
## 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.
## Modules, Packages and Overlays
All expressions in both [modules/default.nix](modules/default.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 can manually be added to [flake.nix](flake.nix)
for inclusion 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.
Since NUR packages are completely unchecked, they are not included by default.
Check out the NUR [branch](https://github.com/nrdxp/nixflk/tree/NUR) for usage.
# License
@ -204,8 +117,8 @@ which they apply. The aforementioned artifacts are all covered by the
licenses of the respective packages.
[direnv]: https://direnv.net
[home-manager]: https://github.com/rycee/home-manager
[NixOS]: https://nixos.org
[nur]: https://github.com/nix-community/NUR
[old]: https://github.com/nrdxp/nixos
[pr]: https://github.com/NixOS/nixpkgs/pull/68897
[rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md

5
hosts/NixOS.nix
View File

@ -1,10 +1,9 @@
{
imports = [ ];
### root password is empty by default ###
imports = [ ../users/nixos ../users/root ];
# Use the systemd-boot EFI boot loader.
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
networking.networkmanager.enable = true;
users.users.root.password = "";
}

24
hosts/default.nix
View File

@ -1,38 +1,44 @@
args@{ home, nixpkgs, self, ... }:
let
utils = import ../lib/utils.nix { lib = nixpkgs.lib; };
inherit (nixpkgs) lib;
utils = import ../lib/utils.nix { inherit lib; };
inherit (utils) recImport;
inherit (builtins) attrValues removeAttrs;
config = this:
nixpkgs.lib.nixosSystem rec {
config = hostName:
lib.nixosSystem rec {
system = "x86_64-linux";
specialArgs.usr = utils;
specialArgs.usr = { inherit utils; };
modules = let
inherit (home.nixosModules) home-manager;
core = ../profiles/core.nix;
global = {
networking.hostName = this;
networking.hostName = hostName;
nix.nixPath = [
"nixpkgs=${nixpkgs}"
"nixos-config=/etc/nixos/configuration.nix"
"nixpkgs-overlays=/etc/nixos/overlays"
];
system.configurationRevision = self.rev;
nixpkgs.overlays = self.overlays;
};
local = import "${toString ./.}/${this}.nix";
local = import "${toString ./.}/${hostName}.nix";
flakeModules = removeAttrs self.nixosModules [ "profiles" ];
# Everything in `./modules/list.nix`.
flakeModules =
attrValues (removeAttrs self.nixosModules [ "profiles" ]);
in attrValues flakeModules
++ [ core global local home.nixosModules.home-manager ];
in flakeModules ++ [ core global local home-manager ];
};

1
shell.nix
View File

@ -20,7 +20,6 @@ in pkgs.mkShell {
shellHook = ''
mkdir -p secrets
mkdir -p users
'';
NIX_CONF_DIR = let

16
users/nixos/default.nix Normal file
View File

@ -0,0 +1,16 @@
{
imports = [ ../../profiles/develop ];
users.users.nixos = {
uid = 1000;
password = "nixos";
description = "default";
isNormalUser = true;
extraGroups = [ "wheel" ];
};
# to avoid zsh startup message
home-manager.users.nrd.home.file.".zshrc" = ''
#
'';
}

4
users/root/default.nix Normal file
View File

@ -0,0 +1,4 @@
# recommend using `hashedPassword`
{
users.users.root.password = "";
}