Merge pull request #301 from YunoHost-Apps/add-_synapse-perm

README.md

@@ -131,6 +131,70 @@ This app doesn't provide any real good web interface. So it's recommended to use
 
 ## Additional information
 
+## Administration
+
+**All documentation of this section is not warranted. A bad use of command could break the app and all the data. So use these commands at your own risk.**
+
+Before any manipulation it's recommended to do a backup by this following command :
+
+`sudo yunohost backup create --apps synapse`
+
+### Set user as admin
+
+Actually there are no functions in the client interface to set a user as admin. So it's possible to enable it manually in the database.
+
+The following command will grant admin privilege to the specified user:
+```
+su --command="psql matrix_synapse" postgres <<< "UPDATE users SET admin = 1 WHERE name = '@user_to_be_admin:domain.tld'"
+```
+
+### Administration API
+
+Synapse's administration API endpoints are under `/_synapse` path and protected with the `admin_api` permission.
+By default, no one has access to this path.
+
+If you wish to access it, for example to use [Synapse Admin](https://github.com/YunoHost-Apps/synapse-admin_ynh),
+you need to give this permission to visitors.
+
+Then, to log in the API with your credentials, you need to set your user as admin (cf. precedent section).
+
+### Upgrade
+
+By default a backup is made before the upgrade. To avoid this you have theses following possibilites:
+- Call the command with the `-b` flag: `yunohost app upgrade synapse -b`
+- Set the settings `disable_backup_before_upgrade` to `1`. You can set this with this command:
+
+`yunohost app setting synapse disable_backup_before_upgrade -v 1`
+
+After this settings will be applied for **all** next upgrade.
+
+From command line:
+
+`yunohost app upgrade synapse`
+
+### Backup
+
+This app use now the core-only feature of the backup. To keep the integrity of the data and to have a better guarantee of the restoration is recommended to proceed like this:
+
+- Stop synapse service with theses following command:
+
+`systemctl stop synapse.service`
+
+- Launch the backup of synapse with this following command:
+
+`yunohost backup create --app synapse`
+
+- Do a backup of your data with your specific strategy (could be with rsync, borg backup or just cp). The data is generally stored in `/home/yunohost.app/matrix-synapse`.
+- Restart the synapse service with these command:
+
+`systemctl start synapse.service`
+
+### Remove
+
+Due of the backup core only feature the data directory in `/home/yunohost.app/matrix-synapse` **is not removed**.
+
+Use the `--purge` flag with the command, or remove it manually to purge app user data.
+
 ### Multi instance support
 
 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:

README_fr.md

@@ -131,6 +131,70 @@ This app doesn't provide any real good web interface. So it's recommended to use
 
 ## Additional information
 
+## Administration
+
+**All documentation of this section is not warranted. A bad use of command could break the app and all the data. So use these commands at your own risk.**
+
+Before any manipulation it's recommended to do a backup by this following command :
+
+`sudo yunohost backup create --apps synapse`
+
+### Set user as admin
+
+Actually there are no functions in the client interface to set a user as admin. So it's possible to enable it manually in the database.
+
+The following command will grant admin privilege to the specified user:
+```
+su --command="psql matrix_synapse" postgres <<< "UPDATE users SET admin = 1 WHERE name = '@user_to_be_admin:domain.tld'"
+```
+
+### Administration API
+
+Synapse's administration API endpoints are under `/_synapse` path and protected with the `admin_api` permission.
+By default, no one has access to this path.
+
+If you wish to access it, for example to use [Synapse Admin](https://github.com/YunoHost-Apps/synapse-admin_ynh),
+you need to give this permission to visitors.
+
+Then, to log in the API with your credentials, you need to set your user as admin (cf. precedent section).
+
+### Upgrade
+
+By default a backup is made before the upgrade. To avoid this you have theses following possibilites:
+- Call the command with the `-b` flag: `yunohost app upgrade synapse -b`
+- Set the settings `disable_backup_before_upgrade` to `1`. You can set this with this command:
+
+`yunohost app setting synapse disable_backup_before_upgrade -v 1`
+
+After this settings will be applied for **all** next upgrade.
+
+From command line:
+
+`yunohost app upgrade synapse`
+
+### Backup
+
+This app use now the core-only feature of the backup. To keep the integrity of the data and to have a better guarantee of the restoration is recommended to proceed like this:
+
+- Stop synapse service with theses following command:
+
+`systemctl stop synapse.service`
+
+- Launch the backup of synapse with this following command:
+
+`yunohost backup create --app synapse`
+
+- Do a backup of your data with your specific strategy (could be with rsync, borg backup or just cp). The data is generally stored in `/home/yunohost.app/matrix-synapse`.
+- Restart the synapse service with these command:
+
+`systemctl start synapse.service`
+
+### Remove
+
+Due of the backup core only feature the data directory in `/home/yunohost.app/matrix-synapse` **is not removed**.
+
+Use the `--purge` flag with the command, or remove it manually to purge app user data.
+
 ### Multi instance support
 
 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:

doc/DISCLAIMER.md

@@ -105,6 +105,70 @@ This app doesn't provide any real good web interface. So it's recommended to use
 
 ## Additional information
 
+## Administration
+
+**All documentation of this section is not warranted. A bad use of command could break the app and all the data. So use these commands at your own risk.**
+
+Before any manipulation it's recommended to do a backup by this following command :
+
+`sudo yunohost backup create --apps synapse`
+
+### Set user as admin
+
+Actually there are no functions in the client interface to set a user as admin. So it's possible to enable it manually in the database.
+
+The following command will grant admin privilege to the specified user:
+```
+su --command="psql matrix_synapse" postgres <<< "UPDATE users SET admin = 1 WHERE name = '@user_to_be_admin:domain.tld'"
+```
+
+### Administration API
+
+Synapse's administration API endpoints are under `/_synapse` path and protected with the `admin_api` permission.
+By default, no one has access to this path.
+
+If you wish to access it, for example to use [Synapse Admin](https://github.com/YunoHost-Apps/synapse-admin_ynh),
+you need to give this permission to visitors.
+
+Then, to log in the API with your credentials, you need to set your user as admin (cf. precedent section).
+
+### Upgrade
+
+By default a backup is made before the upgrade. To avoid this you have theses following possibilites:
+- Call the command with the `-b` flag: `yunohost app upgrade synapse -b`
+- Set the settings `disable_backup_before_upgrade` to `1`. You can set this with this command:
+
+`yunohost app setting synapse disable_backup_before_upgrade -v 1`
+
+After this settings will be applied for **all** next upgrade.
+
+From command line:
+
+`yunohost app upgrade synapse`
+
+### Backup
+
+This app use now the core-only feature of the backup. To keep the integrity of the data and to have a better guarantee of the restoration is recommended to proceed like this:
+
+- Stop synapse service with theses following command:
+
+`systemctl stop synapse.service`
+
+- Launch the backup of synapse with this following command:
+
+`yunohost backup create --app synapse`
+
+- Do a backup of your data with your specific strategy (could be with rsync, borg backup or just cp). The data is generally stored in `/home/yunohost.app/matrix-synapse`.
+- Restart the synapse service with these command:
+
+`systemctl start synapse.service`
+
+### Remove
+
+Due of the backup core only feature the data directory in `/home/yunohost.app/matrix-synapse` **is not removed**.
+
+Use the `--purge` flag with the command, or remove it manually to purge app user data.
+
 ### Multi instance support
 
 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:

scripts/change_url

@@ -122,7 +122,9 @@ ynh_add_config --template="log.yaml" --destination="/etc/matrix-$app/log.yaml"
 
 ynh_script_progression --message="Configuring permissions..." --weight=1
 ynh_permission_url --permission=server_api --clear_urls
-ynh_permission_url --permission=server_api --url=$domain/_matrix --additional_urls=$server_name/.well-known/matrix \
+ynh_permission_url --permission=server_api --url=$domain/_matrix --additional_urls=$server_name/.well-known/matrix
+ynh_permission_url --permission=admin_api --clear_urls
+ynh_permission_url --permission=admin_api --url=$domain/_synapse
 
 #=================================================
 # RELOAD SERVICES

scripts/install

@@ -336,6 +336,9 @@ ynh_permission_update --permission=main --show_tile=false --protected=true
 ynh_permission_create --permission=server_api --url=$domain/_matrix \
                       --label="Server access for client apps." --show_tile=false --allowed=visitors \
                       --auth_header=false --protected=true
+ynh_permission_create --permission=admin_api --url=$domain/_synapse \
+                      --label="Server administration API." --show_tile=false \
+                      --auth_header=false
 if yunohost --output-as plain domain list | grep -q "^$server_name$"; then
     ynh_permission_create --permission=server_client_infos --url=$server_name/.well-known/matrix \
                           --label="Server info for clients. (well-known)" --show_tile=false --allowed=visitors \

scripts/upgrade

@@ -439,6 +439,12 @@ elif yunohost --output-as plain domain list | grep -q "^$server_name"'$'; then
                           --protected=true
 fi
 
+if ! ynh_permission_exists --permission=admin_api; then
+    ynh_permission_create --permission=admin_api --url=$domain/_synapse \
+                          --label="Server administration API." --show_tile=false \
+                          --auth_header=false
+fi
+
 #=================================================
 # SECURE FILES AND DIRECTORIES
 #=================================================