diff --git a/docs/ansible.md b/docs/ansible.md index a532897953a..55aa26248e1 100644 --- a/docs/ansible.md +++ b/docs/ansible.md @@ -92,9 +92,11 @@ Finally, you execute `ansible-playbook ...` commands as per normal now. If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`). To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it ...` command), run: + ```sh apk add sshpass ``` + Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command. #### Resolve directory ownership issues diff --git a/docs/configuring-captcha.md b/docs/configuring-captcha.md index ad411dddeb2..a4a16a1dc5c 100644 --- a/docs/configuring-captcha.md +++ b/docs/configuring-captcha.md @@ -1,6 +1,7 @@ (Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md)) # Overview + Captcha can be enabled for this home server. This file explains how to do that. The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead. diff --git a/docs/configuring-playbook-bridge-beeper-linkedin.md b/docs/configuring-playbook-bridge-beeper-linkedin.md index 02b4d5fed56..5c876b86211 100644 --- a/docs/configuring-playbook-bridge-beeper-linkedin.md +++ b/docs/configuring-playbook-bridge-beeper-linkedin.md @@ -15,6 +15,7 @@ matrix_beeper_linkedin_enabled: true There are some additional things you may wish to configure about the bridge before you continue. Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file: + ```yaml matrix_beeper_linkedin_configuration_extension_yaml: | bridge: @@ -24,6 +25,7 @@ matrix_beeper_linkedin_configuration_extension_yaml: | ``` If you would like to be able to administrate the bridge from your account it can be configured like this: + ```yaml matrix_beeper_linkedin_configuration_extension_yaml: | bridge: diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md index 019ffa28336..f8a83df1d1a 100644 --- a/docs/configuring-playbook-bridge-hookshot.md +++ b/docs/configuring-playbook-bridge-hookshot.md @@ -70,6 +70,7 @@ The GitHub bridge requires you to install a private key file. This can be done i - use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server. To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration: + ```yaml aux_file_definitions: - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}" @@ -78,6 +79,7 @@ aux_file_definitions: owner: "{{ matrix_user_username }}" group: "{{ matrix_user_groupname }}" ``` + For more information, see the documentation in the [default configuration of the aux role](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml). ### Provisioning API diff --git a/docs/configuring-playbook-bridge-mautrix-facebook.md b/docs/configuring-playbook-bridge-mautrix-facebook.md index 848c1c64ae3..e485f3dbdfe 100644 --- a/docs/configuring-playbook-bridge-mautrix-facebook.md +++ b/docs/configuring-playbook-bridge-mautrix-facebook.md @@ -23,6 +23,7 @@ matrix_mautrix_facebook_enabled: true There are some additional things you may wish to configure about the bridge before you continue. Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file: + ```yaml matrix_mautrix_facebook_configuration_extension_yaml: | bridge: @@ -32,6 +33,7 @@ matrix_mautrix_facebook_configuration_extension_yaml: | ``` If you would like to be able to administrate the bridge from your account it can be configured like this: + ```yaml matrix_mautrix_facebook_configuration_extension_yaml: | bridge: diff --git a/docs/configuring-playbook-bridge-mautrix-instagram.md b/docs/configuring-playbook-bridge-mautrix-instagram.md index d57b9346f6c..76022f907a5 100644 --- a/docs/configuring-playbook-bridge-mautrix-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-instagram.md @@ -17,6 +17,7 @@ matrix_mautrix_instagram_enabled: true There are some additional things you may wish to configure about the bridge before you continue. Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file: + ```yaml matrix_mautrix_instagram_configuration_extension_yaml: | bridge: @@ -26,6 +27,7 @@ matrix_mautrix_instagram_configuration_extension_yaml: | ``` If you would like to be able to administrate the bridge from your account it can be configured like this: + ```yaml # The easy way. The specified Matrix user ID will be made an admin of all bridges matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}" diff --git a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md index 1c1f1e79341..4305a45e8ae 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md @@ -48,6 +48,7 @@ Different levels of permission can be granted to users: The permissions are following the sequence: nothing < `relay` < `user` < `admin`. The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this: + ```yaml matrix_mautrix_meta_instagram_bridge_permissions_default: '*': relay diff --git a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md index bf21c3008e8..ef3c8f35c6a 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md @@ -61,6 +61,7 @@ Different levels of permission can be granted to users: The permissions are following the sequence: nothing < `relay` < `user` < `admin`. The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this: + ```yaml matrix_mautrix_meta_messenger_bridge_permissions_default: '*': relay diff --git a/docs/configuring-playbook-bridge-mautrix-signal.md b/docs/configuring-playbook-bridge-mautrix-signal.md index dea39e730a4..7c12efb5bfc 100644 --- a/docs/configuring-playbook-bridge-mautrix-signal.md +++ b/docs/configuring-playbook-bridge-mautrix-signal.md @@ -41,6 +41,7 @@ Different levels of permission can be granted to users: The permissions are following the sequence: nothing < relay < user < admin. The default permissions are set as follows: + ```yaml permissions: '*': relay @@ -48,6 +49,7 @@ permissions: ``` If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file: + ```yaml matrix_mautrix_signal_configuration_extension_yaml: | bridge: @@ -58,6 +60,7 @@ matrix_mautrix_signal_configuration_extension_yaml: | This will add the admin permission to the specific user, while keeping the default permissions. In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file: + ```yaml matrix_mautrix_signal_bridge_permissions: '@ADMIN:example.com': admin diff --git a/docs/configuring-playbook-bridge-mautrix-telegram.md b/docs/configuring-playbook-bridge-mautrix-telegram.md index b97fcbe770a..e32f5d1819a 100644 --- a/docs/configuring-playbook-bridge-mautrix-telegram.md +++ b/docs/configuring-playbook-bridge-mautrix-telegram.md @@ -52,6 +52,7 @@ matrix_mautrix_telegram_configuration_extension_yaml: | ``` You might also want to give permissions to administrate the bot: + ```yaml matrix_mautrix_telegram_configuration_extension_yaml: | bridge: @@ -62,6 +63,7 @@ matrix_mautrix_telegram_configuration_extension_yaml: | More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410 If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration: + ```yaml matrix_mautrix_telegram_filter_mode: whitelist ``` diff --git a/docs/configuring-playbook-email.md b/docs/configuring-playbook-email.md index 51615e752b4..b10dd82243f 100644 --- a/docs/configuring-playbook-email.md +++ b/docs/configuring-playbook-email.md @@ -31,6 +31,7 @@ exim_relay_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 SMTP 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 `exim_relay_sender_address`. The only other thing you need to change is the `exim_relay_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`. diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index 50cb2594e62..547c108c0fa 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -169,6 +169,7 @@ By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-vid There is an ansible playbook that can be run with the following tag: `ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start` For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example: + ```INI [jitsi_jvb_servers] ansible_host= diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index 161965d9534..96981ade8c8 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/docs/configuring-playbook-matrix-media-repo.md @@ -30,6 +30,7 @@ By default, the media-repo will use the local filesystem for data storage. You c ## Configuring the media-repo Additional common configuration options: + ```yaml # The postgres database pooling options diff --git a/docs/configuring-playbook-prometheus-grafana.md b/docs/configuring-playbook-prometheus-grafana.md index f4786f807d2..ccc329c5be7 100644 --- a/docs/configuring-playbook-prometheus-grafana.md +++ b/docs/configuring-playbook-prometheus-grafana.md @@ -120,6 +120,7 @@ Name | Description If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.example.com/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`. The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`. It will look a bit like this: + ```yaml scrape_configs: - job_name: 'synapse' diff --git a/docs/configuring-playbook-user-verification-service.md b/docs/configuring-playbook-user-verification-service.md index 12ece9f02c5..d1ffde99d59 100644 --- a/docs/configuring-playbook-user-verification-service.md +++ b/docs/configuring-playbook-user-verification-service.md @@ -68,6 +68,7 @@ matrix_user_verification_service_uvs_auth_token: "TOKEN" In case Jitsi is also managed by this playbook and 'matrix' authentication in Jitsi is enabled, this collection will automatically configure Jitsi to use the configured auth token. ### (Optional) Disable Auth + Authorization is enabled by default. To disable set ```yaml @@ -108,6 +109,7 @@ The configuration variable `UVS_LOG_LEVEL` can be set to: - debug ## TLS Certificate Checking + If the Matrix Homeserver does not provide a valid TLS certificate, UVS will fail with the following error message: > message: 'No response received: [object Object]', diff --git a/docs/importing-postgres.md b/docs/importing-postgres.md index 06ea65ea626..d7871a78a14 100644 --- a/docs/importing-postgres.md +++ b/docs/importing-postgres.md @@ -32,6 +32,7 @@ just run-tags import-postgres \ ## Troubleshooting ### Table Ownership + A table ownership issue can occur if you are importing from a Synapse installation which was both: - migrated from SQLite to Postgres, and @@ -84,6 +85,7 @@ In this case you can use the command suggested in the import task to clear the d Now on your local machine run `just run-tags setup-postgres` to prepare the database roles etc. If not, you probably get this error. `synapse` is the correct table owner, but the role is missing in database. + ``` "ERROR: role synapse does not exist" ``` diff --git a/docs/maintenance-and-troubleshooting.md b/docs/maintenance-and-troubleshooting.md index 2847e6b1f55..673c8985992 100644 --- a/docs/maintenance-and-troubleshooting.md +++ b/docs/maintenance-and-troubleshooting.md @@ -3,6 +3,7 @@ ## How to see the current status of your services You can check the status of your services by using `systemctl status`. Example: + ```sh sudo systemctl status matrix-synapse diff --git a/docs/maintenance-postgres.md b/docs/maintenance-postgres.md index d652bac0b85..c2b0b302020 100644 --- a/docs/maintenance-postgres.md +++ b/docs/maintenance-postgres.md @@ -88,8 +88,7 @@ The auto-upgrade-backup directory stays around forever, until you **manually dec As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty Postgres server is started, and then the dump is restored into the new server. To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"` -To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage. -If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`. Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"` +To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage. If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`. Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"` **All databases, roles, etc. on the Postgres server are migrated**. diff --git a/docs/updating-users-passwords.md b/docs/updating-users-passwords.md index 9f5e0463afd..3dcc71e19b6 100644 --- a/docs/updating-users-passwords.md +++ b/docs/updating-users-passwords.md @@ -39,7 +39,9 @@ This requires an [access token](obtaining-access-tokens.md) from a server admin If you didn't make your account a server admin when you created it, you can learn how to switch it now by reading about it in [Adding/Removing Administrator privileges to an existing user in Synapse](registering-users.md#addingremoving-administrator-privileges-to-an-existing-user-in-synapse). ### Example: + To set @user:example.com's password to `correct_horse_battery_staple` you could use this curl command: + ```sh curl -XPOST -d '{ "new_password": "correct_horse_battery_staple" }' "https://matrix.example.com/_matrix/client/r0/admin/reset_password/@user:example.com?access_token=MDA...this_is_my_access_token ```