From 75218992de0be568b4be9cea09164bb0b6b3be56 Mon Sep 17 00:00:00 2001 From: Gabriel Arazas Date: Sat, 8 Jul 2023 22:27:43 +0800 Subject: [PATCH] docs/site: write "Project-specific setup" chapter --- README.adoc | 117 ------------------ docs/content/en-US/menu.adoc | 8 +- .../custom-firefox-addons/index.adoc | 26 ++++ .../declarative-host-management/index.adoc | 58 +++++++++ .../declarative-user-management/index.adoc | 48 +++++++ .../assets/attach-sops-prefix.nix | 17 +++ .../secrets-management/assets/get-secrets.nix | 13 ++ .../secrets-management/index.adoc | 51 ++++++++ 8 files changed, 217 insertions(+), 121 deletions(-) create mode 100644 docs/content/en-US/project-specific-setup/custom-firefox-addons/index.adoc create mode 100644 docs/content/en-US/project-specific-setup/declarative-host-management/index.adoc create mode 100644 docs/content/en-US/project-specific-setup/declarative-user-management/index.adoc create mode 100644 docs/content/en-US/project-specific-setup/secrets-management/assets/attach-sops-prefix.nix create mode 100644 docs/content/en-US/project-specific-setup/secrets-management/assets/get-secrets.nix create mode 100644 docs/content/en-US/project-specific-setup/secrets-management/index.adoc diff --git a/README.adoc b/README.adoc index 72853ca8..abae829c 100644 --- a/README.adoc +++ b/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 <>, 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 <>, 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 diff --git a/docs/content/en-US/menu.adoc b/docs/content/en-US/menu.adoc index 127ff093..4cf12896 100644 --- a/docs/content/en-US/menu.adoc +++ b/docs/content/en-US/menu.adoc @@ -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] diff --git a/docs/content/en-US/project-specific-setup/custom-firefox-addons/index.adoc b/docs/content/en-US/project-specific-setup/custom-firefox-addons/index.adoc new file mode 100644 index 00000000..87d3583e --- /dev/null +++ b/docs/content/en-US/project-specific-setup/custom-firefox-addons/index.adoc @@ -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. diff --git a/docs/content/en-US/project-specific-setup/declarative-host-management/index.adoc b/docs/content/en-US/project-specific-setup/declarative-host-management/index.adoc new file mode 100644 index 00000000..3e2bbefc --- /dev/null +++ b/docs/content/en-US/project-specific-setup/declarative-host-management/index.adoc @@ -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 <>, 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.] diff --git a/docs/content/en-US/project-specific-setup/declarative-user-management/index.adoc b/docs/content/en-US/project-specific-setup/declarative-user-management/index.adoc new file mode 100644 index 00000000..60d6bdc3 --- /dev/null +++ b/docs/content/en-US/project-specific-setup/declarative-user-management/index.adoc @@ -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. diff --git a/docs/content/en-US/project-specific-setup/secrets-management/assets/attach-sops-prefix.nix b/docs/content/en-US/project-specific-setup/secrets-management/assets/attach-sops-prefix.nix new file mode 100644 index 00000000..956feffb --- /dev/null +++ b/docs/content/en-US/project-specific-setup/secrets-management/assets/attach-sops-prefix.nix @@ -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"; + }; + })); +} diff --git a/docs/content/en-US/project-specific-setup/secrets-management/assets/get-secrets.nix b/docs/content/en-US/project-specific-setup/secrets-management/assets/get-secrets.nix new file mode 100644 index 00000000..1ce17aee --- /dev/null +++ b/docs/content/en-US/project-specific-setup/secrets-management/assets/get-secrets.nix @@ -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"; + }; + }; +} diff --git a/docs/content/en-US/project-specific-setup/secrets-management/index.adoc b/docs/content/en-US/project-specific-setup/secrets-management/index.adoc new file mode 100644 index 00000000..1fe7c9de --- /dev/null +++ b/docs/content/en-US/project-specific-setup/secrets-management/index.adoc @@ -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[] +----