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:
Timothy DeHerrera
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
|
||||
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
|
||||
|
||||
@ -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 = "";
|
||||
}
|
||||
|
||||
@ -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 ];
|
||||
|
||||
};
|
||||
|
||||
|
||||
@ -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
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