enhance usage docs

docs/usage.md

@@ -43,6 +43,59 @@ tries to update the `nixpkgs` input daily, verifying all tests pass before accep
 [1]: https://github.com/ibizaman/selfhostblocks
 [2]: https://blog.tiserbox.com/posts/2023-12-25-automated-flake-lock-update-pull-requests-and-merging.html
 
+## Example Deployment with Nixos-Rebuild {#usage-example-nixosrebuild}
+
+The following snippets show how to deploy Self Host Blocks using the standard deployment system `nixos-rebuild`.
+
+```nix
+{
+  inputs = {
+    selfhostblocks.url = "github:ibizaman/selfhostblocks";
+  };
+
+  outputs = { self, selfhostblocks }: {
+    nixosConfigurations = {
+      machine = selfhostblocks.inputs.nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+        modules = [
+          selfhostblocks.nixosModules.${system}.default
+        ];
+
+        # Machine specific configuration goes here.
+      };
+    };
+  };
+}
+```
+
+The above snippet is very minimal as it assumes you have only one machine to deploy to, so `nixpkgs`
+is defined exclusively by the `selfhostblocks.inputs.nixpkgs` input. If some machines are not using
+Self Host Blocks, you can do the following:
+
+```nix
+{
+  inputs = {
+    selfhostblocks.url = "github:ibizaman/selfhostblocks";
+  };
+
+  outputs = { self, selfhostblocks }: {
+    nixosConfigurations = {
+      machine1 = nixpkgs.lib.nixosSystem {
+      };
+
+      machine2 = selfhostblocks.inputs.nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+        modules = [
+          selfhostblocks.nixosModules.${system}.default
+        ];
+
+        # Machine specific configuration goes here.
+      };
+    };
+  };
+}
+```
+
 ## Example Deployment With Colmena {#usage-example-colmena}
 
 The following snippets show how to deploy Self Host Blocks using the deployment system [Colmena][3].
@@ -52,6 +105,8 @@ The following snippets show how to deploy Self Host Blocks using the deployment
 ```nix
 {
   inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+
     selfhostblocks.url = "github:ibizaman/selfhostblocks";
   };
 
@@ -68,6 +123,8 @@ The following snippets show how to deploy Self Host Blocks using the deployment
           imports = [
             selfhostblocks.nixosModules.${system}.default
           ];
+
+          # Machine specific configuration goes here.
         };
       };
   };
@@ -103,6 +160,8 @@ is defined exclusively by the `selfhostblocks` input. It is more likely that you
           imports = [
             selfhostblocks.nixosModules.${system}.default
           ];
+
+          # Machine specific configuration goes here.
         };
     };
   };
@@ -111,3 +170,108 @@ is defined exclusively by the `selfhostblocks` input. It is more likely that you
 
 In the above snippet, `machine1` will use the `nixpkgs` version from your inputs while `machine2`
 will use the `nixpkgs` version from `selfhostblocks`.
+
+## Secrets with sops-nix {#usage-secrets}
+
+This section complements the official [sops-nix](https://github.com/Mic92/sops-nix) guide.
+
+Managing secrets is an important aspect of deploying. You cannot store your secrets in nix directly
+because they get stored unencrypted and you don't want that. We need to use another system that
+encrypts secrets when storing in the nix store and then decrypts them on the target host upon system
+activation. `sops-nix` is one of such system.
+
+Sops-nix works by encrypting the secrets file with at least 2 keys. Your private key and a private
+key from the target host. This way, you can edit the secrets and the target host can decrypt the
+secrets. Separating the keys this way is good practice because it reduces the impact of having one
+being compromised.
+
+One way to setup secrets management using `sops-nix`:
+
+1. Create your own private key that will be located in `keys.txt`. The public key will be printed on stdout.
+   ```bash
+   $ nix shell nixpkgs#age --command age-keygen -o keys.txt
+   Public key: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
+   ```
+2. Get the target host's public key. We will use the key derived from the ssh key of the host.
+   ```bash
+   $ nix shell nixpkgs#ssh-to-age --command \
+       sh -c 'ssh-keyscan -t ed25519 -4 <target_host> | ssh-to-age'
+   # localhost:2222 SSH-2.0-OpenSSH_9.6
+   age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
+   ```
+3. Create a `sops.yaml` file that explains how sops-nix should encrypt the - yet to be created -
+   `secrets.yaml` file. You can be creative here, but a basic snippet is:
+   ```bash
+   keys:
+     - &me age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
+     - &target age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
+   creation_rules:
+     - path_regex: secrets.yaml$
+       key_groups:
+       - age:
+         - *me
+         - *target
+   ```
+4. Create a `secrets.yaml` file that will contain the encrypted secrets as a Yaml file:
+   ```bash
+   $ SOPS_AGE_KEY_FILE=keys.txt nix run --impure nixpkgs#sops -- \
+     secrets.yaml
+   ```
+   This will open your preferred editor. An example of yaml file is the following (secrets are elided for brevity):
+   ```yaml
+   nextcloud:
+       adminpass: 43bb4b...
+       onlyoffice:
+           jwt_secret: 3a10fce3...
+   ```
+   The actual file on your filesystem will look like so, again with data elided:
+   ```yaml
+   nextcloud:
+       adminpass: ENC[AES256_GCM,data:Tt99...GY=,tag:XlAqRYidkOMRZAPBsoeEMw==,type:str]
+       onlyoffice:
+           jwt_secret: ENC[AES256_GCM,data:f87a...Yg=,tag:Y1Vg2WqDnJbl1Xg2B6W1Hg==,type:str]
+   sops:
+       kms: []
+       gcp_kms: []
+       azure_kv: []
+       hc_vault: []
+       age:
+           - recipient: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
+             enc: |
+               -----BEGIN AGE ENCRYPTED FILE-----
+               YWdl...6g==
+               -----END AGE ENCRYPTED FILE-----
+           - recipient: age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
+             enc: |
+               -----BEGIN AGE ENCRYPTED FILE-----
+               YWdl...RA==
+               -----END AGE ENCRYPTED FILE-----
+       lastmodified: "2024-01-28T06:07:02Z"
+       mac: ENC[AES256_GCM,data:lDJh...To=,tag:Opon9lMZBv5S7rRhkGFuQQ==,type:str]
+       pgp: []
+       unencrypted_suffix: _unencrypted
+       version: 3.8.1
+   ```
+
+   To actually create random secrets, you can use:
+   ```bash
+   $ nix run nixpkgs#openssl -- rand -hex 64
+   ```
+5. Use `sops-nix` module in nix:
+   ```bash
+   imports = [
+       selfhostblocks.inputs.sops-nix.nixosModules.default
+   ];
+   ```
+6. Reference the secrets in nix:
+   ```nix
+   shb.nextcloud.adminPassFile = config.sops.secrets."nextcloud/adminpass".path;
+
+   sops.secrets."nextcloud/adminpass" = {
+     sopsFile = ./secrets.yaml;
+     mode = "0440";
+     owner = "nextcloud";
+     group = "nextcloud";
+     restartUnits = [ "phpfpm-nextcloud.service" ];
+   };
+   ```