aboutsummaryrefslogtreecommitdiffstats
path: root/doc/mod/notification-matrix.md
diff options
context:
space:
mode:
authorGravatar Michael Gisbers <michael@gisbers.de>2022-02-21 18:21:26 +0100
committerGravatar Christian Hesse <mail@eworm.de>2022-03-01 12:38:54 +0100
commitc35485454c60ae489fd5b9fb7d0afde566cae645 (patch)
tree01dee12d6738fdcb01ddd14c579f11dc1199f86f /doc/mod/notification-matrix.md
parenta00e912bb5c556eaead42a4213c545a34c3959d9 (diff)
doc/mod/notification-matrix: add verbose steps for setup
Modified-by: Christian Hesse <mail@eworm.de>
Diffstat (limited to 'doc/mod/notification-matrix.md')
-rw-r--r--doc/mod/notification-matrix.md59
1 files changed, 57 insertions, 2 deletions
diff --git a/doc/mod/notification-matrix.md b/doc/mod/notification-matrix.md
index e357b5b..91a39e5 100644
--- a/doc/mod/notification-matrix.md
+++ b/doc/mod/notification-matrix.md
@@ -21,13 +21,68 @@ Just install the module:
$ScriptInstallUpdate mod/notification-matrix;
Also install a Matrix client on at least one of your mobile and/or desktop
-devices and create an account.
+devices. As there is no privilege separation you should create a dedicated
+notification account, in addition to your general user account.
Configuration
-------------
Edit `global-config-overlay`, add `MatrixHomeServer`, `MatrixAccessToken` and
-`MatrixRoom`. Then reload the configuration.
+`MatrixRoom` - see below on hints how to retrieve this information. Then
+reload the configuration.
+
+### Home server
+
+Matrix user accounts are identified by a unique user id in the form of
+`@localpart:domain`. The `domain` part is not necessarily your home server
+address, you have to resolve it with the procedure described in the
+[Matrix specification](https://spec.matrix.org/latest/client-server-api/#server-discovery).
+
+Your best bet is to query the server at `domain` with the
+[well-known uri](https://spec.matrix.org/latest/client-server-api/#well-known-uri).
+For "*matrix.org*" this query is:
+
+ / tool fetch "https://matrix.org/.well-known/matrix/client" output=user;
+
+![home server](notification-matrix.d/01-home-server.avif)
+
+So the home server for "*matrix.org*" is "*matrix-client.matrix.org*".
+Please strip the protocol ("*https://*") for `MatrixHomeServer` if given.
+
+### Access token
+
+After discovering the correct home server an access token has to be created.
+For this the login credentials (username and password) of the notification
+account must be sent to the home server via
+[client server api](https://matrix.org/docs/guides/client-server-api#login).
+
+We use the home server discovered above, "*matrix-client.matrix.org*".
+The user is "*example*" and password is "*v3ry-s3cr3t*".
+
+ / tool fetch "https://matrix-client.matrix.org/_matrix/client/r0/login" http-method=post http-data="{\"type\":\"m.login.password\", \"user\":\"example\", \"password\":\"v3ry-s3cr3t\"}" output=user;
+
+![access token](notification-matrix.d/02-access-token.avif)
+
+The server replied with a JSON object containing the `access_token`, use that
+for `MatrixAccessToken`.
+
+### Room
+
+Every Matix chat is a room, so we have to create one. Do so with your general
+user, this makes sure your general user is the room owner. Then join the room
+and invite the notification user by its user id "*@example:matrix.org*". Look
+up the room id within the Matrix client, it should read like
+"*!WUcxpSjKyxSGelouhA:matrix.org*". Use that for `MatrixRoom`.
+
+Finally join the notification user to the room by accepting the invite. Again,
+this can be done with
+[client server api](https://matrix.org/docs/guides/client-server-api#joining-a-room-via-an-invite).
+Make sure to replace room id ("*!*" is escaped with "*%21*") and access token
+with your data.
+
+ / tool fetch "https://matrix-client.matrix.org/_matrix/client/r0/rooms/%21WUcxpSjKyxSGelouhA:matrix.org/join?access_token=yt_ZXdvcm0tdGVzdA_NNqUyvKHRhBLZmnzVVSK_0xu6yN" http-method=post http-data="" output=user;
+
+![join room](notification-matrix.d/03-join-room.avif)
Usage and invocation
--------------------