mirror of
https://github.com/etkecc/synapse-admin.git
synced 2024-11-21 07:15:20 +03:00
add config docs
This commit is contained in:
parent
75b9aeea01
commit
5f7f587477
5 changed files with 102 additions and 0 deletions
|
@ -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
94
docs/config.md
Normal 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue