DOC.md: split off from README.md
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:
parent
9b64b50ee8
commit
e078e7a229
99
DOC.md
Normal file
99
DOC.md
Normal 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
123
README.md
@ -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
|
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.
|
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
|
Please be advised, flakes are still an experimental feature.
|
||||||
even more will become possible, i.e. [nixops](https://nixos.org/nixops)
|
Presuming they get [merged][rfc], even more will become possible, e.g.
|
||||||
|
[nixops](https://nixos.org/nixops)/[disnix](https://nixos.org/disnix)
|
||||||
support.
|
support.
|
||||||
|
|
||||||
#### Flake Talk:
|
#### Flake Talk:
|
||||||
@ -22,6 +23,9 @@ nix-shell
|
|||||||
|
|
||||||
git checkout -b $new_branch template
|
git checkout -b $new_branch template
|
||||||
|
|
||||||
|
# set a root password, preferably with `hashedPassword`
|
||||||
|
$EDITOR ./users/root/default.nix
|
||||||
|
|
||||||
# generate hardware config
|
# generate hardware config
|
||||||
nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
|
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.
|
# any ./profiles you may wish to try out.
|
||||||
$EDITOR ./hosts/${new_host}.nix
|
$EDITOR ./hosts/${new_host}.nix
|
||||||
|
|
||||||
|
|
||||||
# backup existing config and ensure configuration lives in expected location
|
# backup existing config and ensure configuration lives in expected location
|
||||||
mv /etc/nixos /etc/nixos.old
|
mv /etc/nixos /etc/nixos.old
|
||||||
ln -s $PWD /etc/nixos
|
ln -s $PWD /etc/nixos
|
||||||
@ -52,15 +55,13 @@ git add ./hosts/${new_host}.nix
|
|||||||
# This will be run as root.
|
# This will be run as root.
|
||||||
rebuild $new_host switch
|
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
|
## Additional Capabilities
|
||||||
|
|
||||||
@ -72,7 +73,8 @@ rebuild iso
|
|||||||
nix profile install ".#packages.x86_64-linux.myPackage"
|
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
|
```nix
|
||||||
# external flake.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
|
You can use packages, modules and overlays from the
|
||||||
generic can ultimately be exported for use in other flakes without getting
|
[Nix User Repository][nur].
|
||||||
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.
|
|
||||||
|
|
||||||
## Hosts
|
Since NUR packages are completely unchecked, they are not included by default.
|
||||||
Distributions for particular machines should be stored in the [hosts](hosts)
|
Check out the NUR [branch](https://github.com/nrdxp/nixflk/tree/NUR) for usage.
|
||||||
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.
|
|
||||||
|
|
||||||
# License
|
# License
|
||||||
|
|
||||||
@ -204,8 +117,8 @@ which they apply. The aforementioned artifacts are all covered by the
|
|||||||
licenses of the respective packages.
|
licenses of the respective packages.
|
||||||
|
|
||||||
[direnv]: https://direnv.net
|
[direnv]: https://direnv.net
|
||||||
[home-manager]: https://github.com/rycee/home-manager
|
|
||||||
[NixOS]: https://nixos.org
|
[NixOS]: https://nixos.org
|
||||||
|
[nur]: https://github.com/nix-community/NUR
|
||||||
[old]: https://github.com/nrdxp/nixos
|
[old]: https://github.com/nrdxp/nixos
|
||||||
[pr]: https://github.com/NixOS/nixpkgs/pull/68897
|
[pr]: https://github.com/NixOS/nixpkgs/pull/68897
|
||||||
[rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md
|
[rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md
|
||||||
|
@ -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.systemd-boot.enable = true;
|
||||||
boot.loader.efi.canTouchEfiVariables = true;
|
boot.loader.efi.canTouchEfiVariables = true;
|
||||||
|
|
||||||
networking.networkmanager.enable = true;
|
networking.networkmanager.enable = true;
|
||||||
users.users.root.password = "";
|
|
||||||
}
|
}
|
||||||
|
@ -1,38 +1,44 @@
|
|||||||
args@{ home, nixpkgs, self, ... }:
|
args@{ home, nixpkgs, self, ... }:
|
||||||
let
|
let
|
||||||
utils = import ../lib/utils.nix { lib = nixpkgs.lib; };
|
inherit (nixpkgs) lib;
|
||||||
|
|
||||||
|
utils = import ../lib/utils.nix { inherit lib; };
|
||||||
|
|
||||||
inherit (utils) recImport;
|
inherit (utils) recImport;
|
||||||
|
|
||||||
inherit (builtins) attrValues removeAttrs;
|
inherit (builtins) attrValues removeAttrs;
|
||||||
|
|
||||||
config = this:
|
config = hostName:
|
||||||
nixpkgs.lib.nixosSystem rec {
|
lib.nixosSystem rec {
|
||||||
system = "x86_64-linux";
|
system = "x86_64-linux";
|
||||||
|
|
||||||
specialArgs.usr = utils;
|
specialArgs.usr = { inherit utils; };
|
||||||
|
|
||||||
modules = let
|
modules = let
|
||||||
|
inherit (home.nixosModules) home-manager;
|
||||||
|
|
||||||
core = ../profiles/core.nix;
|
core = ../profiles/core.nix;
|
||||||
|
|
||||||
global = {
|
global = {
|
||||||
networking.hostName = this;
|
networking.hostName = hostName;
|
||||||
nix.nixPath = [
|
nix.nixPath = [
|
||||||
"nixpkgs=${nixpkgs}"
|
"nixpkgs=${nixpkgs}"
|
||||||
"nixos-config=/etc/nixos/configuration.nix"
|
"nixos-config=/etc/nixos/configuration.nix"
|
||||||
"nixpkgs-overlays=/etc/nixos/overlays"
|
"nixpkgs-overlays=/etc/nixos/overlays"
|
||||||
];
|
];
|
||||||
|
|
||||||
system.configurationRevision = self.rev;
|
system.configurationRevision = self.rev;
|
||||||
|
|
||||||
nixpkgs.overlays = self.overlays;
|
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
|
in flakeModules ++ [ core global local home-manager ];
|
||||||
++ [ core global local home.nixosModules.home-manager ];
|
|
||||||
|
|
||||||
};
|
};
|
||||||
|
|
||||||
|
@ -20,7 +20,6 @@ in pkgs.mkShell {
|
|||||||
|
|
||||||
shellHook = ''
|
shellHook = ''
|
||||||
mkdir -p secrets
|
mkdir -p secrets
|
||||||
mkdir -p users
|
|
||||||
'';
|
'';
|
||||||
|
|
||||||
NIX_CONF_DIR = let
|
NIX_CONF_DIR = let
|
||||||
|
16
users/nixos/default.nix
Normal file
16
users/nixos/default.nix
Normal 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
4
users/root/default.nix
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
# recommend using `hashedPassword`
|
||||||
|
{
|
||||||
|
users.users.root.password = "";
|
||||||
|
}
|
Loading…
Reference in New Issue
Block a user