From d2a018ceecfed38ba3d9235b0d113ff6ded74f1f Mon Sep 17 00:00:00 2001
From: ibizaman <ibizapeanut@gmail.com>
Date: Mon, 12 Aug 2024 04:34:01 +0200
Subject: [PATCH] add docs for vaultwarden service

---
 docs/default.nix                             |  5 ++
 docs/services.md                             |  6 ++
 modules/services/vaultwarden/docs/default.md | 93 ++++++++++++++++++++
 3 files changed, 104 insertions(+)
 create mode 100644 modules/services/vaultwarden/docs/default.md

diff --git a/docs/default.nix b/docs/default.nix
index b1af2d6..e02ffe8 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -144,6 +144,11 @@ in stdenv.mkDerivation {
         '@OPTIONS_JSON@' \
        ${individualModuleOptionsDocs ../modules/services/nextcloud-server.nix}/share/doc/nixos/options.json
 
+    substituteInPlace ./modules/services/vaultwarden/docs/default.md \
+      --replace \
+        '@OPTIONS_JSON@' \
+       ${individualModuleOptionsDocs ../modules/services/vaultwarden.nix}/share/doc/nixos/options.json
+
     substituteInPlace ./modules/contracts/ssl/docs/default.md \
       --replace \
         '@OPTIONS_JSON@' \
diff --git a/docs/services.md b/docs/services.md
index 9f3ca1c..3ab63a2 100644
--- a/docs/services.md
+++ b/docs/services.md
@@ -13,6 +13,7 @@ information is provided in the respective manual sections.
 | Service               | Backup | Reverse Proxy | SSO | LDAP  | Monitoring | Profiling |
 |-----------------------|--------|---------------|-----|-------|------------|-----------|
 | [Nextcloud Server][1] | P (1)  | Y             | Y   | Y     | Y          | P (2)     |
+| [Vaultwarden][2]      | N      | Y             | Y   | Y     | N          | N         |
 
 Legend: **N**: no but WIP; **P**: partial; **Y**: yes
 
@@ -20,6 +21,11 @@ Legend: **N**: no but WIP; **P**: partial; **Y**: yes
 2. Works but the traces are not exported to Grafana yet.
 
 [1]: services-nextcloud.html
+[2]: services-vaultwarden.html
+
+```{=include=} chapters html:into-file=//services-vaultwarden.html
+modules/services/vaultwarden/docs/default.md
+```
 
 ```{=include=} chapters html:into-file=//services-nextcloud.html
 modules/services/nextcloud-server/docs/default.md
diff --git a/modules/services/vaultwarden/docs/default.md b/modules/services/vaultwarden/docs/default.md
new file mode 100644
index 0000000..5886f7c
--- /dev/null
+++ b/modules/services/vaultwarden/docs/default.md
@@ -0,0 +1,93 @@
+# Vaultwarden Service {#services-vaultwarden}
+
+Defined in [`/modules/services/vaultwarden.nix`](@REPO@/modules/services/vaultwarden.nix).
+
+This NixOS module is a service that sets up a [Vaultwarden Server](https://github.com/dani-garcia/vaultwarden).
+
+## Features {#services-vaultwarden-features}
+
+- Access through subdomain using reverse proxy.
+- Access through HTTPS using reverse proxy.
+- Automatic setup of Redis database for caching.
+- Backup of the data directory through the [backup block](./blocks-backup.html).
+- [Integration Tests](@REPO@/test/services/vaultwarden.nix)
+  - Tests /admin can only be accessed when authenticated with SSO.
+- Access to advanced options not exposed here thanks to how NixOS modules work.
+
+## Usage {#services-vaultwarden-usage}
+
+### Secrets {#services-vaultwarden-secrets}
+
+All the secrets should be readable by the vaultwarden user.
+
+Secrets should not be stored in the nix store. If you're using
+[sops-nix](https://github.com/Mic92/sops-nix) and assuming your secrets file is located at
+`./secrets.yaml`, you can define a secret with:
+
+```nix
+sops.secrets."vaultwarden/db" = {
+  sopsFile = ./secrets.yaml;
+  mode = "0400";
+  owner = "vaultwarden";
+  group = "postgres";
+  restartUnits = [ "vaultwarden.service" ];
+};
+```
+
+Then you can use that secret:
+
+```nix
+shb.vaultwarden.databasePasswordFile = config.sops.secrets."vaultwarden/db".path;
+```
+
+### SSO {#services-vaultwarden-sso}
+
+To protect the `/admin` endpoint, we use SSO.
+This requires the SSL, LDAP and SSO block to be configured.
+Follow those links first if needed.
+
+```nix
+let
+  domain = <...>;
+in
+shb.vaultwarden = {
+  enable = true;
+  inherit domain;
+  subdomain = "vaultwarden";
+  ssl = config.shb.certs.certs.letsencrypt.${domain};
+  port = 8222;
+  authEndpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
+  databasePasswordFile = config.sops.secrets."vaultwarden/db".path;
+  smtp = {
+    host = "smtp.eu.mailgun.org";
+    port = 587;
+    username = "postmaster@mg.${domain}";
+    from_address = "authelia@${domain}";
+    passwordFile = config.sops.secrets."vaultwarden/smtp".path;
+  };
+};
+
+sops.secrets."vaultwarden/db" = {
+  sopsFile = ./secrets.yaml;
+  mode = "0440";
+  owner = "vaultwarden";
+  group = "postgres";
+  restartUnits = [ "vaultwarden.service" "postgresql.service" ];
+};
+sops.secrets."vaultwarden/smtp" = {
+  sopsFile = ./secrets.yaml;
+  mode = "0400";
+  owner = "vaultwarden";
+  group = "vaultwarden";
+  restartUnits = [ "vaultwarden.service" ];
+};
+```
+
+### ZFS {#services-vaultwarden-zfs}
+
+Integration with the ZFS block allows to automatically create the relevant datasets.
+
+```nix
+shb.zfs.datasets."vaultwarden" = config.shb.vaultwarden.mount;
+shb.zfs.datasets."postgresql".path = "/var/lib/postgresql";
+```