From 733b80683337f5628089cf996fbabe7fcaa4f939 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Mon, 26 Nov 2018 07:23:42 +0200 Subject: [PATCH] Annotate certain features as optional/advanced We've had some people get confused into installing Matrix Corporal and having pain with that. With this documentation change, we try to make it clearer that it's an advanced feature not to be touched unless you know what you're doing. On a similar note, we also make sure other things are properly labeled as "(optional)" and/or "(advanced)". --- docs/configuring-playbook-bridge-mautrix-telegram.md | 5 +++-- docs/configuring-playbook-bridge-mautrix-whatsapp.md | 5 +++-- docs/configuring-playbook-federation.md | 2 +- docs/configuring-playbook-matrix-corporal.md | 9 ++++++++- docs/configuring-playbook-own-webserver.md | 4 ++-- docs/configuring-playbook-rest-auth.md | 2 +- docs/configuring-playbook-shared-secret-auth.md | 2 +- docs/configuring-playbook-telemetry.md | 2 +- docs/configuring-playbook.md | 8 ++++---- 9 files changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/configuring-playbook-bridge-mautrix-telegram.md b/docs/configuring-playbook-bridge-mautrix-telegram.md index 0886c60d8..c814cfdd3 100644 --- a/docs/configuring-playbook-bridge-mautrix-telegram.md +++ b/docs/configuring-playbook-bridge-mautrix-telegram.md @@ -1,11 +1,12 @@ -# Setting up Mautrix Telegram +# Setting up Mautrix Telegram (optional) The playbook can install and configure [mautrix-telegram](https://github.com/tulir/mautrix-telegram) for you. See the project's [documentation](https://github.com/tulir/mautrix-telegram/wiki#usage) to learn what it does and why it might be useful to you. You'll need to obtain API keys from `https://my.telegram.org/apps` and then use the following playbook configuration: -``` + +```yaml matrix_mautrix_telegram_enabled: true matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH diff --git a/docs/configuring-playbook-bridge-mautrix-whatsapp.md b/docs/configuring-playbook-bridge-mautrix-whatsapp.md index 0d70043a9..241d9d9c0 100644 --- a/docs/configuring-playbook-bridge-mautrix-whatsapp.md +++ b/docs/configuring-playbook-bridge-mautrix-whatsapp.md @@ -1,11 +1,12 @@ -# Setting up Mautrix Whatsapp +# Setting up Mautrix Whatsapp (optional) The playbook can install and configure [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) for you. See the project's [documentation](https://github.com/tulir/mautrix-whatsapp/wiki) to learn what it does and why it might be useful to you. Use the following playbook configuration: -``` + +```yaml matrix_mautrix_whatsapp_enabled: true ``` diff --git a/docs/configuring-playbook-federation.md b/docs/configuring-playbook-federation.md index 02e69600f..1906f37d0 100644 --- a/docs/configuring-playbook-federation.md +++ b/docs/configuring-playbook-federation.md @@ -1,4 +1,4 @@ -# Controlling Matrix federation +# Controlling Matrix federation (optional) By default, your server federates with the whole Matrix network. That is, people on your server can communicate with people on any other Matrix server. diff --git a/docs/configuring-playbook-matrix-corporal.md b/docs/configuring-playbook-matrix-corporal.md index 8e78ee933..4afb00654 100644 --- a/docs/configuring-playbook-matrix-corporal.md +++ b/docs/configuring-playbook-matrix-corporal.md @@ -1,7 +1,14 @@ -# Setting up Matrix Corporal +# Setting up Matrix Corporal (optional, advanced) + +------------------------------------- + +**WARNING**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't. + +------------------------------------- The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you. +In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment. See that project's documentation to learn what it does and why it might be useful to you. If you decide that you'd like to let this playbook install it for you, you'd need to also [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md). diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md index 18d32b950..5bafe142b 100644 --- a/docs/configuring-playbook-own-webserver.md +++ b/docs/configuring-playbook-own-webserver.md @@ -1,4 +1,4 @@ -# Using your own webserver, instead of this playbook's nginx proxy (optional) +# Using your own webserver, instead of this playbook's nginx proxy (optional, advanced) By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443. If that's alright, you can skip this. @@ -12,7 +12,7 @@ All it takes is: 2) editing your configuration file (`inventory/matrix./vars.yml`): -``` +```yaml matrix_nginx_proxy_enabled: false ``` diff --git a/docs/configuring-playbook-rest-auth.md b/docs/configuring-playbook-rest-auth.md index e320ca491..c2363ff4b 100644 --- a/docs/configuring-playbook-rest-auth.md +++ b/docs/configuring-playbook-rest-auth.md @@ -1,4 +1,4 @@ -# Setting up the REST authentication password provider module +# Setting up the REST authentication password provider module (optional, advanced) The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/kamax-io/matrix-synapse-rest-auth) for you. diff --git a/docs/configuring-playbook-shared-secret-auth.md b/docs/configuring-playbook-shared-secret-auth.md index df5eddd87..26675f4c8 100644 --- a/docs/configuring-playbook-shared-secret-auth.md +++ b/docs/configuring-playbook-shared-secret-auth.md @@ -1,4 +1,4 @@ -# Setting up the Shared Secret Auth password provider module +# Setting up the Shared Secret Auth password provider module (optional, advanced) The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you. diff --git a/docs/configuring-playbook-telemetry.md b/docs/configuring-playbook-telemetry.md index 1b794d9c4..bc954f67a 100644 --- a/docs/configuring-playbook-telemetry.md +++ b/docs/configuring-playbook-telemetry.md @@ -1,4 +1,4 @@ -# Enabling Telemetry for your Matrix server +# Enabling Telemetry for your Matrix server (optional) By default, this playbook configures your Matrix homeserver to not send any telemetry data anywhere. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 54aef726c..6659f6626 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -35,13 +35,13 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Adjusting mxisd Identity Server configuration](configuring-playbook-mxisd.md) (optional) -- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional) +- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced) -- [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional) +- [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional, advanced) -- [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional) +- [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional, advanced) -- [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional) +- [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced) - [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional)