Merge branch 'master' into master

docs/configuring-playbook-bridge-mautrix-hangouts.md

@@ -0,0 +1,24 @@
+# Setting up Mautrix Hangouts (optional)
+
+The playbook can install and configure [mautrix-hangouts](https://github.com/tulir/mautrix-hangouts) for you.
+
+See the project's [documentation](https://github.com/tulir/mautrix-hangouts/wiki#usage) to learn what it does and why it might be useful to you.
+
+To enable the [Google Hangouts](https://hangouts.google.com/) bridge just use the following playbook configuration:
+
+
+```yaml
+matrix_mautrix_hangouts_enabled: true
+```
+
+## Usage
+
+Once the bot is enabled you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
+
+Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions.
+
+Automatic login may not work. If it does not, reload the page and select the "Manual login" checkbox before starting. Manual login involves logging into your Google account normally and then manually getting the OAuth token from browser cookies with developer tools.
+
+Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages.
+
+You can learn more about authentication from the bridge's [official documentation on Authentication](https://github.com/tulir/mautrix-hangouts/wiki/Authentication).

docs/configuring-playbook-dimension.md

@@ -29,7 +29,7 @@ You are required to specify an access token for Dimension to work.
 To get an access token, follow these steps:
 
 1. In a private browsing session (incognito window), open Riot.
-2. It's better to you use dedicated user for getting access token, so log in with this user's username and password.
+2. It's preferable to use a dedicated user for the access token, so create and log in with that user's username and password.
 3. Set the display name and avatar, if required.
 4. In the settings page choose "Help & About", scroll down to the bottom and click `Access Token: <click to reveal>`.
 5. Copy the highlighted text to your configuration.

docs/configuring-playbook-email.md

@@ -7,6 +7,8 @@ This may or may not work, depending on your domain configuration (SPF settings,
 
 By default, emails are sent from `matrix@<your-domain-name>` (as specified by the `matrix_mailer_sender_address` playbook variable).
 
+**Note**: If you are using a Google Cloud instance, [port 25 is always blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/), so you need to relay email through another SMTP server as described below.   
+
 
 ## Firewall settings
 
@@ -31,6 +33,23 @@ matrix_mailer_relay_auth_password: "some-password"
 **Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
 
 
+### Configuations for sending emails using Sendgrid
+An easy and free STMP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `matrix_mailer_sender_address`.
+
+The only other thing you need to change is the `matrix_mailer_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
+
+Note that the `matrix_mailer_relay_auth_username` is literally the string `apikey`, it's always the same for Sendgrid.
+
+```yaml
+matrix_mailer_sender_address: "arbitrary@email.com"
+matrix_mailer_relay_use: true
+matrix_mailer_relay_host_name: "smtp.sendgrid.net"
+matrix_mailer_relay_host_port: 587
+matrix_mailer_relay_auth: true
+matrix_mailer_relay_auth_username: "apikey"
+matrix_mailer_relay_auth_password: "<your api key password>" 
+```
+
 ## Troubleshooting
 
 If you're having trouble with email not being delivered, it may be useful to inspect the mailer logs: `journalctl -f -u matrix-mailer`.

docs/configuring-playbook-email2matrix.md

@@ -0,0 +1,80 @@
+# Setting up Email2Matrix (optional)
+
+The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you.
+
+See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
+
+
+## Preparation
+
+### Port availability
+
+Ensure that port 25 is available on your Matrix server and open in your firewall.
+If you have `postfix` or some other email server software installed, you may need to manually remove it first (unless you need it, of course).
+
+If you really need to run an email server on the Matrix machine for other purposes, it may be possible to run Email2Matrix on another port (with a configuration like `matrix_email2matrix_smtp_host_bind_port: "127.0.0.01:2525"`) and have your other email server relay messages there.
+For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/), see [here](https://github.com/devture/email2matrix/blob/master/docs/setup_with_postfix.md).
+
+### Creating a user
+
+Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side.
+Refer to [Registering users](registering-users.md) for ways to do that. A regular (non-admin) user works best.
+
+### Creating a shared room
+
+After creating a sender user, you should create one or more Matrix rooms that you share with that user.
+It doesn't matter who creates and owns the rooms and who joins later (you or the sender user).
+
+What matters is that both you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there.
+Inviting additional people to the room is okay too.
+
+Take note of each room's room id (different clients show the room id in a different place).
+You'll need the room id when doing [Configuration](#configuration) below.
+
+
+### Obtaining an access token for the sender user
+
+In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it.
+
+To do this, you can execute a command like this:
+
+```
+curl \
+--data '{"identifier": {"type": "m.id.user", "user": "email2matrix" }, "password": "MATRIX_PASSWORD_FOR_THE_USER", "type": "m.login.password", "device_id": "Email2Matrix", "initial_device_display_name": "Email2Matrix"}' \
+https://matrix.DOMAIN/_matrix/client/r0/login
+```
+
+Take note of the `access_token` value. You'll need the access token when doing [Configuration](#configuration) below.
+
+
+## Configuration
+
+After doing the preparation steps above, adjust your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration like this:
+
+```yaml
+matrix_email2matrix_enabled: true
+
+matrix_email2matrix_matrix_mappings:
+  - MailboxName: "my-mailbox"
+    MatrixRoomId: "!someRoom:DOMAIN"
+    MatrixHomeserverUrl: "https://matrix.DOMAIN"
+    MatrixUserId: "@email2matrix:DOMAIN"
+    MatrixAccessToken: "ACCESS_TOKEN_GOES_HERE"
+    IgnoreSubject: false
+    IgnoreBody: false
+    SkipMarkdown: false
+
+  - MailboxName: "my-mailbox2"
+    MatrixRoomId: "!anotherRoom:DOMAIN"
+    MatrixHomeserverUrl: "https://matrix.DOMAIN"
+    MatrixUserId: "@email2matrix:DOMAIN"
+    MatrixAccessToken: "ACCESS_TOKEN_GOES_HERE"
+    IgnoreSubject: true
+    IgnoreBody: false
+    SkipMarkdown: true
+```
+
+You can also set `MatrixHomeserverUrl` to `http://matrix-synapse:8008`, instead of the public `https://matrix.DOMAIN`.
+However, that's more likely to break in the future if you switch to another server implementation than Synapse.
+
+Re-run the playbook (`--tags=setup-email2matrix,start`) and try sending an email to `my-mailbox@matrix.DOMAIN`.

docs/configuring-playbook-ngnix.md

@@ -0,0 +1,25 @@
+# Configure Ngnix (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.
+
+
+## Using Ngnix status
+
+This will serve a statuspage to the hosting machine only. Useful for monitoring software like [longview](https://www.linode.com/docs/platform/longview/longview-app-for-nginx/)
+
+```yaml
+matrix_nginx_proxy_proxy_matrix_nginx_status_enabled: true
+```
+
+This will serve the status page under the following addresses:
+- `http://matrix.DOMAIN/nginx_status` (using HTTP)
+- `https://matrix.DOMAIN/nginx_status` (using HTTPS)
+
+By default, if ```matrix_nginx_proxy_nginx_status_enabled``` is enabled, access to the status page would be allowed from the local IP address of the server. If you wish to allow access from other IP addresses, you can provide them as a list:
+
+```yaml
+matrix_nginx_proxy_proxy_matrix_nginx_status_allowed_addresses:
+- 8.8.8.8
+- 1.1.1.1
+```

docs/configuring-playbook.md

@@ -44,6 +44,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Serving your base domain using this playbook's nginx server](configuring-playbook-base-domain-serving.md) (optional)
 
+- [Configure Ngnix (optional, advanced)](configuring-playbook-ngnix.md) (optional, advanced)
+
 - [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced)
 
 - [Adjusting TURN server configuration](configuring-playbook-turn.md) (optional, advanced)
@@ -77,8 +79,12 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md) (optional)
 
+- [Setting up Mautrix Hangouts bridging](configuring-playbook-bridge-mautrix-hangouts.md) (optional)
+
 - [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional)
 
 - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional)
 
 - [Setting up Appservice Slack bridging](configuring-playbook-bridge-appservice-slack.md) (optional)
+
+- [Setting up Email2Matrix](configuring-playbook-email2matrix.md) (optional)

docs/maintenance-and-troubleshooting.md

@@ -16,6 +16,24 @@ You can see the logs by using journalctl. Example:
 sudo journalctl -fu matrix-synapse
 ```
 
+
+## Increasing Synapse logging
+
+Because the [Synapse](https://github.com/matrix-org/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`.
+
+If you'd like to debug an issue or [report a Synapse bug](https://github.com/matrix-org/synapse/issues/new/choose) to the developers, it'd be better if you temporarily increasing the logging level to `INFO`.
+
+Example configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
+
+```yaml
+matrix_synapse_log_level: "INFO"
+matrix_synapse_storage_sql_log_level: "INFO"
+matrix_synapse_root_log_level: "INFO"
+```
+
+Re-run the playbook after making these configuration changes.
+
+
 ## Postgres
 
 See the dedicated [PostgreSQL Maintenance](maintenance-postgres.md) documentation page.