Added support for the Go-NEB bot

2021-03-11 19:23:01 +01:00 · 2021-03-11 19:23:01 +01:00 · 51e2547484
commit 51e2547484
parent 9b72384df7
16 changed files with 783 additions and 0 deletions
--- a/docs/configuring-dns.md
+++ b/docs/configuring-dns.md
@ -34,6 +34,7 @@ If you are using Cloudflare DNS, make sure to disable the proxy and set all reco
 | CNAME | `dimension` (*)              | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `jitsi` (*)                  | -        | -      | -    | `matrix.<your-domain>` |
 | CNAME | `stats` (*)                  | -        | -      | -    | `matrix.<your-domain>` |
+| CNAME | `goneb` (*)                  | -        | -      | -    | `matrix.<your-domain>` |

 ## Subdomains setup

@ -48,6 +49,8 @@ The `jitsi.<your-domain>` subdomain may be necessary, because this playbook coul

 The `stats.<your-domain>` subdomain may be necessary, because this playbook could install [Grafana](https://grafana.com/) and setup performance metrics for you. Grafana installation is disabled by default, it is not a core required component. To learn how to install it, see our [metrics and graphs guide](configuring-playbook-prometheus-grafana.md). If you do not wish to set up Grafana, feel free to skip the `stats.<your-domain>` DNS record. It is possible to install Prometheus without installing Grafana, this would also not require the `stats.<your-domain>` subdomain.

+The `goneb.<your-domain>` subdomain may be necessary, because this playbook could install the [Go-NEB](https://github.com/matrix-org/go-neb) bot. The installation of Go-NEB is disabled by default, it is not a core required component. To learn how to install it, see our [configuring Go-NEB guide](configuring-playbook-bot-go-neb.md). If you do not wish to set up Go-NEB, feel free to skip the `goneb.<your-domain>` DNS record.
+

 ## `_matrix-identity._tcp` SRV record setup

--- a/docs/configuring-playbook-bot-go-neb.md
+++ b/docs/configuring-playbook-bot-go-neb.md
@ -0,0 +1,218 @@
+# Setting up Go-NEB (optional)
+
+The playbook can install and configure [Go-NEB](https://github.com/matrix-org/go-neb) for you.
+
+Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
+
+See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
+
+
+## Registering the bot users
+
+The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
+
+You **need to register the bot user manually** before setting up the bot.
+
+Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
+
+If you use curl, you can immediatly copy/paste the access token into the configuration file.
+
+```
+curl -X POST --header 'Content-Type: application/json' -d '{
+    "identifier": { "type": "m.id.user", "user": "bot.go-neb" },
+    "password": "a strong password",
+    "type": "m.login.password"
+}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
+```
+
+You can use also use the playbook to [register a new user](registering-users.md):
+
+```
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
+```
+
+And then log in via element, but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start)
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
+
+```yaml
+matrix_bot_go_neb_enabled: true
+
+# You need at least 1 client.
+matrix_bot_go_neb_clients:
+  - UserID: "@goneb:localhost"
+    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+    DeviceID: "DEVICE1"
+    HomeserverURL: "{{ matrix_homeserver_container_url }}"
+    Sync: true
+    AutoJoinRooms: true
+    DisplayName: "Go-NEB!"
+    AcceptVerificationFromUsers: [":localhost:8008"]
+
+  - UserID: "@another_goneb:localhost"
+    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+    DeviceID: "DEVICE2"
+    HomeserverURL: "{{ matrix_homeserver_container_url }}"
+    Sync: false
+    AutoJoinRooms: false
+    DisplayName: "Go-NEB!"
+    AcceptVerificationFromUsers: ["^@admin:localhost:8008$"]
+
+# Optional, for use with the github_cmd, github_webhooks or jira services
+matrix_bot_go_neb_realms:
+  - ID: "github_realm"
+    Type: "github"
+    Config: {} # No need for client ID or Secret as Go-NEB isn't generating OAuth URLs
+
+# Optional. The list of *authenticated* sessions which Go-NEB is aware of.
+matrix_bot_go_neb_sessions:
+  - SessionID: "your_github_session"
+    RealmID: "github_realm"
+    UserID: "@YOUR_USER_ID:localhost" # This needs to be the username of the person that's allowed to use the !github commands
+    Config:
+      # Populate these fields by generating a "Personal Access Token" on github.com
+      AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
+      Scopes: "admin:org_hook,admin:repo_hook,repo,user"
+
+# The list of services which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# See the docs for /configureService for the full list of options:
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
+# You need at least 1 service.
+matrix_bot_go_neb_services:
+  - ID: "echo_service"
+    Type: "echo"
+    UserID: "@goneb:localhost"
+    Config: {}
+
+# Can be obtained from https://developers.giphy.com/dashboard/
+  - ID: "giphy_service"
+    Type: "giphy"
+    UserID: "@goneb:localhost" # requires a Syncing client
+    Config:
+      api_key: "qwg4672vsuyfsfe"
+      use_downsized: false
+
+# This service has been dead for over a year :/
+  - ID: "guggy_service"
+    Type: "guggy"
+    UserID: "@goneb:localhost" # requires a Syncing client
+    Config:
+      api_key: "2356saaqfhgfe"
+
+# API Key via https://developers.google.com/custom-search/v1/introduction
+# CX via http://www.google.com/cse/manage/all
+# https://stackoverflow.com/questions/6562125/getting-a-cx-id-for-custom-search-google-api-python
+# 'Search the entire web' and 'Image search' enabled for best results
+  - ID: "google_service"
+    Type: "google"
+    UserID: "@goneb:localhost" # requires a Syncing client
+    Config:
+      api_key: "AIzaSyA4FD39m9"
+      cx: "AIASDFWSRRtrtr"
+
+# Get a key via https://api.imgur.com/oauth2/addclient
+# Select "oauth2 without callback url" and use the clientid as api_key value
+  - ID: "imgur_service"
+    Type: "imgur"
+    UserID: "@imgur:localhost" # requires a Syncing client
+    Config:
+      api_key: "AIzaSyA4FD39m9"
+
+  - ID: "wikipedia_service"
+    Type: "wikipedia"
+    UserID: "@goneb:localhost" # requires a Syncing client
+    Config:
+
+  - ID: "rss_service"
+    Type: "rssbot"
+    UserID: "@another_goneb:localhost"
+    Config:
+      feeds:
+        "http://lorem-rss.herokuapp.com/feed?unit=second&interval=60":
+          rooms: ["!qmElAGdFYCHoCJuaNt:localhost"]
+          must_include:
+            author:
+              - author1
+            description:
+              - lorem
+              - ipsum
+          must_not_include:
+            title:
+              - Lorem
+              - Ipsum
+
+  - ID: "github_cmd_service"
+    Type: "github"
+    UserID: "@goneb:localhost" # requires a Syncing client
+    Config:
+      RealmID: "github_realm"
+
+    # Make sure your BASE_URL can be accessed by Github!
+  - ID: "github_webhook_service"
+    Type: "github-webhook"
+    UserID: "@another_goneb:localhost"
+    Config:
+      RealmID: "github_realm"
+      ClientUserID: "@YOUR_USER_ID:localhost" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
+      Rooms:
+        "!someroom:id":
+          Repos:
+            "matrix-org/synapse":
+              Events: ["push", "issues"]
+            "matrix-org/dendron":
+              Events: ["pull_request"]
+        "!anotherroom:id":
+          Repos:
+            "matrix-org/synapse":
+              Events: ["push", "issues"]
+            "matrix-org/dendron":
+              Events: ["pull_request"]
+
+  - ID: "slackapi_service"
+    Type: "slackapi"
+    UserID: "@slackapi:localhost"
+    Config:
+      Hooks:
+        "hook1":
+          RoomID: "!someroom:id"
+          MessageType: "m.text" # default is m.text
+
+  - ID: "alertmanager_service"
+    Type: "alertmanager"
+    UserID: "@alertmanager:localhost"
+    Config:
+      # This is for information purposes only. It should point to Go-NEB path as follows:
+      # `/services/hooks/<base64 encoded service ID>`
+      # Where in this case "service ID" is "alertmanager_service"
+      # Make sure your BASE_URL can be accessed by the Alertmanager instance!
+      webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
+      # Each room will get the notification with the alert rendered with the given template
+      rooms:
+        "!someroomid:domain.tld":
+          text_template: "{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}"
+          html_template: "{{range .Alerts -}}  {{ $severity := index .Labels \"severity\" }}    {{ if eq .Status \"firing\" }}      {{ if eq $severity \"critical\"}}        <font color='red'><b>[FIRING - CRITICAL]</b></font>      {{ else if eq $severity \"warning\"}}        <font color='orange'><b>[FIRING - WARNING]</b></font>      {{ else }}        <b>[FIRING - {{ $severity }}]</b>      {{ end }}    {{ else }}      <font color='green'><b>[RESOLVED]</b></font>    {{ end }}  {{ index .Labels \"alertname\"}} : {{ index .Annotations \"description\"}}   <a href=\"{{ .GeneratorURL }}\">source</a><br/>{{end -}}"
+          msg_type: "m.text"  # Must be either `m.text` or `m.notice`
+```
+
+
+## Installing
+
+After configuring the playbook, run the [installation](installing.md) command again:
+
+```
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+
+## Usage
+
+To use the bot, invite it to any existing Matrix room (`/invite @whatever_you_chose:DOMAIN` where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain, make sure you have permission from the room owner if that's not you).
+
+Basic usage is like this: `!echo hi` or `!imgur puppies` or `!giphy matrix`
+
+If you enabled the github_cmd service you can get the supported commands via `!github help`
+
+You can also refer to the upstream [Documentation](https://github.com/matrix-org/go-neb).
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@ -729,6 +729,27 @@ matrix_bot_matrix_reminder_bot_database_password: "{{ matrix_synapse_macaroon_se
 ######################################################################


+######################################################################
+#
+# matrix-bot-go-neb
+#
+######################################################################
+
+# We don't enable bots by default.
+matrix_bot_go_neb_enabled: false
+
+matrix_bot_go_neb_systemd_required_services_list: |
+  {{
+    ['docker.service']
+  }}
+
+######################################################################
+#
+# /matrix-bot-go-neb
+#
+######################################################################
+
+
 ######################################################################
 #
 # matrix-corporal
@ -1053,6 +1074,7 @@ matrix_nginx_proxy_proxy_matrix_client_redirect_root_uri_to_domain: "{{ matrix_s
 matrix_nginx_proxy_proxy_matrix_enabled: true
 matrix_nginx_proxy_proxy_element_enabled: "{{ matrix_client_element_enabled }}"
 matrix_nginx_proxy_proxy_dimension_enabled: "{{ matrix_dimension_enabled }}"
+matrix_nginx_proxy_proxy_bot_go_neb_enabled: "{{ matrix_bot_go_neb_enabled }}"
 matrix_nginx_proxy_proxy_jitsi_enabled: "{{ matrix_jitsi_enabled }}"
 matrix_nginx_proxy_proxy_grafana_enabled: "{{ matrix_grafana_enabled }}"

@ -1123,6 +1145,8 @@ matrix_ssl_domains_to_obtain_certificates_for: |
    +
    ([matrix_server_fqn_dimension] if matrix_dimension_enabled else [])
    +
+    ([matrix_server_fqn_bot_go_neb] if matrix_bot_go_neb_enabled else [])
+    +
    ([matrix_server_fqn_jitsi] if matrix_jitsi_enabled else [])
    +
    ([matrix_server_fqn_grafana] if matrix_grafana_enabled else [])
--- a/roles/matrix-base/defaults/main.yml
+++ b/roles/matrix-base/defaults/main.yml
@ -18,6 +18,9 @@ matrix_server_fqn_element: "element.{{ matrix_domain }}"
 # This is where you access the Dimension.
 matrix_server_fqn_dimension: "dimension.{{ matrix_domain }}"

+# For use with Go-NEB! (github callback url for example)
+matrix_server_fqn_bot_go_neb: "goneb.{{ matrix_domain }}"
+
 # This is where you access Jitsi.
 matrix_server_fqn_jitsi: "jitsi.{{ matrix_domain }}"

--- a/roles/matrix-bot-go-neb/defaults/main.yml
+++ b/roles/matrix-bot-go-neb/defaults/main.yml
@ -0,0 +1,225 @@
+# Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.
+# See: https://github.com/matrix-org/go-neb
+
+matrix_bot_go_neb_enabled: false
+matrix_bot_go_neb_version: latest
+matrix_bot_go_neb_docker_image: "matrixdotorg/go-neb:{{ matrix_bot_go_neb_version }}"
+matrix_bot_go_neb_docker_image_force_pull: "{{ matrix_bot_go_neb_docker_image.endswith(':latest') }}"
+
+matrix_bot_go_neb_base_path: "{{ matrix_base_data_path }}/go-neb"
+matrix_bot_go_neb_config_path: "{{ matrix_bot_go_neb_base_path }}/config"
+matrix_bot_go_neb_config_path_in_container: "/config/config.yaml"
+matrix_bot_go_neb_data_path: "{{ matrix_bot_go_neb_base_path }}/data"
+matrix_bot_go_neb_data_store_path: "{{ matrix_bot_go_neb_data_path }}/store"
+
+# A list of extra arguments to pass to the container
+matrix_bot_go_neb_container_extra_arguments: []
+
+# List of systemd services that matrix-bot-go-neb.service depends on
+matrix_bot_go_neb_systemd_required_services_list: ['docker.service']
+
+# List of systemd services that matrix-bot-go-neb.service wants
+matrix_bot_go_neb_systemd_wanted_services_list: []
+
+# Database-related configuration fields.
+#
+# MUST be "sqlite3". No other type is supported.
+matrix_bot_go_neb_database_engine: 'sqlite3'
+
+matrix_bot_go_neb_sqlite_database_path_local: "{{ matrix_bot_go_neb_data_path }}/bot.db"
+matrix_bot_go_neb_sqlite_database_path_in_container: "/data/bot.db"
+
+matrix_bot_go_neb_storage_database: "{{
+	{
+		'sqlite3': (matrix_bot_go_neb_sqlite_database_path_in_container + '?_busy_timeout=5000'),
+	}[matrix_bot_go_neb_database_engine]
+}}"
+
+# The bot's username(s). These users need to be created manually beforehand.
+# The access tokens that the bot uses to authenticate.
+# Generate one as described in
+# https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook-dimension.md#access-token
+# via curl. With the element method, you might run into decryption problems (see https://github.com/matrix-org/go-neb#quick-start)
+matrix_bot_go_neb_clients: {}
+#  - UserID: "@goneb:localhost"
+#    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+#    DeviceID: "DEVICE1"
+#    HomeserverURL: "http://localhost:8008"
+#    Sync: true
+#    AutoJoinRooms: true
+#    DisplayName: "Go-NEB!"
+#    AcceptVerificationFromUsers: [":localhost:8008"]
+#
+#  - UserID: "@another_goneb:localhost"
+#    AccessToken: "MDASDASJDIASDJASDAFGFRGER"
+#    DeviceID: "DEVICE2"
+#    HomeserverURL: "http://localhost:8008"
+#    Sync: false
+#    AutoJoinRooms: false
+#    DisplayName: "Go-NEB!"
+#    AcceptVerificationFromUsers: ["^@admin:localhost:8008$"]
+
+# The list of realms which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# See the docs for /configureAuthRealm for the full list of options:
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureAuthRealmRequest
+matrix_bot_go_neb_realms: {}
+#  - ID: "github_realm"
+#    Type: "github"
+#    Config: {} # No need for client ID or Secret as Go-NEB isn't generating OAuth URLs
+
+# The list of *authenticated* sessions which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# The full list of options are shown below: there is no single HTTP endpoint
+# which maps to this section.
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#Session
+matrix_bot_go_neb_sessions: {}
+#  - SessionID: "your_github_session"
+#    RealmID: "github_realm"
+#    UserID: "@YOUR_USER_ID:localhost" # This needs to be the username of the person that's allowed to use the !github commands
+#    Config:
+#      # Populate these fields by generating a "Personal Access Token" on github.com
+#      AccessToken: "YOUR_GITHUB_ACCESS_TOKEN"
+#      Scopes: "admin:org_hook,admin:repo_hook,repo,user"
+
+# The list of services which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# See the docs for /configureService for the full list of options:
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
+matrix_bot_go_neb_services: {}
+#  - ID: "echo_service"
+#    Type: "echo"
+#    UserID: "@goneb:localhost"
+#    Config: {}
+
+## Can be obtained from https://developers.giphy.com/dashboard/
+#  - ID: "giphy_service"
+#    Type: "giphy"
+#    UserID: "@goneb:localhost" # requires a Syncing client
+#    Config:
+#      api_key: "qwg4672vsuyfsfe"
+#      use_downsized: false
+#
+## This service has been dead for over a year :/
+#  - ID: "guggy_service"
+#    Type: "guggy"
+#    UserID: "@goneb:localhost" # requires a Syncing client
+#    Config:
+#      api_key: "2356saaqfhgfe"
+#
+## API Key via https://developers.google.com/custom-search/v1/introduction
+## CX via http://www.google.com/cse/manage/all
+## https://stackoverflow.com/questions/6562125/getting-a-cx-id-for-custom-search-google-api-python
+## 'Search the entire web' and 'Image search' enabled for best results
+#  - ID: "google_service"
+#    Type: "google"
+#    UserID: "@goneb:localhost" # requires a Syncing client
+#    Config:
+#      api_key: "AIzaSyA4FD39m9"
+#      cx: "AIASDFWSRRtrtr"
+#
+## Get a key via https://api.imgur.com/oauth2/addclient
+## Select "oauth2 without callback url" and use the clientid as api_key value
+#  - ID: "imgur_service"
+#    Type: "imgur"
+#    UserID: "@imgur:localhost" # requires a Syncing client
+#    Config:
+#      api_key: "AIzaSyA4FD39m9"
+#
+#  - ID: "wikipedia_service"
+#    Type: "wikipedia"
+#    UserID: "@goneb:localhost" # requires a Syncing client
+#    Config:
+#
+#  - ID: "rss_service"
+#    Type: "rssbot"
+#    UserID: "@another_goneb:localhost"
+#    Config:
+#      feeds:
+#        "http://lorem-rss.herokuapp.com/feed?unit=second&interval=60":
+#          rooms: ["!qmElAGdFYCHoCJuaNt:localhost"]
+#          must_include:
+#            author:
+#              - author1
+#            description:
+#              - lorem
+#              - ipsum
+#          must_not_include:
+#            title:
+#              - Lorem
+#              - Ipsum
+#
+#  - ID: "github_cmd_service"
+#    Type: "github"
+#    UserID: "@goneb:localhost" # requires a Syncing client
+#    Config:
+#      RealmID: "github_realm"
+#
+#    # Make sure your BASE_URL can be accessed by Github!
+#  - ID: "github_webhook_service"
+#    Type: "github-webhook"
+#    UserID: "@another_goneb:localhost"
+#    Config:
+#      RealmID: "github_realm"
+#      ClientUserID: "@YOUR_USER_ID:localhost" # needs to be an authenticated user so Go-NEB can create webhooks. Check the UserID field in the github_realm in matrix_bot_go_neb_sessions.
+#      Rooms:
+#        "!someroom:id":
+#          Repos:
+#            "matrix-org/synapse":
+#              Events: ["push", "issues"]
+#            "matrix-org/dendron":
+#              Events: ["pull_request"]
+#        "!anotherroom:id":
+#          Repos:
+#            "matrix-org/synapse":
+#              Events: ["push", "issues"]
+#            "matrix-org/dendron":
+#              Events: ["pull_request"]
+#
+#  - ID: "slackapi_service"
+#    Type: "slackapi"
+#    UserID: "@slackapi:localhost"
+#    Config:
+#      Hooks:
+#        "hook1":
+#          RoomID: "!someroom:id"
+#          MessageType: "m.text" # default is m.text
+#
+#  - ID: "alertmanager_service"
+#    Type: "alertmanager"
+#    UserID: "@alertmanager:localhost"
+#    Config:
+#      # This is for information purposes only. It should point to Go-NEB path as follows:
+#      # `/services/hooks/<base64 encoded service ID>`
+#      # Where in this case "service ID" is "alertmanager_service"
+#      # Make sure your BASE_URL can be accessed by the Alertmanager instance!
+#      webhook_url: "http://localhost/services/hooks/YWxlcnRtYW5hZ2VyX3NlcnZpY2U"
+#      # Each room will get the notification with the alert rendered with the given template
+#      rooms:
+#        "!someroomid:domain.tld":
+#          text_template: "{{range .Alerts -}} [{{ .Status }}] {{index .Labels \"alertname\" }}: {{index .Annotations \"description\"}} {{ end -}}"
+#          html_template: "{{range .Alerts -}}  {{ $severity := index .Labels \"severity\" }}    {{ if eq .Status \"firing\" }}      {{ if eq $severity \"critical\"}}        <font color='red'><b>[FIRING - CRITICAL]</b></font>      {{ else if eq $severity \"warning\"}}        <font color='orange'><b>[FIRING - WARNING]</b></font>      {{ else }}        <b>[FIRING - {{ $severity }}]</b>      {{ end }}    {{ else }}      <font color='green'><b>[RESOLVED]</b></font>    {{ end }}  {{ index .Labels \"alertname\"}} : {{ index .Annotations \"description\"}}   <a href=\"{{ .GeneratorURL }}\">source</a><br/>{{end -}}"
+#          msg_type: "m.text"  # Must be either `m.text` or `m.notice`
+
+# Default configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrix_bot_go_neb_configuration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_bot_go_neb_configuration_yaml: "{{ lookup('template', 'templates/config.yaml.j2') }}"
+
+matrix_bot_go_neb_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_bot_go_neb_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_bot_go_neb_configuration_yaml`.
+
+matrix_bot_go_neb_configuration_extension: "{{ matrix_bot_go_neb_configuration_extension_yaml|from_yaml if matrix_bot_go_neb_configuration_extension_yaml|from_yaml is mapping else {} }}"
+
+# Holds the final configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_bot_go_neb_configuration_yaml`.
+matrix_bot_go_neb_configuration: "{{ matrix_bot_go_neb_configuration_yaml|from_yaml|combine(matrix_bot_go_neb_configuration_extension, recursive=True) }}"
+
--- a/roles/matrix-bot-go-neb/tasks/init.yml
+++ b/roles/matrix-bot-go-neb/tasks/init.yml
@ -0,0 +1,3 @@
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-go-neb.service'] }}"
+  when: matrix_bot_go_neb_enabled|bool
--- a/roles/matrix-bot-go-neb/tasks/main.yml
+++ b/roles/matrix-bot-go-neb/tasks/main.yml
@ -0,0 +1,21 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
+  when: "run_setup|bool and matrix_bot_go_neb_enabled|bool"
+  tags:
+    - setup-all
+    - setup-bot-go-neb
+
+- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
+  when: "run_setup|bool and matrix_bot_go_neb_enabled|bool"
+  tags:
+    - setup-all
+    - setup-bot-go-neb
+
+- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+  when: "run_setup|bool and not matrix_bot_go_neb_enabled|bool"
+  tags:
+    - setup-all
+    - setup-bot-go-neb
--- a/roles/matrix-bot-go-neb/tasks/setup_install.yml
+++ b/roles/matrix-bot-go-neb/tasks/setup_install.yml
@ -0,0 +1,50 @@
+---
+
+- set_fact:
+    matrix_bot_go_neb_requires_restart: false
+
+- name: Ensure go-neb paths exist
+  file:
+    path: "{{ item.path }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - { path: "{{ matrix_bot_go_neb_config_path }}", when: true }
+    - { path: "{{ matrix_bot_go_neb_data_path }}", when: true }
+    - { path: "{{ matrix_bot_go_neb_data_store_path }}", when: true }
+  when: "item.when|bool"
+
+- name: Ensure go-neb image is pulled
+  docker_image:
+    name: "{{ matrix_bot_go_neb_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_bot_go_neb_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_bot_go_neb_docker_image_force_pull }}"
+
+- name: Ensure go-neb config installed
+  copy:
+    content: "{{ matrix_bot_go_neb_configuration|to_nice_yaml }}"
+    dest: "{{ matrix_bot_go_neb_config_path }}/config.yaml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- name: Ensure matrix-bot-go-neb.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-bot-go-neb.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-bot-go-neb.service"
+    mode: 0644
+  register: matrix_bot_go_neb_systemd_service_result
+
+- name: Ensure systemd reloaded after matrix-bot-go-neb.service installation
+  service:
+    daemon_reload: yes
+  when: "matrix_bot_go_neb_systemd_service_result.changed|bool"
+
+- name: Ensure matrix-bot-go-neb.service restarted, if necessary
+  service:
+    name: "matrix-bot-go-neb.service"
+    state: restarted
+  when: "matrix_bot_go_neb_requires_restart|bool"
--- a/roles/matrix-bot-go-neb/tasks/setup_uninstall.yml
+++ b/roles/matrix-bot-go-neb/tasks/setup_uninstall.yml
@ -0,0 +1,35 @@
+---
+
+- name: Check existence of matrix-go-neb service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-bot-go-neb.service"
+  register: matrix_bot_go_neb_service_stat
+
+- name: Ensure matrix-go-neb is stopped
+  service:
+    name: matrix-bot-go-neb
+    state: stopped
+    daemon_reload: yes
+  register: stopping_result
+  when: "matrix_bot_go_neb_service_stat.stat.exists|bool"
+
+- name: Ensure matrix-bot-go-neb.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-bot-go-neb.service"
+    state: absent
+  when: "matrix_bot_go_neb_service_stat.stat.exists|bool"
+
+- name: Ensure systemd reloaded after matrix-bot-go-neb.service removal
+  service:
+    daemon_reload: yes
+  when: "matrix_bot_go_neb_service_stat.stat.exists|bool"
+
+- name: Ensure Matrix go-neb paths don't exist
+  file:
+    path: "{{ matrix_bot_go_neb_base_path }}"
+    state: absent
+
+- name: Ensure go-neb Docker image doesn't exist
+  docker_image:
+    name: "{{ matrix_bot_go_neb_docker_image }}"
+    state: absent
--- a/roles/matrix-bot-go-neb/tasks/validate_config.yml
+++ b/roles/matrix-bot-go-neb/tasks/validate_config.yml
@ -0,0 +1,13 @@
+---
+
+- name: Fail if there's not at least 1 client
+  fail:
+    msg: >-
+      You need at least 1 client in the matrix_bot_go_neb_clients block.
+  when: matrix_bot_go_neb_clients is not defined or matrix_bot_go_neb_clients[0] is not defined
+
+- name: Fail if there's not at least 1 service
+  fail:
+    msg: >-
+      You need at least 1 service in the matrix_bot_go_neb_services block.
+  when: matrix_bot_go_neb_services is not defined or matrix_bot_go_neb_services[0] is not defined
--- a/roles/matrix-bot-go-neb/templates/config.yaml.j2
+++ b/roles/matrix-bot-go-neb/templates/config.yaml.j2
@ -0,0 +1,44 @@
+# Go-NEB Configuration File
+#
+# This file provides an alternative way to configure Go-NEB which does not involve HTTP APIs.
+#
+# This file can be supplied to go-neb by the environment variable `CONFIG_FILE=config.yaml`.
+# It will force Go-NEB to operate in "config" mode. This means:
+#   - Go-NEB will ONLY use the data contained inside this file.
+#   - All of Go-NEB's /admin HTTP listeners will be disabled. You will be unable to add new services at runtime.
+#   - The environment variable `DATABASE_URL` will be ignored and an in-memory database will be used instead.
+#
+# This file is broken down into 4 sections which matches the following HTTP APIs:
+#   - /configureClient
+#   - /configureAuthRealm
+#   - /configureService
+#   - /requestAuthSession (redirects not supported)
+
+# The list of clients which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# See the docs for /configureClient for the full list of options:
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ClientConfig
+clients:
+  {{ matrix_bot_go_neb_clients }}
+
+# The list of realms which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# See the docs for /configureAuthRealm for the full list of options:
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureAuthRealmRequest
+realms:
+  {{ matrix_bot_go_neb_realms }}
+
+# The list of *authenticated* sessions which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# The full list of options are shown below: there is no single HTTP endpoint
+# which maps to this section.
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#Session
+sessions:
+  {{ matrix_bot_go_neb_sessions }}
+
+# The list of services which Go-NEB is aware of.
+# Delete or modify this list as appropriate.
+# See the docs for /configureService for the full list of options:
+# https://matrix-org.github.io/go-neb/pkg/github.com/matrix-org/go-neb/api/index.html#ConfigureServiceRequest
+services:
+  {{ matrix_bot_go_neb_services }}
--- a/roles/matrix-bot-go-neb/templates/systemd/matrix-bot-go-neb.service.j2
+++ b/roles/matrix-bot-go-neb/templates/systemd/matrix-bot-go-neb.service.j2
@ -0,0 +1,46 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=Matrix reminder bot
+{% for service in matrix_bot_go_neb_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_bot_go_neb_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-bot-go-neb 2>/dev/null'
+ExecStartPre=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-bot-go-neb 2>/dev/null'
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-bot-go-neb \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--network={{ matrix_docker_network }} \
+			-e 'BIND_ADDRESS=:4050' \
+			-e 'DATABASE_TYPE={{ matrix_bot_go_neb_database_engine }}' \
+			-e 'BASE_URL=https://{{ matrix_server_fqn_bot_go_neb }}' \
+			-e 'CONFIG_FILE={{ matrix_bot_go_neb_config_path_in_container }}' \
+			-e 'DATABASE_URL={{ matrix_bot_go_neb_storage_database }}' \
+			--mount type=bind,src={{ matrix_bot_go_neb_config_path }},dst=/config,ro \
+			--mount type=bind,src={{ matrix_bot_go_neb_data_path }},dst=/data \
+			--entrypoint=/bin/sh \
+			{% for arg in matrix_bot_go_neb_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_bot_go_neb_docker_image }} \
+			-c "go-neb /config/config.yaml"
+
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-bot-go-neb 2>/dev/null'
+ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-bot-go-neb 2>/dev/null'
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-bot-go-neb
+
+[Install]
+WantedBy=multi-user.target
--- a/roles/matrix-nginx-proxy/defaults/main.yml
+++ b/roles/matrix-nginx-proxy/defaults/main.yml
@ -120,6 +120,10 @@ matrix_nginx_proxy_proxy_matrix_federation_port: 8448
 matrix_nginx_proxy_proxy_dimension_enabled: false
 matrix_nginx_proxy_proxy_dimension_hostname: "{{ matrix_server_fqn_dimension }}"

+# Controls whether proxying the goneb domain should be done.
+matrix_nginx_proxy_proxy_bot_go_neb_enabled: false
+matrix_nginx_proxy_proxy_bot_go_neb_hostname: "{{ matrix_server_fqn_bot_go_neb }}"
+
 # Controls whether proxying the jitsi domain should be done.
 matrix_nginx_proxy_proxy_jitsi_enabled: false
 matrix_nginx_proxy_proxy_jitsi_hostname: "{{ matrix_server_fqn_jitsi }}"
@ -236,6 +240,9 @@ matrix_nginx_proxy_proxy_element_additional_server_configuration_blocks: []
 # A list of strings containing additional configuration blocks to add to Dimension's server configuration (matrix-dimension.conf).
 matrix_nginx_proxy_proxy_dimension_additional_server_configuration_blocks: []

+# A list of strings containing additional configuration blocks to add to GoNEB's server configuration (matrix-bot-go-neb.conf).
+matrix_nginx_proxy_proxy_bot_go_neb_additional_server_configuration_blocks: []
+
 # A list of strings containing additional configuration blocks to add to Jitsi's server configuration (matrix-jitsi.conf).
 matrix_nginx_proxy_proxy_jitsi_additional_server_configuration_blocks: []

--- a/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml
+++ b/roles/matrix-nginx-proxy/tasks/setup_nginx_proxy.yml
@ -79,6 +79,13 @@
    mode: 0644
  when: matrix_nginx_proxy_proxy_dimension_enabled|bool

+- name: Ensure Matrix nginx-proxy configuration for goneb domain exists
+  template:
+    src: "{{ role_path }}/templates/nginx/conf.d/matrix-bot-go-neb.conf.j2"
+    dest: "{{ matrix_nginx_proxy_confd_path }}/matrix-bot-go-neb.conf"
+    mode: 0644
+  when: matrix_nginx_proxy_proxy_bot_go_neb_enabled|bool
+
 - name: Ensure Matrix nginx-proxy configuration for jitsi domain exists
  template:
    src: "{{ role_path }}/templates/nginx/conf.d/matrix-jitsi.conf.j2"
@ -196,6 +203,12 @@
    state: absent
  when: "not matrix_nginx_proxy_proxy_dimension_enabled|bool"

+- name: Ensure Matrix nginx-proxy configuration for goneb domain deleted
+  file:
+    path: "{{ matrix_nginx_proxy_confd_path }}/matrix-bot-go-neb.conf"
+    state: absent
+  when: "not matrix_nginx_proxy_proxy_bot_go_neb_enabled|bool"
+
 - name: Ensure Matrix nginx-proxy configuration for jitsi domain deleted
  file:
    path: "{{ matrix_nginx_proxy_confd_path }}/matrix-jitsi.conf"
--- a/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-bot-go-neb.conf.j2
+++ b/roles/matrix-nginx-proxy/templates/nginx/conf.d/matrix-bot-go-neb.conf.j2
@ -0,0 +1,77 @@
+#jinja2: lstrip_blocks: "True"
+
+{% macro render_vhost_directives() %}
+	gzip on;
+	gzip_types text/plain application/json application/javascript text/css image/x-icon font/ttf image/gif;
+	add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+	add_header X-Content-Type-Options nosniff;
+{% for configuration_block in matrix_nginx_proxy_proxy_bot_go_neb_additional_server_configuration_blocks %}
+	{{- configuration_block }}
+{% endfor %}
+
+	location / {
+		{% if matrix_nginx_proxy_enabled %}
+			{# Use the embedded DNS resolver in Docker containers to discover the service #}
+			resolver 127.0.0.11 valid=5s;
+			set $backend "matrix-bot-go-neb:4050";
+			proxy_pass http://$backend;
+		{% else %}
+			{# Generic configuration for use outside of our container setup #}
+			proxy_pass http://127.0.0.1:4050;
+		{% endif %}
+
+		proxy_set_header Host $host;
+		proxy_set_header X-Forwarded-For $remote_addr;
+	}
+{% endmacro %}
+
+server {
+	listen {{ 8080 if matrix_nginx_proxy_enabled else 80 }};
+	server_name {{ matrix_nginx_proxy_proxy_bot_go_neb_hostname }};
+
+	server_tokens off;
+	root /dev/null;
+
+	{% if matrix_nginx_proxy_https_enabled %}
+		location /.well-known/acme-challenge {
+			{% if matrix_nginx_proxy_enabled %}
+				{# Use the embedded DNS resolver in Docker containers to discover the service #}
+				resolver 127.0.0.11 valid=5s;
+				set $backend "matrix-certbot:8080";
+				proxy_pass http://$backend;
+			{% else %}
+				{# Generic configuration for use outside of our container setup #}
+				proxy_pass http://127.0.0.1:{{ matrix_ssl_lets_encrypt_certbot_standalone_http_port }};
+			{% endif %}
+		}
+
+		location / {
+			return 301 https://$http_host$request_uri;
+		}
+	{% else %}
+		{{ render_vhost_directives() }}
+	{% endif %}
+}
+
+{% if matrix_nginx_proxy_https_enabled %}
+server {
+	listen {{ 8443 if matrix_nginx_proxy_enabled else 443 }} ssl http2;
+	listen [::]:{{ 8443 if matrix_nginx_proxy_enabled else 443 }} ssl http2;
+
+	server_name {{ matrix_nginx_proxy_proxy_bot_go_neb_hostname }};
+
+	server_tokens off;
+	root /dev/null;
+
+	ssl_certificate {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_bot_go_neb_hostname }}/fullchain.pem;
+	ssl_certificate_key {{ matrix_ssl_config_dir_path }}/live/{{ matrix_nginx_proxy_proxy_bot_go_neb_hostname }}/privkey.pem;
+
+	ssl_protocols {{ matrix_nginx_proxy_ssl_protocols }};
+	{% if matrix_nginx_proxy_ssl_ciphers != '' %}
+	ssl_ciphers {{ matrix_nginx_proxy_ssl_ciphers }};
+	{% endif %}
+	ssl_prefer_server_ciphers {{ matrix_nginx_proxy_ssl_prefer_server_ciphers }};
+
+	{{ render_vhost_directives() }}
+}
+{% endif %}
--- a/setup.yml
+++ b/setup.yml
@ -32,6 +32,7 @@
    - matrix-bridge-mx-puppet-instagram
    - matrix-bridge-sms
    - matrix-bot-matrix-reminder-bot
+    - matrix-bot-go-neb
    - matrix-synapse
    - matrix-synapse-admin
    - matrix-prometheus-node-exporter