1
0
Fork 0
mirror of https://github.com/YunoHost-Apps/synapse_ynh.git synced 2024-09-03 20:26:38 +02:00
synapse_ynh/README.md

162 lines
7.2 KiB
Markdown
Raw Normal View History

2022-05-21 21:55:12 +02:00
<!--
2024-03-06 21:53:34 +01:00
N.B.: This README was automatically generated by https://github.com/YunoHost/apps/tree/master/tools/readme_generator
2022-05-21 21:55:12 +02:00
It shall NOT be edited by hand.
-->
2017-02-13 20:43:41 +01:00
2022-05-21 21:55:12 +02:00
# Synapse for YunoHost
2018-02-12 21:11:15 +01:00
2024-03-06 21:53:34 +01:00
[![Integration level](https://dash.yunohost.org/integration/synapse.svg)](https://dash.yunohost.org/appci/app/synapse) ![Working status](https://ci-apps.yunohost.org/ci/badges/synapse.status.svg) ![Maintenance status](https://ci-apps.yunohost.org/ci/badges/synapse.maintain.svg)
[![Install Synapse with YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app=synapse)
2017-02-27 08:11:50 +01:00
2022-05-21 21:55:12 +02:00
*[Lire ce readme en français.](./README_fr.md)*
> *This package allows you to install Synapse quickly and simply on a YunoHost server.
If you don't have YunoHost, please consult [the guide](https://yunohost.org/#/install) to learn how to install it.*
2017-02-13 20:43:41 +01:00
2019-04-30 19:15:33 +02:00
## Overview
2017-12-15 22:54:09 +01:00
2018-02-12 21:11:15 +01:00
Instant messaging server matrix network.
2018-03-17 09:55:05 +01:00
Yunohost chatroom with matrix : [https://riot.im/app/#/room/#yunohost:matrix.org](https://riot.im/app/#/room/#yunohost:matrix.org)
2018-02-12 21:11:15 +01:00
2022-05-21 21:55:12 +02:00
2022-06-17 03:18:00 +02:00
**Shipped version:** 1.61.0~ynh1
2022-05-21 21:55:12 +02:00
## Disclaimers / important information
2018-02-12 21:11:15 +01:00
2019-04-30 19:15:33 +02:00
## Configuration
2017-10-13 14:57:26 +02:00
### Install for ARM arch (or slow arch)
2017-02-13 20:43:41 +01:00
2018-03-17 09:55:05 +01:00
For all slow or arm architecture it's recommended to build the dh file before the install to have a quicker install.
2020-05-28 21:18:18 +02:00
You could build it by this cmd : `openssl dhparam -out /etc/ssl/private/dh2048.pem 2048 > /dev/null`
2017-02-13 20:43:41 +01:00
After that you can install it without problem.
2018-03-17 09:55:05 +01:00
The package uses a prebuilt python virtual environnement. The binary are taken from this repository: https://github.com/Josue-T/synapse_python_build
2017-10-25 20:18:51 +02:00
The script to build the binary is also available.
2017-10-13 14:57:26 +02:00
### Web client
2017-02-13 20:43:41 +01:00
If you want a web client you can also install Element with this package: https://github.com/YunoHost-Apps/element_ynh .
2017-02-13 20:43:41 +01:00
2017-10-13 14:57:26 +02:00
### Access by federation
2017-02-13 20:43:41 +01:00
If your server name is identical to the domain on which synapse is installed, and the default port 8448 is used, your server is normally already accessible by the federation.
2019-02-08 15:27:41 +01:00
well-known support (#136) * Update README.md * Update manifest.json * a * Delete a * avoid boolean for public but ask a clear choice Yes/No * Update check_process Add server_name="domain2.tld" (DOMAIN) * .well-known DNS conf become optionnal with .well-known edition * .well-known redirection for access by federation Create .well-known redirection for access by federation * .well-known redirection for access by federation If not existing, create .well-known redirection for access by federation * Update README.md back to 0.99.5.2 * back to 0.99.5.2 * back to 0.99.5.2 * back to 0.99.5.2 * Update install * Update upgrade * Update install * Update upgrade * Update install * Update upgrade * Update .well-known redirection for access by federation and applications like Riot.im * Update .well-known redirection for access by federation and applications like Riot.im * update to 1.1.0 * update to 1.1.0 * update to 1.1.0 * update to 1.1.0 * update to 1.1.0 * update to 1.1.0 * Update install * Update upgrade * Update to 1.2.1 * Update to 1.2.1 * Update to 1.2.1 * Back to v1.1.0 * Back to v1.1.0 * Back to v1.1.0 * Update to v1.2.1 * Update to v1.2.1 * Update to v1.2.1 * Important update of upgrade script ynh_replace_string __SERVER_NAME__ $server_name "$homeserver_config_path" was missing * Back to v1.1.0 * Back to v1.1.0 * Back to v1.1.0 * Fix typo for ipv6 validation * Upgrade to v1.2.1 * Upgrade to v1.2.1 * Upgrade to v1.2.1 * remove server_name's nginx conf remove /etc/nginx/conf.d/${server_name}.d/server_name.conf * Create server_name.conf To allow the automatic well-known system for server-name detection instead of DNS record * Update install In # Create .well-known redirection for access by federation change cat > /etc/nginx/conf.d/${server_name}.d/server_name.conf <<EOF location /.well-known/matrix/ { return 200 '{"m.server": "$domain", "m.homeserver": "https://$domain"}'; add_header Content-Type application/json; add_header Access-Control-Allow-Origin '*'; } EOF to cp ../conf/server_name.conf /etc/nginx/conf.d/${server_name}.d/server_name.conf after creation of ../conf/server_name.conf file. * Update upgrade In # Create .well-known redirection for access by federation if it doesn't exist change cat > /etc/nginx/conf.d/${server_name}.d/server_name.conf <<EOF location /.well-known/matrix/ { return 200 '{"m.server": "$domain", "m.homeserver": "https://$domain"}'; add_header Content-Type application/json; add_header Access-Control-Allow-Origin '*'; } EOF to cp ../conf/server_name.conf /etc/nginx/conf.d/${server_name}.d/server_name.conf * backup well.known server_name nginx cond add ynh_backup "/etc/nginx/conf.d/${server_name}.d/server_name.conf" * Backup well.known server-name nging conf add server_name=$(ynh_app_setting_get $app server_name) to make ynh_backup "/etc/nginx/conf.d/${server_name}.d/server_name.conf" understood * Update backup * Update scripts/install Co-Authored-By: Josue-T <josue@tille.ch> * Update install * Update README.md Co-Authored-By: Josue-T <josue@tille.ch> * Update scripts/upgrade Co-Authored-By: Josue-T <josue@tille.ch> * Update conf/server_name.conf Co-Authored-By: Josue-T <josue@tille.ch> * move .well-known redirection to config section move #Create .well-known redirection for access by federation to end of config section * move .well-known redirection to config section move #Create .well-known redirection to the end of config section and Indentation * add checksum management for server_name.conf add checksum management for server_name.conf with the helper ynh_store_file_checksum * add checksum management for server_name.conf add checksum management for server_name.conf with the helper ynh_store_file_checksum * replace __SERVER_NAME__ * replace __SERVER_NAME__ * delete a blank line * Update upgrade * Update install * Update check_process Co-Authored-By: Josue-T <josue@tille.ch> * Update conf/server_name.conf Co-Authored-By: Josue-T <josue@tille.ch> * remove blank line * ynh_store_file_checksum after cp inside if block * change order checksum and cp change order to ynh_backup_if_checksum_is_different then cp then ynh_store_file_checksum * Update install * Update upgrade * Update backup * Update backup * Update scripts/backup Co-Authored-By: Josue-T <josue@tille.ch> * Update scripts/install Co-Authored-By: Josue-T <josue@tille.ch> * Update scripts/install Co-Authored-By: Josue-T <josue@tille.ch> * Update scripts/install Co-Authored-By: Josue-T <josue@tille.ch> * Update install * Update remove * Update upgrade
2019-12-01 22:18:56 +01:00
If not, you can add the following line in the dns configuration but you normally don't need it as a .well-known file is edited during the install to declare your server name and port to the federation.
2017-02-13 20:43:41 +01:00
```
_matrix._tcp.<server_name.tld> <ttl> IN SRV 10 0 <port> <domain-or-subdomain-of-synapse.tld>
2017-02-13 20:43:41 +01:00
```
for example
```
2019-05-11 14:45:00 +02:00
_matrix._tcp.example.com. 3600 IN SRV 10 0 SYNAPSE_PORT synapse.example.com.
2017-02-13 20:43:41 +01:00
```
2018-03-17 09:55:05 +01:00
You need to replace SYNAPSE_PORT by the real port. This port can be obtained by the command: `yunohost app setting SYNAPSE_INSTANCE_NAME synapse_tls_port`
2018-03-09 21:04:01 +01:00
For more details, see : https://github.com/matrix-org/synapse/blob/master/docs/federate.md
2019-02-08 15:27:41 +01:00
2018-03-17 09:55:05 +01:00
If it is not automatically done, you need to open this in your ISP box.
2018-03-09 21:04:01 +01:00
2019-02-08 11:24:08 +01:00
You also need a valid TLS certificate for the domain used by synapse. To do that you can refer to the documentation here : https://yunohost.org/#/certificate_en
2018-03-09 21:04:01 +01:00
### Turnserver
2018-03-17 09:55:05 +01:00
For Voip and video conferencing a turnserver is also installed (and configured). The turnserver listens on two UDP and TCP ports. You can get them with these commands:
2018-03-13 16:31:27 +01:00
```
yunohost app setting synapse turnserver_tls_port
yunohost app setting synapse turnserver_alt_tls_port
```
2018-07-05 21:46:24 +02:00
The turnserver will also choose a port dynamically when a new call starts. The range is between 49153 - 49193.
2018-05-10 13:58:51 +02:00
2018-07-05 21:46:24 +02:00
For some security reason the ports range (49153 - 49193) isn't automatically open by default. If you want to use the synapse server for voip or conferencing you will need to open this port range manually. To do this just run this command:
2018-03-09 21:04:01 +01:00
2018-06-20 19:23:51 +02:00
```
yunohost firewall allow Both 49153:49193
```
You might also need to open these ports (if it is not automatically done) on your ISP box.
2018-07-05 21:46:24 +02:00
To prevent the situation when the server is behind a NAT, the public IP is written in the turnserver config. By this the turnserver can send its real public IP to the client. For more information see [the coturn example config file](https://github.com/coturn/coturn/blob/master/examples/etc/turnserver.conf#L102-L120).So if your IP changes, you could run the script `/opt/yunohost/__SYNAPSE_INSTANCE_NAME__/Coturn_config_rotate.sh` to update your config.
2018-06-20 19:23:51 +02:00
2018-07-05 21:46:24 +02:00
If you have a dynamic IP address, you also might need to update this config automatically. To do that just edit a file named `/etc/cron.d/coturn_config_rotate` and add the following content (just adapt the __SYNAPSE_INSTANCE_NAME__ which could be `synapse` or maybe `synapse__2`).
2018-06-20 19:23:51 +02:00
```
*/15 * * * * root bash /opt/yunohost/__SYNAPSE_INSTANCE_NAME__/Coturn_config_rotate.sh;
```
2021-03-30 21:53:13 +02:00
#### OpenVPN
In case of you have an OpenVPN server you might want than `coturn-synapse` restart when the VPN restart. To do this create a file named `/usr/local/bin/openvpn_up_script.sh` with this content:
```
#!/bin/bash
(
sleep 5
sudo systemctl restart coturn-synapse.service
) &
exit 0
```
Add this line in you sudo config file `/etc/sudoers`
```
openvpn ALL=(ALL) NOPASSWD: /bin/systemctl restart coturn-synapse.service
```
And add this line in your OpenVPN config file
```
ipchange /usr/local/bin/openvpn_up_script.sh
```
2018-05-15 13:00:18 +02:00
2017-10-13 14:57:26 +02:00
### Important Security Note
2017-02-13 20:43:41 +01:00
We do not recommend running Element from the same domain name as your Matrix
2017-02-13 20:43:41 +01:00
homeserver (synapse). The reason is the risk of XSS (cross-site-scripting)
vulnerabilities that could occur if someone caused Element to load and render
2017-02-13 20:43:41 +01:00
malicious user generated content from a Matrix API which then had trusted
access to Element (or other apps) due to sharing the same domain.
2017-02-13 20:43:41 +01:00
We have put some coarse mitigations into place to try to protect against this
2018-03-17 09:55:05 +01:00
situation, but it's still not a good practice to do it in the first place. See
https://github.com/vector-im/element-web/issues/1977 for more details.
2017-02-13 20:43:41 +01:00
2019-04-30 19:15:33 +02:00
## YunoHost specific features
2017-12-29 20:24:57 +01:00
2019-04-30 19:15:33 +02:00
## Limitations
2018-02-12 21:11:15 +01:00
2018-03-17 09:55:05 +01:00
Synapse uses a lot of ressource. So on slow architecture (like small ARM board), this app could take a lot of CPU and RAM.
2018-02-12 21:11:15 +01:00
This app doesn't provide any real good web interface. So it's recommended to use Element client to connect to this app. This app is available [here](https://github.com/YunoHost-Apps/element_ynh)
2018-02-12 21:11:15 +01:00
2019-04-30 19:15:33 +02:00
## Additional information
2018-02-12 21:11:15 +01:00
2018-02-12 23:38:54 +01:00
### Multi instance support
2018-03-17 09:55:05 +01:00
To give a possibility to have multiple domains you can use multiple instances of synapse. In this case all instances will run on different ports so it's really important to put a SRV record in your domain. You can get the port that you need to put in your SRV record with this following command:
```
yunohost app setting synapse__<instancenumber> synapse_tls_port
```
2018-03-17 09:55:05 +01:00
Before installing a second instance of the app it's really recommended to update all existing instances.
2022-05-21 21:55:12 +02:00
## Documentation and resources
2022-05-26 17:28:09 +02:00
* Official app website: <https://matrix.org/>
* Upstream app code repository: <https://github.com/matrix-org/synapse>
2024-03-06 21:53:34 +01:00
* YunoHost Store: <https://apps.yunohost.org/app/synapse>
2022-05-26 17:28:09 +02:00
* Report a bug: <https://github.com/YunoHost-Apps/synapse_ynh/issues>
2022-05-21 21:55:12 +02:00
## Developer info
2022-05-21 21:55:12 +02:00
Please send your pull request to the [testing branch](https://github.com/YunoHost-Apps/synapse_ynh/tree/testing).
2022-05-21 21:55:12 +02:00
To try the testing branch, please proceed like that.
2022-05-26 17:28:09 +02:00
``` bash
2019-04-30 19:15:33 +02:00
sudo yunohost app install https://github.com/YunoHost-Apps/synapse_ynh/tree/testing --debug
2018-02-12 23:38:54 +01:00
or
2019-04-30 19:15:33 +02:00
sudo yunohost app upgrade synapse -u https://github.com/YunoHost-Apps/synapse_ynh/tree/testing --debug
2018-02-12 23:38:54 +01:00
```
2022-05-21 21:55:12 +02:00
2024-03-06 21:53:34 +01:00
**More info regarding app packaging:** <https://yunohost.org/packaging_apps>