initial commit

docs/modules/nixos/maubot.md

@@ -0,0 +1,99 @@
+# Maubot
+
+A plugin-based Matrix bot system.
+
+> Warning: Maubot uses [deprecated `libolm`](https://github.com/mautrix/go/issues/262).
+
+View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/maubot).
+
+## References
+
+- [GitHub repository](https://github.com/maubot/maubot)
+
+## Sops
+
+Provide the following entries to your host's `secrets.yaml`:
+
+> Replace `abc123` with your actual secrets as well as `alice` and `bob` with your actual admin user names.
+
+```yaml
+maubot:
+  admins:
+    alice: abc123
+    bob: abc123
+    # ...  
+```
+
+## Config
+
+This module only works if Matrix Synapse is running on the same machine.
+See [the module on synix](./matrix-synapse.md).
+
+```nix
+{
+  imports = [ 
+    inputs.synix.nixosModules.maubot 
+    inputs.synix.nixosModules.matrix-synapse
+  ];
+
+  nixpkgs.config.permittedInsecurePackages = [
+    "olm-3.2.16"
+  ];
+
+  services.maubot = {
+    enable = true;
+    sops = true;
+    admins = [
+      "alice"
+      "bob"
+    ];
+    plugins = with config.services.maubot.package.plugins; [
+      gitlab
+      reminder
+    ];
+  };
+
+  services.matrix-synapse = {
+    enable = true;
+    # ...
+  };
+}
+```
+
+## Setup
+
+1. Create a bot: `$ register_new_matrix_user`
+1. Login as your admin user: `$ mbc login`
+1. Authenticate as bot: `$ mbc auth`
+1. Take note of the access token and device ID
+1. Visit `https:/EXAMPLE.TLD/_matrix/maubot`
+1. Create a client (if not already preset)
+1. Create an instance
+
+## Bots
+
+### GitLab
+
+> See [Readme on GitHub](https://github.com/maubot/gitlab?tab=readme-ov-file)
+
+Create a personal access token with full API access.
+
+```
+!gitlab server login https://git.example.com PERSONAL_ACCESS_TOKEN
+!gitlab webhook add https://git.example.com user/project
+```
+
+Check the webhook URL for potential errors.
+
+## Tips
+
+### Upload a profile picture to Matrix
+
+```sh
+curl -X POST "https://YOUR_HOMESERVER_URL/_matrix/media/v3/upload" \
+     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+     -H "Content-Type: image/png" \
+     --data-binary "@/path/to/your/image.png"
+```
+
+The respond body contains a valid avatar URL (`mxc://...`).