mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-10-16 17:29:42 +02:00
Add support for Element Admin
This commit is contained in:
Slavi Pantaleev
71
docs/configuring-playbook-element-admin.md
Normal file
71
docs/configuring-playbook-element-admin.md
Normal file
@@ -0,0 +1,71 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2024 wjbeckett
|
||||
SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Setting up Element Admin (optional)
|
||||
|
||||
The playbook can install and configure [Element Admin](https://github.com/element-hq/element-admin) for you.
|
||||
|
||||
Element Admin is a web-based administration panel for Synapse and [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md).
|
||||
|
||||
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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A [Synapse](configuring-playbook-synapse.md) homeserver with its Admin API enabled (the playbook automatically enables it for you when you enable Element Admin)
|
||||
- [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) with its Admin API enabled (the playbook automatically enables it for you when you enable Element Admin)
|
||||
|
||||
## Decide on a domain and path
|
||||
|
||||
By default, the Element Admin is configured to be served on the `admin.element.example.com` domain.
|
||||
|
||||
If you'd like to run Element Admin on another hostname, see the [Adjusting the Element Admin URL](#adjusting-the-element-admin-url-optional) section below.
|
||||
|
||||
## Adjusting DNS records (optional)
|
||||
|
||||
By default, this playbook installs Element Admin on the `admin.element.` subdomain (`admin.element.example.com`) and requires you to create a `CNAME` record for `admin.element`, which targets `matrix.example.com`.
|
||||
|
||||
When setting these values, replace `example.com` with your own.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_element_admin_enabled: true
|
||||
```
|
||||
|
||||
### Adjusting the Element Admin URL (optional)
|
||||
|
||||
By tweaking the `matrix_element_admin_hostname` variable, you can easily make the service available at a **different hostname** than the default one.
|
||||
|
||||
Example additional configuration for your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_element_admin_hostname: element-admin.example.com
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> A `matrix_element_admin_path_prefix` variable is also available and mean to let you configure a path prefix for the Element Admin service, but **Element Admin does not support running under a sub-path yet**.
|
||||
|
||||
## 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
|
||||
|
||||
Once installed, Element Call integrates seamlessly with Matrix clients like [Element Web](configuring-playbook-client-element-web.md) and Element X on mobile (iOS and Android).
|
||||
@@ -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 [login with access token](https://github.com/etkecc/synapse-admin/pull/58), 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.
|
||||
- ❌ Certain **tools like [synapse-admin](./configuring-playbook-synapse-admin.md) do not have full compatibility with MAS yet**. synapse-admin already supports [login with access token](https://github.com/etkecc/synapse-admin/pull/58), 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.
|
||||
|
||||
- ❌ **Some services experience issues when authenticating via MAS**:
|
||||
|
||||
|
||||
@@ -18,6 +18,8 @@ synapse-admin is a web UI tool you can use to **administrate users, rooms, media
|
||||
|
||||
💡 **Note**: 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.
|
||||
|
||||
💡 **Note**: The playbook also supports an alternative management UI in the shape of [Element Admin](./configuring-playbook-element-admin.md). However, it's currently less feature-rich than Synapse Admin and has a dependency on [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.
|
||||
@@ -40,7 +42,7 @@ matrix_synapse_admin_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.
|
||||
|
||||
> [!WARNING]
|
||||
> If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all.
|
||||
> If you're using [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS) for authentication, you will be able to [log into synapse-admin with an access token](https://github.com/etkecc/synapse-admin/pull/58), but certain synapse-admin features (especially those around user management) will be limited or not work at all. You may be interested in using [Element Admin](docs/configuring-playbook-element-admin.md) for these purposes.
|
||||
|
||||
### Adjusting the Synapse Admin URL (optional)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user