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)".
This commit is contained in:
Slavi Pantaleev 2018-11-26 07:23:42 +02:00
parent 529b5b222d
commit 733b806833
9 changed files with 24 additions and 15 deletions

View file

@ -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. 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. 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: 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_enabled: true
matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH

View file

@ -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. 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. 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: Use the following playbook configuration:
```
```yaml
matrix_mautrix_whatsapp_enabled: true matrix_mautrix_whatsapp_enabled: true
``` ```

View file

@ -1,4 +1,4 @@
# Controlling Matrix federation # Controlling Matrix federation (optional)
By default, your server federates with the whole Matrix network. 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. That is, people on your server can communicate with people on any other Matrix server.

View file

@ -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. 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. 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). 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).

View file

@ -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. 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. If that's alright, you can skip this.
@ -12,7 +12,7 @@ All it takes is:
2) editing your configuration file (`inventory/matrix.<your-domain>/vars.yml`): 2) editing your configuration file (`inventory/matrix.<your-domain>/vars.yml`):
``` ```yaml
matrix_nginx_proxy_enabled: false matrix_nginx_proxy_enabled: false
``` ```

View file

@ -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. The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/kamax-io/matrix-synapse-rest-auth) for you.

View file

@ -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. The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you.

View file

@ -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. By default, this playbook configures your Matrix homeserver to not send any telemetry data anywhere.

View file

@ -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) - [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) - [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional)