nixos/modules/services/matrix/maubot.md

   1 # Maubot {#module-services-maubot}
   2
   3 [Maubot](https://github.com/maubot/maubot) is a plugin-based bot
   4 framework for Matrix.
   5
   6 ## Configuration {#module-services-maubot-configuration}
   7
   8 1. Set [](#opt-services.maubot.enable) to `true`. The service will use
   9    SQLite by default.
  10 2. If you want to use PostgreSQL instead of SQLite, do this:
  11
  12    ```nix
  13    {
  14      services.maubot.settings.database = "postgresql://maubot@localhost/maubot";
  15    }
  16    ```
  17
  18    If the PostgreSQL connection requires a password, you will have to
  19    add it later on step 8.
  20 3. If you plan to expose your Maubot interface to the web, do something
  21    like this:
  22    ```nix
  23    {
  24      services.nginx.virtualHosts."matrix.example.org".locations = {
  25        "/_matrix/maubot/" = {
  26          proxyPass = "http://127.0.0.1:${toString config.services.maubot.settings.server.port}";
  27          proxyWebsockets = true;
  28        };
  29      };
  30      services.maubot.settings.server.public_url = "matrix.example.org";
  31      # do the following only if you want to use something other than /_matrix/maubot...
  32      services.maubot.settings.server.ui_base_path = "/another/base/path";
  33    }
  34    ```
  35 4. Optionally, set `services.maubot.pythonPackages` to a list of python3
  36    packages to make available for Maubot plugins.
  37 5. Optionally, set `services.maubot.plugins` to a list of Maubot
  38    plugins (full list available at https://plugins.maubot.xyz/):
  39    ```nix
  40    {
  41      services.maubot.plugins = with config.services.maubot.package.plugins; [
  42        reactbot
  43        # This will only change the default config! After you create a
  44        # plugin instance, the default config will be copied into that
  45        # instance's config in Maubot's database, and further base config
  46        # changes won't affect the running plugin.
  47        (rss.override {
  48          base_config = {
  49            update_interval = 60;
  50            max_backoff = 7200;
  51            spam_sleep = 2;
  52            command_prefix = "rss";
  53            admins = [ "@chayleaf:pavluk.org" ];
  54          };
  55        })
  56      ];
  57      # ...or...
  58      services.maubot.plugins = config.services.maubot.package.plugins.allOfficialPlugins;
  59      # ...or...
  60      services.maubot.plugins = config.services.maubot.package.plugins.allPlugins;
  61      # ...or...
  62      services.maubot.plugins = with config.services.maubot.package.plugins; [
  63        (weather.override {
  64          # you can pass base_config as a string
  65          base_config = ''
  66            default_location: New York
  67            default_units: M
  68            default_language:
  69            show_link: true
  70            show_image: false
  71          '';
  72        })
  73      ];
  74    }
  75    ```
  76 6. Start Maubot at least once before doing the following steps (it's
  77    necessary to generate the initial config).
  78 7. If your PostgreSQL connection requires a password, add
  79    `database: postgresql://user:password@localhost/maubot`
  80    to `/var/lib/maubot/config.yaml`. This overrides the Nix-provided
  81    config. Even then, don't remove the `database` line from Nix config
  82    so the module knows you use PostgreSQL!
  83 8. To create a user account for logging into Maubot web UI and
  84    configuring it, generate a password using the shell command
  85    `mkpasswd -R 12 -m bcrypt`, and edit `/var/lib/maubot/config.yaml`
  86    with the following:
  87
  88    ```yaml
  89    admins:
  90        admin_username: $2b$12$g.oIStUeUCvI58ebYoVMtO/vb9QZJo81PsmVOomHiNCFbh0dJpZVa
  91    ```
  92
  93    Where `admin_username` is your username, and `$2b...` is the bcrypted
  94    password.
  95 9. Optional: if you want to be able to register new users with the
  96    Maubot CLI (`mbc`), and your homeserver is private, add your
  97    homeserver's registration key to `/var/lib/maubot/config.yaml`:
  98
  99    ```yaml
 100    homeservers:
 101        matrix.example.org:
 102            url: https://matrix.example.org
 103            secret: your-very-secret-key
 104    ```
 105 10. Restart Maubot after editing `/var/lib/maubot/config.yaml`,and
 106     Maubot will be available at
 107     `https://matrix.example.org/_matrix/maubot`. If you want to use the
 108     `mbc` CLI, it's available using the `maubot` package (`nix-shell -p
 109     maubot`).