From 5f7f58747741606ccb2ea598001bd43937d91185 Mon Sep 17 00:00:00 2001 From: Aine Date: Wed, 20 Nov 2024 13:02:45 +0200 Subject: [PATCH] add config docs --- README.md | 2 + docs/config.md | 94 ++++++++++++++++++++++++++++++++++++++++++++ docs/custom-menu.md | 2 + docs/restrict-hs.md | 2 + docs/system-users.md | 2 + 5 files changed, 102 insertions(+) create mode 100644 docs/config.md diff --git a/README.md b/README.md index a0dc571..557206e 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,8 @@ In case you use [spantaleev/matrix-docker-ansible-deploy](https://github.com/spa [etkecc/ansible](https://github.com/etkecc/ansible), configuration will be automatically added to the `/.well-known/matrix/client` file. +[Configuration options](config.md) + The `config.json` can be injected into a Docker container using a bind mount. ```yml diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..01f75ac --- /dev/null +++ b/docs/config.md @@ -0,0 +1,94 @@ +# Configuration + +Synapse Admin could be configured using the following ways (both are optional, and both could be used together): + +* By providing the `config.json` file alongside with the Synapse Admin deployment, example: [admin.etke.cc/config.json](https://admin.etke.cc/config.json) +* By providing configuration under the `cc.etke.synapse-admin` key in the `/.well-known/matrix/client` file, example: +[demo.etke.host/.well-known/matrix/client](https://demo.etke.host/.well-known/matrix/client) + +In case you are an [etke.cc](https://etke.cc) customer, +or use [spantaleev/matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy), +or [etkecc/ansible](https://github.com/etkecc/ansible), +configuration will be automatically added to the `/.well-known/matrix/client` file. + +**Why `/.well-known/matrix/client`?** + +Because any instance of Synapse Admin will automatically pick up the configuration from the homeserver. +Common use case when you have a Synapse server running, but don't want (or can't) deploy Synapse Admin alongside with it. +In this case, you could provide the configuration in the `/.well-known/matrix/client` file, +and any Synapse Admin instance (e.g., [admin.etke.cc](https://admin.etke.cc) will pick it up. + +Another common case is when you have multiple Synapse servers running and want to use a single Synapse Admin instance to manage them all. +In this case, you could provide the configuration in the `/.well-known/matrix/client` file for each of the servers. + +## Configuration options + +* `restrictBaseUrl` - restrictBaseUrl restricts the Synapse Admin instance to work only with specific homeserver(-s). + It accepts both a string and an array of strings. + The homeserver URL should be the _actual_ homeserver URL, and not the delegated one. + Example: `https://matrix.example.com` or `https://synapse.example.net` + [More details](restrict-hs.md) +* `asManagedUsers` - protect system user accounts managed by appservices (such as bridges) / system (such as bots) from accidental changes. + By defining a list of MXID regex patterns, you can protect these accounts from accidental changes. + Example: `^@baibot:example\\.com$`, `^@slackbot:example\\.com$`, `^@slack_[a-zA-Z0-9\\-]+:example\\.com$`, `^@telegrambot:example\\.com$`, `^@telegram_[a-zA-Z0-9]+:example\\.com$` + [More details](system-users.md) +* `menu` - add custom menu items to the main menu (sidebar) by providing a `menu` array in the config. + Each `menu` item can contain the following fields: + * `label` (required): The text to display in the menu. + * `icon` (optional): The icon to display next to the label, one of the [../src/components/icons.ts] icons, otherwise a default icon will be used. + * `url` (required): The URL to navigate to when the menu item is clicked. + [More details](custom-menu.md) + +## Examples + +### config.json + +```json +{ + "restrictBaseUrl": [ + "https://matrix.example.com", + "https://synapse.example.net" + ], + "asManagedUsers": [ + "^@baibot:example\\.com$", + "^@slackbot:example\\.com$", + "^@slack_[a-zA-Z0-9\\-]+:example\\.com$", + "^@telegrambot:example\\.com$", + "^@telegram_[a-zA-Z0-9]+:example\\.com$" + ], + "menu": [ + { + "label": "Contact support", + "icon": "SupportAgent", + "url": "https://github.com/etkecc/synapse-admin/issues" + } + ] +} +``` + +### `/.well-known/matrix/client` + +```json +{ + "cc.etke.synapse-admin": { + "restrictBaseUrl": [ + "https://matrix.example.com", + "https://synapse.example.net" + ], + "asManagedUsers": [ + "^@baibot:example\\.com$", + "^@slackbot:example\\.com$", + "^@slack_[a-zA-Z0-9\\-]+:example\\.com$", + "^@telegrambot:example\\.com$", + "^@telegram_[a-zA-Z0-9]+:example\\.com$" + ], + "menu": [ + { + "label": "Contact support", + "icon": "SupportAgent", + "url": "https://github.com/etkecc/synapse-admin/issues" + } + ] + } +} +``` diff --git a/docs/custom-menu.md b/docs/custom-menu.md index 93a4576..6422ba3 100644 --- a/docs/custom-menu.md +++ b/docs/custom-menu.md @@ -14,6 +14,8 @@ Each `menu` item can contain the following fields: default icon will be used. * `url` (required): The URL to navigate to when the menu item is clicked. +[Configuration options](config.md) + ### config.json ```json diff --git a/docs/restrict-hs.md b/docs/restrict-hs.md index fb22d32..63cbb73 100644 --- a/docs/restrict-hs.md +++ b/docs/restrict-hs.md @@ -17,6 +17,8 @@ So, if you have a homeserver `example.com` where users have MXIDs like `@user:ex but actual Synapse is installed on `matrix.example.com` subdomain, you should use `https://matrix.example.com` in the configuration. +[Configuration options](config.md) + ### config.json ```json diff --git a/docs/system-users.md b/docs/system-users.md index fec91c9..e60ebce 100644 --- a/docs/system-users.md +++ b/docs/system-users.md @@ -15,6 +15,8 @@ The examples below contain the configuration settings to mark and [Baibot](https://github.com/etkecc/baibot) users of `example.com` homeserver as appservice-managed users, just to illustrate the options to protect both specific MXIDs (as in the Baibot example) and all puppets of a bridge (as in the Telegram and Slack examples). +[Configuration options](config.md) + ### config.json ```json