mirror of
https://github.com/foo-dogsquared/nixos-config.git
synced 2025-01-30 22:57:55 +00:00
docs/site: write "Project-specific setup" chapter
This commit is contained in:
parent
3a00738bf7
commit
75218992de
117
README.adoc
117
README.adoc
@ -124,123 +124,6 @@ It is exported in the flakes at `outputs.homeConfigurations`.
|
||||
For more information, see the link:./users/README.adoc[related documentation].
|
||||
|
||||
|
||||
[#declarative-host-management]
|
||||
=== Declarative host management
|
||||
|
||||
This project uses a custom setup for declarative host management.
|
||||
Specifically, it is done with a simple file at link:./images.toml[`./images.toml`] where it expects a table of the hosts' metadata.
|
||||
Each host in the table represents one of the hosts at link:./hosts/[`./hosts/`].
|
||||
|
||||
A host metadata has a certain schema which the following example is a complete version of it.
|
||||
The data is then used for certain functions in the flake definition file (i.e., `flake.nix`).
|
||||
|
||||
[#lst:images-metadata-example]
|
||||
[source, toml]
|
||||
----
|
||||
[plover]
|
||||
system = "x86_64-linux"
|
||||
format = "iso"
|
||||
hostname = "ploverrific"
|
||||
domain = "foodogsquared.one"
|
||||
nixpkgs-channel = "nixos-unstable-small"
|
||||
|
||||
[plover.deploy]
|
||||
hostname = "plover.foodogsquared.one"
|
||||
ssh-user = "admin"
|
||||
fast-connection = true
|
||||
auto-rollback = true
|
||||
magic-rollback = true
|
||||
remote-build = true
|
||||
----
|
||||
|
||||
For a complete reference, here are the expected attributes.
|
||||
|
||||
- `system` contains the platform of the host system.
|
||||
This is mainly used to indicate the platform used for the nixpkgs repository.
|
||||
|
||||
- `format` is the image output format for the host.
|
||||
It expects an accepted value from link:https://github.com/nix-community/nixos-generators[nixos-generators] project.
|
||||
|
||||
- `hostname` is the canonical hostname for the host.
|
||||
If unset, the hostname is the name of the table key.
|
||||
In the <<lst:images-metadata-example, previous example>>, if `plover.hostname` is unset, the value would be `plover` instead of `ploverrific`.
|
||||
|
||||
- `domain` is the domain used for networking configuration.
|
||||
It is set for `networking.domain` in NixOS configuration.
|
||||
|
||||
- `nixpkgs-channel` is the nixpkgs channel to be used for the host.
|
||||
The value could be any one of the nixpkgs flake inputs imported into this flake.
|
||||
By default, it uses `nixpkgs` flake input which points to the `nixos-unstable` channel.
|
||||
|
||||
- `deploy` is a table containing arguments from link:https://github.com/serokell/deploy-rs[deploy-rs].
|
||||
Only a few arguments are accepted (i.e., `hostname`, `fast-connection`, `remote-build`, `magic-rollback`, and `auto-rollback`).
|
||||
|
||||
Take note, only certain hosts can be considered as a NixOS configuration (e.g., `nixosConfigurations`).
|
||||
Specifically, those images with a format of `iso` and those without (since they fall back to `iso` anyways).
|
||||
Those NixOS configuration are then included as part of the deploy nodes for deploy-rs.
|
||||
Otherwise, most images are intended to be built.
|
||||
footnote:[Though, one could create a custom activation and deployment script with deploy-rs.]
|
||||
|
||||
|
||||
[#declarative-user-management]
|
||||
=== Declarative user management
|
||||
|
||||
Similarly to <<declarative-host-management>>, this project also provides a way to declare home-manager users.
|
||||
|
||||
Similar to `images.toml`, it expects a table of users with each representing one of the users from link:./users/home-manager/[`./users/home-manager/`].
|
||||
These are then included as part of `homeConfigurations` for easier installation with the standalone home-manager tool.
|
||||
Of which they are then included as part of deploy nodes for deploy-rs (also for easier deployment).
|
||||
|
||||
Here's an example user with complete schema.
|
||||
|
||||
[source, toml]
|
||||
----
|
||||
[foo-dogsquared]
|
||||
system = "x86_64-linux"
|
||||
home-manager-channel = "home-manager-23.05"
|
||||
home-directory = "/home/foo-dogsquared"
|
||||
username = "foodogsquared"
|
||||
|
||||
[foo-dogsquared.deploy]
|
||||
hostname = "local.foodogsquared.one"
|
||||
ssh-user = "admin"
|
||||
profile = "foodogsquared"
|
||||
fast-connection = true
|
||||
auto-rollback = true
|
||||
magic-rollback = true
|
||||
remote-build = true
|
||||
----
|
||||
|
||||
- `system` contains the platform of the home-manager user.
|
||||
This is mainly used to indicate the platform used for the nixpkgs repository.
|
||||
|
||||
- `home-manager-channel` contains the home-manager channel to be used.
|
||||
The value should be one of the home-manager channel that is imported into this flake.
|
||||
By default, it sets the home-manager channel at `home-manager` which is pointed at the unstable channel.
|
||||
|
||||
- `home-directory` is the associated home directory of the home-manager.
|
||||
It is set for `config.home.directory` at the home-manager configuration.
|
||||
By default, it will be set at `/home/$USERNAME`.
|
||||
|
||||
- `username` is the username of the home-manager user to be used for `config.home.username` at the home-manager configuration.
|
||||
If unset, it will use the table key.
|
||||
In the above example, the unset value would be `foo-dogsquared`.
|
||||
|
||||
- `deploy` is pretty similar to the previous configuration setting that it sets certain options for deploy-rs.
|
||||
|
||||
|
||||
[#secrets-management]
|
||||
=== Secrets management
|
||||
|
||||
This repo uses link:https://github.com/mozilla/sops[sops] as the main secret management tool.
|
||||
For integrating this into NixOS, I use link:https://github.com/Mic92/sops-nix[sops-nix].
|
||||
|
||||
To get started using sops, I recommend to take a look at `.sops.yaml` file which secrets belong to whom.
|
||||
Then edit a secrets with `sops PATH_TO_SECRET`.
|
||||
Take note, you need to respective keys to edit the secret in the first place.
|
||||
If you edit `./secrets/backup-archive.yaml` for example, it needs one of the keys (either my age and GPG key or the age key from host `ni`).
|
||||
|
||||
|
||||
|
||||
|
||||
== TODO
|
||||
|
||||
@ -7,10 +7,10 @@
|
||||
** link:{{< relref "./lay-of-the-land/what-should-not-be-here/" >}}[What should not be here?]
|
||||
|
||||
* Project-specific setup
|
||||
** link:./project-specific-setup/declarative-host-management[Declarative host management]
|
||||
** link:./project-specific-setup/declarative-user-management[Declarative user management]
|
||||
** link:./project-specific-setup/secrets-management[Secrets management]
|
||||
** link:./project-specific-setup/custom-firefox-addons[Custom Firefox addons]
|
||||
** link:{{< relref "./project-specific-setup/declarative-host-management" >}}[Declarative host management]
|
||||
** link:{{< relref "./project-specific-setup/declarative-user-management" >}}[Declarative user management]
|
||||
** link:{{< relref "./project-specific-setup/secrets-management" >}}[Secrets management]
|
||||
** link:{{< relref "./project-specific-setup/custom-firefox-addons" >}}[Custom Firefox addons]
|
||||
|
||||
* NixOS modules
|
||||
** link:./nixos-modules/profiles[Profiles]
|
||||
|
||||
@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Custom Firefox addons
|
||||
---
|
||||
= Custom Firefox addons
|
||||
|
||||
This project has a set of custom Firefox addons similar from link:https://nur.nix-community.org/repos/rycee/[rycee's NUR repo].
|
||||
In fact, it uses the link:https://sr.ht/~rycee/mozilla-addons-to-nix/[same tooling] as rycee's to generate my own list.
|
||||
|
||||
To get started, you'll have to create an input file containing the addons.
|
||||
In the project, this is found in github:{github-repo}[`./pkgs/firefox-addons.json`, path=./pkgs/firefox-addons.json, rev=master].
|
||||
For reference, here's my current list of Firefox addons.
|
||||
|
||||
[source, json]
|
||||
----
|
||||
include::github:{github-repo}[path=pkgs/firefox-addons/firefox-addons.json]
|
||||
----
|
||||
|
||||
But you're not done yet, you have to generate the output with the following command.
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
mozilla-addons-to-nix pkgs/firefox-addons/firefox-addons.json pkgs/firefox-addons/default.nix
|
||||
----
|
||||
|
||||
Then add the generated output into your package list at `./pkgs/default.nix`.
|
||||
At this point, you should be done.
|
||||
@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Declarative host management
|
||||
---
|
||||
= Declarative host management
|
||||
|
||||
This project uses a custom setup for declarative host management.
|
||||
Specifically, it is done with a simple file at github:{github-repo}[`./images.toml`, path=./images.toml, rev=master] where it expects a table of the hosts' metadata.
|
||||
Each host in the table represents one of the hosts at github:{github-repo}[`./hosts/`, path=./hosts/, rev=master].
|
||||
|
||||
A host metadata has a certain schema which the following example is a complete version of it.
|
||||
The data is then used for certain functions in the flake definition file (i.e., `flake.nix`).
|
||||
|
||||
[#lst:images-metadata-example]
|
||||
[source, toml]
|
||||
----
|
||||
[plover]
|
||||
system = "x86_64-linux"
|
||||
format = "iso"
|
||||
hostname = "ploverrific"
|
||||
domain = "foodogsquared.one"
|
||||
nixpkgs-channel = "nixos-unstable-small"
|
||||
|
||||
[plover.deploy]
|
||||
hostname = "plover.foodogsquared.one"
|
||||
ssh-user = "admin"
|
||||
fast-connection = true
|
||||
auto-rollback = true
|
||||
magic-rollback = true
|
||||
remote-build = true
|
||||
----
|
||||
|
||||
For a complete reference, here are the expected attributes.
|
||||
|
||||
- `system` contains the platform of the host system.
|
||||
This is mainly used to indicate the platform used for the nixpkgs repository.
|
||||
|
||||
- `format` is the image output format for the host.
|
||||
It expects an accepted value from github:nix-community/nixos-generators[opts=repo] project.
|
||||
|
||||
- `hostname` is the canonical hostname for the host.
|
||||
If unset, the hostname is the name of the table key.
|
||||
In the <<lst:images-metadata-example, previous example>>, if `plover.hostname` is unset, the value would be `plover` instead of `ploverrific`.
|
||||
|
||||
- `domain` is the domain used for networking configuration.
|
||||
It is set for `networking.domain` in NixOS configuration.
|
||||
|
||||
- `nixpkgs-channel` is the nixpkgs channel to be used for the host.
|
||||
The value could be any one of the nixpkgs flake inputs imported into this flake.
|
||||
By default, it uses `nixpkgs` flake input which points to the `nixos-unstable` channel.
|
||||
|
||||
- `deploy` is a table containing arguments from github:serokell/deploy-rs[opts=repo].
|
||||
Only a few arguments are accepted (i.e., `hostname`, `fast-connection`, `remote-build`, `magic-rollback`, and `auto-rollback`).
|
||||
|
||||
Take note, only certain hosts can be considered as a NixOS configuration (e.g., `nixosConfigurations`).
|
||||
Specifically, those images with a format of `iso` and those without (since they fall back to `iso` anyways).
|
||||
Those NixOS configuration are then included as part of the deploy nodes for deploy-rs.
|
||||
Otherwise, most images are intended to be built.
|
||||
footnote:[Though, one could create a custom activation and deployment script with deploy-rs.]
|
||||
@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Declarative user management
|
||||
---
|
||||
= Declarative user management
|
||||
|
||||
Similarly to xref:../declarative-host-management/index.adoc[Declarative host management], this project also provides a way to declare home-manager users.
|
||||
The `users.toml` sits in the project root expecting certain data.
|
||||
Similar to `images.toml`, it expects a table of users with each representing one of the users from github:{github-repo}[`./users/home-manager/`, path=./users/home-manager/, rev=master].
|
||||
These are then included as part of `homeConfigurations` for easier installation with the standalone home-manager tool.
|
||||
Of which they are then included as part of deploy nodes for deploy-rs (also for easier deployment).
|
||||
|
||||
Here's an example user with complete schema.
|
||||
|
||||
.A user with complete schema
|
||||
[source, toml]
|
||||
----
|
||||
[foo-dogsquared]
|
||||
system = "x86_64-linux"
|
||||
home-manager-channel = "home-manager-23.05"
|
||||
home-directory = "/home/foo-dogsquared"
|
||||
username = "foodogsquared"
|
||||
|
||||
[foo-dogsquared.deploy]
|
||||
hostname = "local.foodogsquared.one"
|
||||
ssh-user = "admin"
|
||||
profile = "foodogsquared"
|
||||
fast-connection = true
|
||||
auto-rollback = true
|
||||
magic-rollback = true
|
||||
remote-build = true
|
||||
----
|
||||
|
||||
- `system` contains the platform of the home-manager user.
|
||||
This is mainly used to indicate the platform used for the nixpkgs repository.
|
||||
|
||||
- `home-manager-channel` contains the home-manager channel to be used.
|
||||
The value should be one of the home-manager channel that is imported into this flake.
|
||||
By default, it sets the home-manager channel at `home-manager` which is pointed at the unstable channel.
|
||||
|
||||
- `home-directory` is the associated home directory of the home-manager.
|
||||
It is set for `config.home.directory` at the home-manager configuration.
|
||||
By default, it will be set at `/home/$USERNAME`.
|
||||
|
||||
- `username` is the username of the home-manager user to be used for `config.home.username` at the home-manager configuration.
|
||||
If unset, it will use the table key.
|
||||
In the above example, the unset value would be `foo-dogsquared`.
|
||||
|
||||
- `deploy` is pretty similar to the previous configuration setting that it sets certain options for deploy-rs.
|
||||
@ -0,0 +1,17 @@
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
sops.secrets =
|
||||
lib.getSecrets ./sops.yaml {
|
||||
ssh-key = { };
|
||||
"borg/ssh-key" = { };
|
||||
} //
|
||||
(lib.getSecrets ./wireguard.yaml
|
||||
(lib.attachSopsPathPrefix "wireguard" {
|
||||
"private-key" = {
|
||||
group = config.users.users.systemd-network.group;
|
||||
reloadUnits = [ "systemd-networkd.service" ];
|
||||
mode = "0640";
|
||||
};
|
||||
}));
|
||||
}
|
||||
@ -0,0 +1,13 @@
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
sops.secrets = lib.getSecrets ./sops.yaml {
|
||||
ssh-key = { };
|
||||
"borg/ssh-key" = { };
|
||||
"wireguard/private-key" = {
|
||||
group = config.users.users.systemd-network.group;
|
||||
reloadUnits = [ "systemd-networkd.service" ];
|
||||
mode = "0640";
|
||||
};
|
||||
};
|
||||
}
|
||||
@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Secrets management
|
||||
---
|
||||
= Secrets management
|
||||
|
||||
This repo uses github:mozilla/sops[opts=repo] as the main secret management tool.
|
||||
For integrating this into NixOS, I use github:Mic92/sops-nix[opts=repo].
|
||||
|
||||
To get started, you need to be familiar with using sops and then be intimately familiar with sops-nix NixOS module footnote:[There's even a home-manager module available which is nice.].
|
||||
|
||||
To get started using sops, I recommend to take a look at `.sops.yaml` file which secrets belong to whom.
|
||||
Then edit a secrets with `sops PATH_TO_SECRET`.
|
||||
Take note, you need to respective keys to edit the secret in the first place.
|
||||
If you edit `./secrets/backup-archive.yaml` for example, it needs one of the keys (either my age and GPG key or the age key from host `ni`).
|
||||
|
||||
The recommended practice to manage them secrets is to have them consolidate into one file.
|
||||
However, once the namespace has a large number (preferably 7 or more) of secrets under it, you can separate them into a individual file with the namespace as the filename.
|
||||
|
||||
In order to use sops with NixOS, we have to use sops-nix NixOS module.
|
||||
The best practice for using this module (for this project anyways) is to not set `sops.defaultSopsFile` and set individual secrets with `sopsFile`.
|
||||
Obviously, this is tedious.
|
||||
|
||||
Which is why I have several functions in my custom library that helps with setting secrets.
|
||||
The star of the show is `getSecrets` which accepts a path to the sops file and an attribute set of secrets to be set with `sops.secrets`.
|
||||
As you might've guessed, `getSecrets` will set the `sopsFile` to the given secret.
|
||||
|
||||
[#lst:get-secrets-demo]
|
||||
[source, nix]
|
||||
----
|
||||
include::./assets/get-secrets.nix[]
|
||||
----
|
||||
|
||||
[chat, foodogsquared]
|
||||
====
|
||||
What about for secrets that have been separated into its own file, you ask.
|
||||
The files under that namespace will be moved up in the filesystem which is not nice for organizing your decrypted secrets.
|
||||
====
|
||||
|
||||
[chat, Ezran]
|
||||
====
|
||||
I'm going to guess you also have a function in your library for that.
|
||||
====
|
||||
|
||||
For secrets that have been eventually moved into its own file where the decrypted secrets location will be moved one parent up in the location, there is a function for it which is `attachSopsPathPrefix`.
|
||||
The following example assumes that Wireguard secrets has been moved into its own file.
|
||||
|
||||
[#lst:attach-sops-prefix-demo]
|
||||
[source, nix]
|
||||
----
|
||||
include::./assets/attach-sops-prefix.nix[]
|
||||
----
|
||||
Loading…
Reference in New Issue
Block a user