add config docs

This commit is contained in:
Aine 2024-11-20 13:02:45 +02:00
parent 75b9aeea01
commit 5f7f587477
No known key found for this signature in database
GPG key ID: 34969C908CCA2804
5 changed files with 102 additions and 0 deletions

View file

@ -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

94
docs/config.md Normal file
View file

@ -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"
}
]
}
}
```

View file

@ -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

View file

@ -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

View file

@ -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