Document adding a contributor

infra/README.org

@@ -1,6 +1,9 @@
 #+title: Infra
 
 This directory contains the definition of the VMs that host our infrastructure.
+
+* NixOps4
+
 Their configuration can be updated via NixOps4. Run
 
 #+begin_src sh
@@ -26,14 +29,21 @@ Then, given a deployment (eg. ~git~), run
 nixops4 apply <deployment>
 #+end_src
 
+Alternatively, to run the ~default~ deployment, run
+
+#+begin_src sh
+nixops4 apply
+#+end_src
+
 * Deployments
 
+- default :: Contains everything
 - ~git~ :: Machines hosting our Git infrastructure, eg. Forgejo and its actions
   runners
 - ~web~ :: Machines hosting our online content, eg. the website or the wiki
 - ~other~ :: Machines without a specific purpose
 
-* Procolix machines
+* Machines
 
 These machines are hosted on the Procolix Proxmox instance, to which
 non-Procolix members of the project do not have access. They host our stable

keys/README.md

@@ -0,0 +1,32 @@
+# Keys
+
+This directory contains the SSH public keys of both contributors to the projects
+and systems that we administrate. Keys are used both for [secrets](../secrets)
+decryption and [infra](../infra) management.
+
+Which private keys can be used to decrypt secrets is defined in
+[`secrets.nix`](../secrets/secrets.nix) as _all the contributors_ as well as the
+specific systems that need access to the secret in question. Adding a
+contributor of system's key to a secret requires rekeying the secret, which can
+only be done by some key that had already access to it. (Alternatively, one can
+overwrite a secret without knowing its contents.)
+
+In infra management, the systems' keys are used for security reasons; they
+identify the machine that we are talking to. The contributor keys are used to
+give access to the `root` user on these machines, which allows, among other
+things, to deploy their configurations with NixOps4.
+
+## Adding a contributor
+
+Adding a contributor consists of three steps:
+
+1. The contributor in question adds a file with their key to the
+   `./contributors` directory, and opens a pull request with it.
+
+2. An already-existing contributor rekeys the secrets, taking that new key into
+   account. See [../secrets#adding-a-contributor].
+
+3. An already-existing contributor redeploys the infrastructure to take into
+   account the new access. See [../infra].
+
+4. The pull request is accepted and merged.

secrets/README.md

@@ -49,3 +49,8 @@ As an example, let us add a secret in a file “cheeses” whose content should
    service that you are using must be able to read from a file at runtime, and
    if the NixOS default module options do not provide that, you must find a way
    around it.
+
+### Adding a contributor
+
+See [../keys]. Rekeying can be done by running `agenix --rekey` (or `-r` for
+short) in the current directory. This requires access to the secrets.