Update docs for Element Web and SchildiChat Web (#3925)

* Update docs for Element Web and SchildiChat Web: add the common section "Extending the configuration" Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for Element Web and SchildiChat Web: remove redundant descriptions Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for Element Web and SchildiChat Web: reorganization Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for Element Web and SchildiChat Web: edit descriptions about themes Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for Element Web and SchildiChat Web: add examples of extending the configuration This follows docs/configuring-playbook-appservice-draupnir-for-all.md, etc. Note the examples are available on the main.yml files. Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-client-element-web.md: add an instruction about the section on disabling Element Web Signed-off-by: Suguru Hirahara <[email protected]> --------- Signed-off-by: Suguru Hirahara <[email protected]> Co-authored-by: Suguru Hirahara <[email protected]>
spantaleev · Jan 10, 2025 · 9c61742 · 9c61742
1 parent 638f53a
commit 9c61742
Show file tree

Hide file tree

Showing 2 changed files with 98 additions and 32 deletions.
diff --git a/docs/configuring-playbook-client-element-web.md b/docs/configuring-playbook-client-element-web.md
@@ -2,44 +2,43 @@
 
 By default, this playbook installs the [Element Web](https://github.com/element-hq/element-web) Matrix client for you. If that's okay, you can skip this document.
 
+If you'd like to stop the playbook installing the client, see the section [below](#disabling-element-web) to check the configuration for disabling it.
+
 💡 **Note**: the latest version of Element Web is also available on the web, hosted by 3rd parties. If you trust giving your credentials to the following 3rd party Single Page Applications, you can consider using it from there and avoiding the (small) overhead of self-hosting (by [disabling Element Web](#disabling-element-web)):
 
 - [app.element.io](https://app.element.io/), hosted by [Element](https://element.io/)
 - [app.etke.cc](https://app.etke.cc/), hosted by [etke.cc](https://etke.cc/)
 
-## Disabling Element Web
-
-If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
-
-```yaml
-matrix_client_element_enabled: false
-```
-
 ## Adjusting the playbook configuration
 
-The playbook provides some customization variables you could use to change Element Web's settings.
+### Themes
 
-Their defaults are defined in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml) and they ultimately end up in the generated `/matrix/element/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-element/templates/config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2) template.
+You can change the look of Element Web by pulling themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project or defining your own themes manually.
 
-**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
+#### Use themes by `element-themes`
 
-Alternatively, **if there is no pre-defined variable** for an Element Web setting you wish to change:
+To pull the themes from the `element-themes` project and use them for your Element Web instance, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of Element Web's various settings that rarely get used.
+```yaml
+matrix_client_element_themes_enabled: true
+```
 
-- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-element/templates/config.json.j2)) by making use of the `matrix_client_element_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
+If the variable is set to `true`, all themes found in the repository specified with `matrix_client_element_themes_repository_url` will be installed and enabled automatically.
 
-- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
+Note that for a custom theme to work well, all Element Web instances that you use must have the same theme installed.
 
-### Themes
+#### Define themes manually
 
-To change the look of Element Web, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
+You can also define your own themes manually by adding and adjusting the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_element_themes_enabled: true`).
+```yaml
+# Controls the `setting_defaults.custom_themes` setting of the Element Web configuration.
+matrix_client_element_setting_defaults_custom_themes: []
+```
 
-If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
+If you define your own themes with it and set `matrix_client_element_themes_enabled` to `true` for the themes by `element-themes`, your themes will be preserved as well.
 
-Note that for a custom theme to work well, all Element Web instances that you use must have the same theme installed.
+If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
 
 ### Adjusting the Element Web URL
 
@@ -58,6 +57,33 @@ matrix_client_element_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_client_element_path_prefix: /element
 ```
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-element/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-element/templates/config.json.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_element_configuration_extension_json` variable
+
+For example, to override some Element Web settings, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+ # Your custom JSON configuration for Element Web should go to `matrix_client_element_configuration_extension_json`.
+ # This configuration extends the default starting configuration (`matrix_client_element_configuration_default`).
+ #
+ # You can override individual variables from the default configuration, or introduce new ones.
+ #
+ # If you need something more special, you can take full control by
+ # completely redefining `matrix_client_element_configuration_default`.
+ #
+matrix_client_element_configuration_extension_json: |
+ {
+ "disable_3pid_login": true,
+ "disable_login_language_selector": true
+ }
+```
+
 ## Adjusting DNS records
 
 Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Element Web domain to the Matrix server.
@@ -66,6 +92,14 @@ By default, you will need to create a CNAME record for `element`. See [Configuri
 
 If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
+## Disabling Element Web
+
+If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_client_element_enabled: false
+```
+
 ## 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:

diff --git a/docs/configuring-playbook-client-schildichat-web.md b/docs/configuring-playbook-client-schildichat-web.md
@@ -16,29 +16,34 @@ To enable SchildiChat Web, add the following configuration to your `inventory/ho
 matrix_client_schildichat_enabled: true
 ```
 
-The playbook provides some customization variables you could use to change SchildiChat Web's settings.
+### Themes
 
-Their defaults are defined in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml) and they ultimately end up in the generated `/matrix/schildichat/config.json` file (on the server). This file is generated from the [`roles/custom/matrix-client-schildichat/templates/config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2) template.
+You can change the look of SchildiChat Web by pulling themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project or defining your own themes manually.
 
-**If there's an existing variable** which controls a setting you wish to change, you can simply define that variable in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) and [re-run the playbook](installing.md) to apply the changes.
+#### Use themes by `element-themes`
 
-Alternatively, **if there is no pre-defined variable** for a SchildiChat Web setting you wish to change:
+To pull the themes from the `element-themes` project and use them for your SchildiChat Web instance, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-- you can either **request a variable to be created** (or you can submit such a contribution yourself). Keep in mind that it's **probably not a good idea** to create variables for each one of SchildiChat Web's various settings that rarely get used.
+```yaml
+matrix_client_schildichat_themes_enabled: true
+```
 
-- or, you can **extend and override the default configuration** ([`config.json.j2`](../roles/custom/matrix-client-schildichat/templates/config.json.j2)) by making use of the `matrix_client_schildichat_configuration_extension_json_` variable. You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
+If the variable is set to `true`, all themes found in the repository specified with `matrix_client_schildichat_themes_repository_url` will be installed and enabled automatically.
 
-- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_schildichat_configuration_default` (or `matrix_client_schildichat_configuration`). You can find information about this in [`roles/custom/matrix-client-schildichat/defaults/main.yml`](../roles/custom/matrix-client-schildichat/defaults/main.yml).
+Note that for a custom theme to work well, all SchildiChat Web instances that you use must have the same theme installed.
 
-### Themes
+#### Define themes manually
 
-To change the look of SchildiChat Web, you can define your own themes manually by using the `matrix_client_schildichat_setting_defaults_custom_themes` setting.
+You can also define your own themes manually by adding and adjusting the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
 
-Or better yet, you can automatically pull it all themes provided by the [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes) project by simply flipping a flag (`matrix_client_schildichat_themes_enabled: true`).
+```yaml
+# Controls the `setting_defaults.custom_themes` setting of the SchildiChat Web configuration.
+matrix_client_schildichat_setting_defaults_custom_themes: []
+```
 
-If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
+If you define your own themes with it and set `matrix_client_schildichat_themes_enabled` to `true` for the themes by `element-themes`, your themes will be preserved as well.
 
-Note that for a custom theme to work well, all SchildiChat Web instances that you use must have the same theme installed.
+If you make your own theme, we encourage you to submit it to the **aaronraimist/element-themes** project, so that the whole community could easily enjoy it.
 
 ### Adjusting the SchildiChat Web URL
 
@@ -57,6 +62,33 @@ matrix_client_schildichat_hostname: "{{ matrix_server_fqn_matrix }}"
 matrix_client_schildichat_path_prefix: /schildichat
 ```
 
+### Extending the configuration
+
+There are some additional things you may wish to configure about the component.
+
+Take a look at:
+
+- `roles/custom/matrix-client-schildichat/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+- `roles/custom/matrix-client-schildichat/templates/config.json.j2` for the component's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_client_schildichat_configuration_extension_json` variable
+
+For example, to override some SchildiChat Web settings, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+ # Your custom JSON configuration for SchildiChat Web should go to `matrix_client_schildichat_configuration_extension_json`.
+ # This configuration extends the default starting configuration (`matrix_client_schildichat_configuration_default`).
+ #
+ # You can override individual variables from the default configuration, or introduce new ones.
+ #
+ # If you need something more special, you can take full control by
+ # completely redefining `matrix_client_schildichat_configuration_default`.
+ #
+matrix_client_schildichat_configuration_extension_json: |
+ {
+ "disable_3pid_login": true,
+ "disable_login_language_selector": true
+ }
+```
+
 ## Adjusting DNS records
 
 Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the SchildiChat Web domain to the Matrix server.