Add setting display name and avatar feature (#6)

* update env var docs in the comments of default file

* add set avatar feature and update docs and license to be more tidy

* add setting display name and avatar

* Apply suggestions from code review - update features

* add info about using this bot via kubernetes

* add info about setting up registration

* Update README.md - note nightly builds being on main tag

.env.default

@@ -1,20 +1,53 @@
+# port that this service runs on in the docker container
 APP_PORT="3000"
+
+# made up secret you set in the webhook_configs url of a reciever that alertmanager
+# uses when making making HTTP POSTS to this service receivers:
+#  - name: 'myreceiver'
+#    webhook_configs:
+#    - url: 'https://my-matrix-alertmanager.tld/alerts?secret=veryverysecretkeyhere'
 APP_ALERTMANAGER_SECRET="<secret key for the webhook events>"
-MATRIX_HOMESERVER_URL="https://homeserver.tld"
+
+# ----------------------------------------------------------------------------
+#                  matrix homeserver connection info
+# ----------------------------------------------------------------------------
+
+# url of your matrix homeserver, commonly synapse
+MATRIX_HOMESERVER_URL="https://matrix.myhomeserver.tld"
+
 # The rooms to send alerts to, separated by a |
 # Each entry contains the receiver name (from alertmanager) and the
 # internal id (not the public alias) of the Matrix channel to forward to.
+#
+# we may change this down the line because it's ugly :) Perhaps json string?
 MATRIX_ROOMS="receiver1/!abcdefgh:homeserver.tld|receiver2/!qwerty:homeserver.tld"
+
+# "access token" that matrix expects during registration of this bot (also called
+# an appservice). In your registration.yaml that you provide to your homeserver, such as synapse, you will need to provide
+# this token as the as_token
 MATRIX_TOKEN="<token from the alertmanager user on matrix>"
-MATRIX_USER="@alertmanager:homeserver.tld"
+
+# user to use for this bot on your matrix homeserver
+MATRIX_USER="@alertmanager:matrix.myhomeserver.tld"
+
+# optional mxc:// URL to use for this bot's avatar photo
+MATRIX_AVATAR="mxc://"
+
+# optional display name this bot
+MATRIX_DISPLAY_NAME="Alertmanager Bot"
+
 # Set this to 1 to make firing alerts do a `@room` mention.
-# NOTE! Bot should also have enough power in the room for this to be useful.
-MENTION_ROOM="0"
+# ⚠️ NOTE! Bot should also have enough power in the room for this to be useful.
+MENTION_ROOM="true"
+
+# TODO: check to see if this work?
+#
+# comment to disable Grafana links
+GRAFANA_URL="https://grafana.example.com"
 
-# set to enable Grafana links
-#GRAFANA_URL=https://grafana.example.com
 # grafana data source
-#GRAFANA_DATASOURCE=default
+# comment to disable Grafana links
+GRAFANA_DATASOURCE="default"
 
-# set to enable silence link
-#ALERTMANAGER_URL=https://alertmanager.example.com
+# comment to disable silence link
+ALERTMANAGER_URL="https://alertmanager.example.com"

LICENSE

@@ -1,11 +1,6 @@
-### After July 10 2024
-
-All changes are done by Open Engineering and Jesse Hitch
-
-### Prior to July 10 2024, all code is MIT copyright J. Robinson
-
 MIT License
 
+Copyright (c) 2024 Jesse Hitch
 Copyright (c) 2018 Jason Robinson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

README.md

@@ -13,32 +13,63 @@ A bot to receive Prometheus Alertmanager webhook events and forward them to chos
 
 </details>
 
-Main features:
-
-* Uses pre-created Matrix user to send alerts using token auth.
-* Configurable room per alert receiver.
-* Automatic joining of configured rooms. Private rooms require an invite.
-* Secret key authentication with Alertmanager.
-* HTML formatted messages.
+### Main features
+
+* Uses pre-created Matrix user to send alerts using token auth
+  * you can also use an [application service](https://spec.matrix.org/v1.11/application-service-api/) to register a new user
+* Configurable room per alert receiver
+* Automatic joining of configured rooms. Private rooms require an invite
+* Secret key authentication with Alertmanager
+* HTML formatted messages
 * Optionally mentions `@room` on firing alerts
+* Optionally set the bot user's display name and avatar
 
-## How to use
+# How to use
 
-### Configuration
+## Running the bot in a Docker container
 
-Whether running manually or via the Docker image, the configuration is set
-via environment variables. When running manually, copy `.env.default`
-into `.env`, set the values and they will be loaded automatically.
+We host a docker image that builds nightly here: [jessebot/matrix-alertmanager-bot](https://hub.docker.com/repository/docker/jessebot/matrix-alertmanager-bot). Nightly builds are tagged with `main`. Checkout out [`.env.default`](./.env.default) for the possible env vars to pass in.
 
-When using the Docker image, set the environment variables when running
-the container.
+## Registering the Application Service with matrix
+Matrix has a concept of [application services](https://spec.matrix.org/v1.11/application-service-api/) (often called an appservice), for bot services/users. To register this bot as an application service, you need to create a registration yaml file, such as `alertmanager.yaml` that's accessible locally to your matrix homeserver (such as synapse), and it should have the following contents:
 
-### Docker
+```yaml
+# A unique, user-defined ID of the application service which will never change.
+id: alertmanager
+# The URL for the application service. May include a path after the domain name.
+# Optionally set to null if no traffic is required.
+# this is an example but it can be whatever URL and port you host this bot at
+url: http://matrix-stack-bridge-alertmanager:3000
+#  Whether requests from masqueraded users are rate-limited. The sender is excluded.
+rate_limited: false
+# The localpart of the user associated with the application service.
+# Events will be sent to the AS if this user is the target of the event, or is a
+# joined member of the room where the event occurred.
+sender_localpart: alertmanager
+# A secret token that the application service will use to authenticate requests to the homeserver.
+as_token: "soemthingverysecurebutdefinitelynotthisexactstringuseyourbestjudgementwitharandomgenerator"
+# A secret token that the homeserver will use authenticate requests to the application service.
+hs_token: "soemthingelseverysecurebutdefinitelynotthisexactstringuseyourbestjudgementwitharandomgenerator"
+# The namespaces that the application service is interested in.
+# https://spec.matrix.org/v1.11/application-service-api/#definition-registration_namespaces
+namespaces:
+  # https://spec.matrix.org/v1.11/application-service-api/#definition-registration_namespace
+  users:
+    - exclusive: true
+      regex: "^@alertmanager.*:mymatrix.server.tld$"
+    - exclusive: true
+      regex: "^@:mymatrix.server.tld$"
+```
 
-Still working on this, but when available, it will be here: https://hub.docker.com/r/jessebot/matrix-alertmanager-bot
+Then, in your `homeserver.yaml`, you need to include reference to the above registration yaml file, so for example, if you saved that file to `/bridges/alertmanager.yaml`, you'd add the following to your homeserver config:
 
+```yaml
+# A list of application service config files to use
+app_service_config_files:
+  - "/bridges/alertmanager.yaml"
+```
 
-### Alertmanager
+## Setting up Alertmanager
 
 You will need to configure a webhook receiver in Alertmanager. It should looks something like this:
 
@@ -51,7 +82,7 @@ receivers:
 
 The secret key obviously should match the one in the alertmanager configuration.
 
-### Prometheus rules
+## Styling Prometheus rules
 
 Add some styling to your prometheus rules
 
@@ -69,6 +100,104 @@ rules:
 
 NOTE! Currently the bot cannot talk HTTPS, so you need to have a reverse proxy in place to terminate SSL, or use unsecure unencrypted connections.
 
+## Running in Kubernetes
+
+[small-hack/matrix-chart](https://github.com/small-hack/matrix-chart) is a matrix stack for Kubernetes that includes this bot. In your values.yaml include:
+
+```yaml
+bridges:
+  alertmanager:
+    enabled: true
+    image:
+      # -- alertmanager bridge docker image
+      repository: "jessebot/matrix-alertmanager-bot"
+      # -- alertmanager bridge docker image tag
+      tag: "0.11.0"
+      # -- alertmanager bridge docker image pull policy. If tag is "latest", set tag to "Always"
+      pullPolicy: IfNotPresent
+
+    service:
+      # -- service type for the alertmanager bridge
+      type: ClusterIP
+
+    # -- alertmanager bridge pod replicas
+    replicaCount: 1
+
+    # -- set the revisionHistoryLimit to decide how many replicaSets are
+    # kept when you change a deployment. Explicitly setting this field to 0,
+    # will result in cleaning up all the history of your Deployment thus that
+    # Deployment will not be able to roll back.
+    revisionHistoryLimit: 2
+
+    existingSecret:
+      registration: ""
+
+    # this section is for registering the application service with matrix
+    # read more about application services here:
+    # https://spec.matrix.org/v1.11/application-service-api/
+    registration:
+      # -- name of the application service
+      id: "alertmanager"
+      # -- url of the alertmanager service. if not provided, we will template it
+      # for you like http://matrix-alertmanager-service:3000
+      url: ""
+      # -- should this bot be rate limited?
+      rate_limited: false
+      # -- localpart of the user associated with the application service.
+      # Events will be sent to the AS if this user is the target of the event,
+      # or is a joined member of the room where the event occurred.
+      sender_localpart: "alertmanager"
+      # A secret token that the application service will use to authenticate
+      # requests to the homeserver.
+      as_token: ""
+      # -- Use an existing Kubernetes Secret to store your own generated appservice
+      # and homeserver tokens. If this is not set, we'll generate them for you.
+      # Setting this won't override the ENTIRE registration.yaml we generate for
+      # the synapse pod to authenticate mautrix/discord. It will only replaces the tokens.
+      # To replaces the ENTIRE registration.yaml, use
+      # bridges.alertmanager.existingSecret.registration
+      existingSecret: ""
+      existingSecretKeys:
+        # -- key in existingSecret for as_token (application service token). If
+        # provided and existingSecret is set, ignores bridges.alertmanager.registration.as_token
+        as_token: "as_token"
+        # -- key in existingSecret for hs_token (home server token)
+        hs_token: "hs_token"
+
+    encryption: false
+
+    config:
+      # -- appservice port?
+      app_port: 3000
+      # -- secret key for the webhook events, I don't know what this is
+      app_alertmanager_secret: ""
+      # -- your homeserver url, e.g. https://homeserver.tld
+      homeserver_url: ""
+
+      bot:
+        # -- user in matrix for the the alertmanager bot e.g. alertmanager
+        # which becomes @alertmanager:homeserver.tld
+        user: ""
+        # -- optional: display name to set for the bot user
+        display_name: ""
+        # -- optional: mxc:// avatar to set for the bot user
+        avatar_url: ""
+        # -- rooms to send alerts to, separated by a |
+        # Each entry contains the receiver name (from alertmanager) and the
+        # internal id (not the public alias) of the Matrix channel to forward to.
+        rooms: ""
+        # -- Set this to true to make firing alerts do a `@room` mention.
+        # NOTE! Bot should also have enough power in the room for this to be useful.
+        mention_room: false
+
+      # -- set to enable Grafana links, e.g. https://grafana.example.com
+      grafana_url: ""
+      # -- grafana data source, e.g. default
+      grafana_datasource: ""
+      # -- set to enable silence link, e.g. https://alertmanager.example.com
+      alertmanager_url: ""
+```
+
 ## TODO
 
 * Registering an account instead of having to use an existing account
@@ -79,11 +208,11 @@ NOTE! Currently the bot cannot talk HTTPS, so you need to have a reverse proxy i
 - Express
 - Matrix JS SDK
 
-## Status
+## Authors and Maintainers
 
-This project was originally created by [Jason Robinson](https://jasonrobinson.me) / @jaywink:federator.dev
+This project was originally created by [Jason Robinson](https://jasonrobinson.me) and then it was forked by [beeper/matrix-alertmanager] but they didn't add their own copyright notice, and then I, [@jessebot](https://github.com/jessebot), from [@small-hack](https://github.com/small-hack) forked it as well.
 
-It is now maintained by [small-hack](https://github.com/small-hack) and [@jessebot](https://github.com/jessebot). We're actively cleaning up the security alerts and adding renovatebot to keep it all up to date.
+I've started cleaning up the security alerts and adding plan on renovatebot to keep it all up to date. I'll try to also create some PRs to update the other codebases as well :)
 
 ## License
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "matrix-alertmanager",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Prometheus Alertmanager bot for Matrix",
   "main": "src/app.js",
   "scripts": {

src/client.js

@@ -35,6 +35,16 @@ const client = {
                 await this.ensureInRoom(room[1])
             }
         })
+
+        // ensure display name is updated
+        if (process.env.MATRIX_DISPLAY_NAME) {
+            this.connection.setDisplayName(process.env.MATRIX_DISPLAY_NAME);
+        }
+
+        // ensure avatar is updated
+        if (process.env.MATRIX_AVATAR_URL) {
+            this.connection.setAvatarUrl(process.env.MATRIX_AVATAR_URL);
+        }
     },
     sendAlert: async function(roomId, alert) {
         await this.ensureInRoom(roomId)