mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2026-04-04 13:46:59 +03:00
Synapse Admin is Ketesa now! (#5113)
* Synapse Admin is Ketesa now! * i18n changes * add automatic migration * fix migration version in vars * add a note about routing for OIDC Auth * mention v1.0.0 announcement blog post * Update docs/container-images.md Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> * Update CHANGELOG.md Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com> --------- Co-authored-by: Suguru Hirahara <luixxiul@users.noreply.github.com>
This commit is contained in:
Aine
GitHub
@@ -414,7 +414,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password. (This note applies to password authentication mode.)
|
||||
- If you change the bot password (`matrix_bot_baibot_config_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_baibot_config_user_password` to let the bot know its new password. (This note applies to password authentication mode.)
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -89,7 +89,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_buscarron_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password.
|
||||
- If you change the bot password (`matrix_bot_buscarron_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_buscarron_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -102,7 +102,7 @@ This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synap
|
||||
|
||||
**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
|
||||
|
||||
The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
|
||||
The APIs can also be accessed via [Ketesa](https://github.com/etkecc/ketesa), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Ketesa for you. For details about it, see [this page](configuring-playbook-ketesa.md).
|
||||
|
||||
#### Add the configuration
|
||||
|
||||
@@ -212,7 +212,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_draupnir_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_draupnir_password` to let the bot know its new password.
|
||||
- If you change the bot password (`matrix_bot_draupnir_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_draupnir_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -78,7 +78,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_honoroit_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password.
|
||||
- If you change the bot password (`matrix_bot_honoroit_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_honoroit_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_matrix_registration_bot_bot_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_registration_bot_bot_password` to let the bot know its new password.
|
||||
- If you change the bot password (`matrix_bot_matrix_registration_bot_bot_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_matrix_registration_bot_bot_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password.
|
||||
- If you change the bot password (`matrix_bot_matrix_reminder_bot_matrix_user_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_matrix_reminder_bot_matrix_user_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -103,7 +103,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bot password (`matrix_bot_maubot_initial_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password.
|
||||
- If you change the bot password (`matrix_bot_maubot_initial_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_maubot_initial_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synap
|
||||
|
||||
**Note**: access to the APIs is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, doing so is not recommended for additional security. See [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints).
|
||||
|
||||
The APIs can also be accessed via [Synapse Admin](https://github.com/etkecc/synapse-admin), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
|
||||
The APIs can also be accessed via [Ketesa](https://github.com/etkecc/ketesa), a web UI tool you can use to administrate users, rooms, media, etc. on your Matrix server. The playbook can install and configure Ketesa for you. For details about it, see [this page](configuring-playbook-ketesa.md).
|
||||
|
||||
#### Add the configuration
|
||||
|
||||
@@ -198,7 +198,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the Pantalaimon's password (`matrix_bot_mjolnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_mjolnir_pantalaimon_password` to let Pantalaimon know its new password.
|
||||
- If you change the Pantalaimon's password (`matrix_bot_mjolnir_pantalaimon_password` in your `vars.yml` file) subsequently, its credentials on the homeserver won't be updated automatically. If you'd like to change the password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_mjolnir_pantalaimon_password` to let Pantalaimon know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -87,7 +87,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed.
|
||||
|
||||
- If you change the bridge's bot password (`matrix_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_postmoogle_password` to let the bot know its new password.
|
||||
- If you change the bridge's bot password (`matrix_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_postmoogle_password` to let the bot know its new password.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ Element Admin is a web-based administration panel for Synapse and [Matrix Authen
|
||||
|
||||
See the project's [documentation](https://github.com/element-hq/element-admin) to learn more.
|
||||
|
||||
💡 **Note**: This project is still very young and doesn't have many features. For now, it's recommended to use [Synapse Admin](./configuring-playbook-synapse-admin.md) instead. Deployments that use [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) can use Element Admin for user-management (something that Synapse Admin can't do), while continuing to use Synapse Admin for all other purposes.
|
||||
💡 **Note**: This project is still very young and doesn't have many features. [Ketesa](./configuring-playbook-ketesa.md) is the fully-featured alternative — it covers all Synapse and MAS Admin APIs, including complete user management, session management, and MAS policy data. Element Admin remains a valid choice if you prefer its interface.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
||||
100
docs/configuring-playbook-ketesa.md
Normal file
100
docs/configuring-playbook-ketesa.md
Normal file
@@ -0,0 +1,100 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2020-2024 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2020-2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2021 Aaron Raimist
|
||||
SPDX-FileCopyrightText: 2023 Christian González
|
||||
SPDX-FileCopyrightText: 2024 Nikita Chernyi
|
||||
SPDX-FileCopyrightText: 2024 Uğur İLTER
|
||||
SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
|
||||
SPDX-FileCopyrightText: 2026 Nikita Chernyi
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up Ketesa (optional)
|
||||
|
||||
The playbook can install and configure [Ketesa](https://github.com/etkecc/ketesa) for you.
|
||||
|
||||
Ketesa is a fully-featured admin interface for Matrix homeservers — manage users, rooms, media, sessions, and more from one clean, responsive web UI. It is the evolution of [Awesome-Technologies/synapse-admin](https://github.com/Awesome-Technologies/synapse-admin): what began as a fork has grown into its own independent project with a redesigned interface, comprehensive Synapse and MAS API coverage, and multi-language support. See the [Ketesa v1.0.0 announcement](https://etke.cc/blog/introducing-ketesa/) for a full overview of what's new.
|
||||
|
||||
>[!NOTE]
|
||||
>
|
||||
> - Ketesa does not work with other homeserver implementations than Synapse due to API's incompatibility.
|
||||
> - The latest version of Ketesa is hosted by [etke.cc](https://etke.cc/) at [admin.etke.cc](https://admin.etke.cc/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting.
|
||||
> - This playbook also supports an alternative management UI in the shape of [Element Admin](./configuring-playbook-element-admin.md). Please note that it's currently less feature-rich than Ketesa and requires [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md).
|
||||
|
||||
## Adjusting DNS records (optional)
|
||||
|
||||
By default, this playbook installs Ketesa on the `matrix.` subdomain, at the `/synapse-admin` path (https://matrix.example.com/synapse-admin) — the legacy path is kept for backward compatibility. This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
|
||||
|
||||
If you wish to adjust it, see the section [below](#adjusting-the-ketesa-url-optional) for details about DNS configuration.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Ketesa, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_ketesa_enabled: true
|
||||
```
|
||||
|
||||
**Note**: Ketesa requires Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). Because Ketesa needs these APIs to function, when installing Ketesa, the playbook **automatically** exposes the Synapse Admin API publicly for you. Depending on the homeserver implementation you're using (Synapse, Dendrite), this is equivalent to:
|
||||
|
||||
- for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true`
|
||||
- for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true`
|
||||
|
||||
By default, Ketesa installation will be [restricted to only work with one homeserver](https://github.com/etkecc/ketesa/blob/main/README.md#restricting-available-homeserver) — the one managed by the playbook. To adjust these restrictions, tweak the `matrix_ketesa_config_restrictBaseUrl` variable.
|
||||
|
||||
### Adjusting the Ketesa URL (optional)
|
||||
|
||||
By tweaking the `matrix_ketesa_hostname` and `matrix_ketesa_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
|
||||
|
||||
We recommend updating the path prefix to `/ketesa` to align with the new branding, while the default `/synapse-admin` is kept for backward compatibility:
|
||||
|
||||
```yaml
|
||||
matrix_ketesa_path_prefix: /ketesa
|
||||
```
|
||||
|
||||
Or to change the hostname entirely:
|
||||
|
||||
```yaml
|
||||
# Change the default hostname and path prefix
|
||||
matrix_ketesa_hostname: admin.example.com
|
||||
matrix_ketesa_path_prefix: /
|
||||
```
|
||||
|
||||
If you've changed the default hostname, you may need to create a CNAME record for the Ketesa domain (`admin.example.com`), which targets `matrix.example.com`.
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-ketesa/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_ketesa_configuration_extension_json` variable
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
After installation, Ketesa will be accessible at: `https://matrix.example.com/synapse-admin/` (or `/ketesa/` if you updated the path prefix as recommended)
|
||||
|
||||
To use Ketesa, you need to have [registered at least one administrator account](registering-users.md) on your server.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-ketesa`.
|
||||
|
||||
If you have questions, you can join this community room and feel free to ask: [#ketesa:etke.cc](https://matrix.to/#/#ketesa:etke.cc)
|
||||
@@ -51,7 +51,7 @@ This section details what you can expect when switching to the Matrix Authentica
|
||||
|
||||
- ❌ **Synapse password providers will need to be disabled**. You can no longer use [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc. When the authentication flow is handled by MAS (not by Synapse anymore), it doesn't make sense to extend the Synapse authentication flow with additional modules. Many bridges used to rely on shared-secret-auth for doing double-puppeting (impersonating other users), but most (at least the mautrix bridges) nowadays use [Appservice Double Puppet](./configuring-playbook-appservice-double-puppet.md) as a better alternative. Older/maintained bridges may still rely on shared-secret-auth, as do other services like [matrix-corporal](./configuring-playbook-matrix-corporal.md).
|
||||
|
||||
- ❌ Certain **tools like [Synapse Admin](./configuring-playbook-synapse-admin.md) do not have full compatibility with MAS yet**. Synapse Admin already supports OIDC auth, browsing users (which Synapse will internally fetch from MAS) and updating user avatars. However, editing users (passwords, etc.) now needs to happen directly against MAS using the [MAS Admin API](https://element-hq.github.io/matrix-authentication-service/api/index.html), which Synapse Admin cannot interact with yet. You may be interested in using [Element Admin](./configuring-playbook-element-admin.md) for these purposes.
|
||||
- ✅ **[Ketesa](./configuring-playbook-ketesa.md) has full MAS integration**. Ketesa supports OIDC auth, user management, all session types (browser, OAuth2, compatibility), linked email addresses, upstream OAuth provider links, MAS policy data, and user creation through MAS. It is the recommended tool for managing homeservers running MAS.
|
||||
|
||||
- ❌ **Some services experience issues when authenticating via MAS**:
|
||||
|
||||
|
||||
@@ -1,93 +0,0 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2020-2024 MDAD project contributors
|
||||
SPDX-FileCopyrightText: 2020-2024 Slavi Pantaleev
|
||||
SPDX-FileCopyrightText: 2021 Aaron Raimist
|
||||
SPDX-FileCopyrightText: 2023 Christian González
|
||||
SPDX-FileCopyrightText: 2024 Nikita Chernyi
|
||||
SPDX-FileCopyrightText: 2024 Uğur İLTER
|
||||
SPDX-FileCopyrightText: 2024-2026 Suguru Hirahara
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up Synapse Admin (optional)
|
||||
|
||||
The playbook can install and configure Synapse Admin for you.
|
||||
|
||||
Synapse Admin is a web UI tool you can use to **administrate users, rooms, media, etc. on your Matrix homeserver**. This playbook is configured to install [etkecc/synapse-admin](https://github.com/etkecc/synapse-admin), which is a [feature-rich](https://github.com/etkecc/synapse-admin#fork-differences) fork of [Awesome-Technologies/synapse-admin](https://github.com/Awesome-Technologies/synapse-admin).
|
||||
|
||||
>[!NOTE]
|
||||
>
|
||||
> - Synapse Admin does not work with other homeserver implementations than Synapse due to API's incompatibility.
|
||||
> - The latest version of Synapse Admin is hosted by [etke.cc](https://etke.cc/) at [admin.etke.cc](https://admin.etke.cc/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting.
|
||||
> - This playbook also supports an alternative management UI in the shape of [Element Admin](./configuring-playbook-element-admin.md). Please note that it's currently less feature-rich than Synapse Admin and requires [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md).
|
||||
|
||||
## Adjusting DNS records (optional)
|
||||
|
||||
By default, this playbook installs Synapse Admin on the `matrix.` subdomain, at the `/synapse-admin` path (https://matrix.example.com/synapse-admin). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
|
||||
|
||||
If you wish to adjust it, see the section [below](#adjusting-the-synapse-admin-url-optional) for details about DNS configuration.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_synapse_admin_enabled: true
|
||||
```
|
||||
|
||||
**Note**: Synapse Admin requires Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) to function. Access to them is restricted with a valid access token, so exposing them publicly should not be a real security concern. Still, for additional security, we normally leave them unexposed, following [official Synapse reverse-proxying recommendations](https://element-hq.github.io/synapse/latest/reverse_proxy.html#synapse-administration-endpoints). Because Synapse Admin needs these APIs to function, when installing Synapse Admin, the playbook **automatically** exposes the Synapse Admin API publicly for you. Depending on the homeserver implementation you're using (Synapse, Dendrite), this is equivalent to:
|
||||
|
||||
- for [Synapse](./configuring-playbook-synapse.md) (our default homeserver implementation): `matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true`
|
||||
- for [Dendrite](./configuring-playbook-dendrite.md): `matrix_dendrite_container_labels_public_client_synapse_admin_api_enabled: true`
|
||||
|
||||
By default, synapse-admin installation will be [restricted to only work with one homeserver](https://github.com/etkecc/synapse-admin/blob/e21e44362c879ac41f47c580b04210842b6ff3d7/README.md#restricting-available-homeserver) — the one managed by the playbook. To adjust these restrictions, tweak the `matrix_synapse_admin_config_restrictBaseUrl` variable.
|
||||
|
||||
### Adjusting the Synapse Admin URL (optional)
|
||||
|
||||
By tweaking the `matrix_synapse_admin_hostname` and `matrix_synapse_admin_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
|
||||
|
||||
Example additional configuration for your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# Change the default hostname and path prefix
|
||||
matrix_synapse_admin_hostname: admin.example.com
|
||||
matrix_synapse_admin_path_prefix: /
|
||||
```
|
||||
|
||||
If you've changed the default hostname, you may need to create a CNAME record for the Synapse Admin domain (`admin.example.com`), which targets `matrix.example.com`.
|
||||
|
||||
When setting, replace `example.com` with your own.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the component.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-synapse-admin/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_synapse_admin_configuration_extension_json` variable
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Usage
|
||||
|
||||
After installation, Synapse Admin will be accessible at: `https://matrix.example.com/synapse-admin/`
|
||||
|
||||
To use Synapse Admin, you need to have [registered at least one administrator account](registering-users.md) on your server.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-synapse-admin`.
|
||||
|
||||
If you have questions, you can join this community room and feel free to ask: [#synapse-admin:etke.cc](https://matrix.to/#/#synapse-admin:etke.cc)
|
||||
@@ -196,11 +196,11 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
|
||||
|
||||
## Usage
|
||||
|
||||
### Synapse Admin
|
||||
### Ketesa
|
||||
|
||||
With [Synapse Admin](configuring-playbook-synapse-admin.md), certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace.
|
||||
[Ketesa](configuring-playbook-ketesa.md) is a fully-featured web UI for administrating your homeserver — managing users, rooms, media, sessions, and more.
|
||||
|
||||
The playbook can install and configure Synapse Admin for you. For details about it, see [this page](configuring-playbook-synapse-admin.md).
|
||||
The playbook can install and configure Ketesa for you. For details about it, see [this page](configuring-playbook-ketesa.md).
|
||||
|
||||
### Monitoring Synapse Metrics with Prometheus and Grafana
|
||||
|
||||
|
||||
@@ -102,7 +102,7 @@ Extend and modify how users are authenticated on your homeserver.
|
||||
|
||||
- [Setting up Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md)
|
||||
|
||||
- [Setting up Synapse Admin](configuring-playbook-synapse-admin.md)
|
||||
- [Setting up Ketesa](configuring-playbook-ketesa.md)
|
||||
|
||||
- [Setting up matrix-registration](configuring-playbook-matrix-registration.md)
|
||||
|
||||
|
||||
@@ -134,7 +134,7 @@ Services that help you in administrating and monitoring your Matrix installation
|
||||
| ------- | --------------- | -------- | ----------- |
|
||||
| [matrix-alertmanager-receiver](configuring-playbook-alertmanager-receiver.md) | [metio/matrix-alertmanager-receiver](https://hub.docker.com/r/metio/matrix-alertmanager-receiver) | ❌ | Prometheus' [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) client |
|
||||
| [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md) | [element-hq/matrix-authentication-service](https://ghcr.io/element-hq/matrix-authentication-service) | ❌ | OAuth 2.0 and OpenID Provider server |
|
||||
| [synapse-admin](configuring-playbook-synapse-admin.md) | [etke.cc/synapse-admin](https://ghcr.io/etkecc/synapse-admin) | ❌ | Web UI tool for administrating users and rooms on your Matrix server |
|
||||
| [Ketesa](configuring-playbook-ketesa.md) | [etkecc/ketesa](https://ghcr.io/etkecc/ketesa) | ❌ | Fully-featured web UI for administrating your Matrix homeserver — users, rooms, media, sessions, and more |
|
||||
| [Metrics and Graphs](configuring-playbook-prometheus-grafana.md) | [prom/prometheus](https://hub.docker.com/r/prom/prometheus/) | ❌ | [Prometheus](https://prometheus.io) time-series database server |
|
||||
| [Metrics and Graphs](configuring-playbook-prometheus-grafana.md) | [prom/node-exporter](https://hub.docker.com/r/prom/node-exporter/) | ❌ | Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter |
|
||||
| [Metrics and Graphs](configuring-playbook-prometheus-grafana.md) | [grafana/grafana](https://hub.docker.com/r/grafana/grafana/) | ❌ | Graphing tool that works well with the above two images. Our playbook also adds two dashboards for [Synapse](https://github.com/element-hq/synapse/tree/master/contrib/grafana) and [Node Exporter](https://github.com/rfrail3/grafana-dashboards) |
|
||||
|
||||
@@ -95,10 +95,7 @@ This `register-user` script actually invokes the `mas-cli manage register-user`
|
||||
|
||||
## Managing users via a Web UI
|
||||
|
||||
To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).
|
||||
|
||||
> [!WARNING]
|
||||
> If you're using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), note that user management via synapse-admin is not fully working yet. See the [Expectations](configuring-playbook-matrix-authentication-service.md#expectations) section for more information.
|
||||
To manage users and your homeserver more easily (via a web interface), you can install [Ketesa](configuring-playbook-ketesa.md) — a fully-featured admin UI covering users, rooms, media, sessions, and MAS management.
|
||||
|
||||
## Letting certain users register on your private server
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ Note that **not all components support self-building yet**.
|
||||
|
||||
Possibly outdated list of roles where self-building the Docker image is currently possible:
|
||||
- `matrix-synapse`
|
||||
- `matrix-synapse-admin`
|
||||
- `matrix-ketesa`
|
||||
- `matrix-client-element`
|
||||
- `hydrogen`
|
||||
- `cinny`
|
||||
|
||||
Reference in New Issue
Block a user