Merge pull request #47 from YunoHost/add_comments

Add comments
2018-07-30 09:58:07 +02:00
parent 3165e398fd 397a241df6
commit c6bdc79713
10 changed files with 221 additions and 69 deletions
--- a/scripts/backup
+++ b/scripts/backup
@@ -13,6 +13,10 @@ source /usr/share/yunohost/helpers
 # MANAGE SCRIPT FAILURE
 #=================================================

+ynh_clean_setup () {
+	### Remove this function if there's nothing to clean before calling the remove script.
+	true
+}
 # Exit if an error occurs during the execution of the script
 ynh_abort_if_errors

@@ -68,7 +72,7 @@ ynh_backup "/etc/logrotate.d/$app"
 ynh_backup "/etc/systemd/system/$app.service"

 #=================================================
-# BACKUP THE CRON FILE
+# BACKUP A CRON FILE
 #=================================================

 ynh_backup "/etc/cron.d/$app"
--- a/scripts/change_url
+++ b/scripts/change_url
@@ -75,11 +75,6 @@ then
 	path_url="$new_path"
 	# Create a dedicated nginx config
 	ynh_add_nginx_config
-	if [ "$path_url" != "/" ]
-	then
-		ynh_replace_string "^#sub_path_only " "" "$nginx_conf_path"
-	fi
-	ynh_store_file_checksum "$nginx_conf_path"
 fi

 # Change the domain for nginx
--- a/scripts/install
+++ b/scripts/install
@@ -13,6 +13,10 @@ source /usr/share/yunohost/helpers
 # MANAGE SCRIPT FAILURE
 #=================================================

+ynh_clean_setup () {
+	### Remove this function if there's nothing to clean before calling the remove script.
+	true
+}
 # Exit if an error occurs during the execution of the script
 ynh_abort_if_errors

@@ -25,23 +29,26 @@ path_url=$YNH_APP_ARG_PATH
 admin=$YNH_APP_ARG_ADMIN
 is_public=$YNH_APP_ARG_IS_PUBLIC
 language=$YNH_APP_ARG_LANGUAGE
+password=$YNH_APP_ARG_PASSWORD

-# This is a multi-instance app, meaning it can be installed several times independently
-# The id of the app as stated in the manifest is available as $YNH_APP_ID
-# The instance number is available as $YNH_APP_INSTANCE_NUMBER (equals "1", "2", ...)
-# The app instance name is available as $YNH_APP_INSTANCE_NAME
-#    - the first time the app is installed, YNH_APP_INSTANCE_NAME = ynhexample
-#    - the second time the app is installed, YNH_APP_INSTANCE_NAME = ynhexample__2
-#    - ynhexample__{N} for the subsequent installations, with N=3,4, ...
-# The app instance name is probably what you are interested the most, since this is
-# guaranteed to be unique. This is a good unique identifier to define installation path,
-# db names, ...
+### If it's a multi-instance app, meaning it can be installed several times independently
+### The id of the app as stated in the manifest is available as $YNH_APP_ID
+### The instance number is available as $YNH_APP_INSTANCE_NUMBER (equals "1", "2", ...)
+### The app instance name is available as $YNH_APP_INSTANCE_NAME
+###    - the first time the app is installed, YNH_APP_INSTANCE_NAME = ynhexample
+###    - the second time the app is installed, YNH_APP_INSTANCE_NAME = ynhexample__2
+###    - ynhexample__{N} for the subsequent installations, with N=3,4, ...
+### The app instance name is probably what interests you most, since this is
+### guaranteed to be unique. This is a good unique identifier to define installation path,
+### db names, ...
 app=$YNH_APP_INSTANCE_NAME

 #=================================================
 # CHECK IF THE APP CAN BE INSTALLED WITH THESE ARGS
 #=================================================

+### If the app uses nginx as web server (written in HTML/PHP in most cases), the final path should be "/var/www/$app".
+### If the app provides an internal web server (or uses another application server such as uwsgi), the final path should be "/opt/yunohost/$app"
 final_path=/var/www/$app
 test ! -e "$final_path" || ynh_die "This path already contains a folder"

@@ -69,6 +76,11 @@ ynh_app_setting_set $app language $language
 # FIND AND OPEN A PORT
 #=================================================

+### Use these lines if you have to open a port for the application
+### `ynh_find_port` will find the first available port starting from the given port.
+### If you're not using these lines:
+###		- Remove the section "CLOSE A PORT" in the remove script
+
 # Find a free port
 port=$(ynh_find_port 8095)
 # Open this port
@@ -79,13 +91,27 @@ ynh_app_setting_set $app port $port
 # INSTALL DEPENDENCIES
 #=================================================

+### `ynh_install_app_dependencies` allows you to add any "apt" dependencies to the package.
+### Those deb packages will be installed as dependencies of this package.
+### If you're not using this helper:
+###		- Remove the section "REMOVE DEPENDENCIES" in the remove script
+###		- As well as the section "REINSTALL DEPENDENCIES" in the restore script
+###		- And the section "UPGRADE DEPENDENCIES" in the upgrade script
+
 ynh_install_app_dependencies deb1 deb2

 #=================================================
 # CREATE A MYSQL DATABASE
 #=================================================
-# If your app uses a MySQL database, you can use these lines to bootstrap
-# a database, an associated user and save the password in app settings
+
+### Use these lines if you need a database for the application.
+### `ynh_mysql_setup_db` will create a database, an associated user and a ramdom password.
+### The password will be stored as 'mysqlpwd' into the app settings,
+### and will be available as $db_pwd
+### If you're not using these lines:
+###		- Remove the section "BACKUP THE MYSQL DATABASE" in the backup script
+###		- Remove also the section "REMOVE THE MYSQL DATABASE" in the remove script
+###		- As well as the section "RESTORE THE MYSQL DATABASE" in the restore script

 db_name=$(ynh_sanitize_dbid $app)
 ynh_app_setting_set $app db_name $db_name
@@ -95,6 +121,10 @@ ynh_mysql_setup_db $db_name $db_name
 # DOWNLOAD, CHECK AND UNPACK SOURCE
 #=================================================

+### `ynh_setup_source` is used to install an app from a zip or tar.gz file,
+### downloaded from an upstream source, like a git repository.
+### `ynh_setup_source` use the file conf/app.src
+
 ynh_app_setting_set $app final_path $final_path
 # Download, check integrity, uncompress and patch the source from app.src
 ynh_setup_source "$final_path"
@@ -103,13 +133,10 @@ ynh_setup_source "$final_path"
 # NGINX CONFIGURATION
 #=================================================

+### `ynh_add_nginx_config` will use the file conf/nginx.conf
+
 # Create a dedicated nginx config
 ynh_add_nginx_config
-if [ "$path_url" != "/" ]
-then
-	ynh_replace_string "^#sub_path_only" "" "/etc/nginx/conf.d/$domain.d/$app.conf"
-fi
-ynh_store_file_checksum "/etc/nginx/conf.d/$domain.d/$app.conf"

 #=================================================
 # CREATE DEDICATED USER
@@ -122,6 +149,17 @@ ynh_system_user_create $app
 # PHP-FPM CONFIGURATION
 #=================================================

+### `ynh_add_fpm_config` is used to set up a PHP config.
+### You can remove it if your app doesn't use PHP.
+### `ynh_add_fpm_config` will use the files conf/php-fpm.conf and conf/php-fpm.ini
+### If you're not using these lines:
+###		- You can remove these files in conf/.
+###		- Remove the section "BACKUP THE PHP-FPM CONFIGURATION" in the backup script
+###		- Remove also the section "REMOVE PHP-FPM CONFIGURATION" in the remove script
+###		- As well as the section "RESTORE THE PHP-FPM CONFIGURATION" in the restore script
+###		With the reload at the end of the script.
+###		- And the section "PHP-FPM CONFIGURATION" in the upgrade script
+
 # Create a dedicated php-fpm config
 ynh_add_fpm_config

@@ -135,6 +173,17 @@ ynh_add_fpm_config
 # SETUP SYSTEMD
 #=================================================

+### `ynh_systemd_config` is used to configure a systemd script for an app.
+### It can be used for apps that use sysvinit (with adaptation) or systemd.
+### Have a look at the app to be sure this app needs a systemd script.
+### `ynh_systemd_config` will use the file conf/systemd.service
+### If you're not using these lines:
+###		- You can remove those files in conf/.
+###		- Remove the section "BACKUP SYSTEMD" in the backup script
+###		- Remove also the section "STOP AND REMOVE SERVICE" in the remove script
+###		- As well as the section "RESTORE SYSTEMD" in the restore script
+###		- And the section "SETUP SYSTEMD" in the upgrade script
+
 # Create a dedicated systemd config
 ynh_add_systemd_config

@@ -142,6 +191,11 @@ ynh_add_systemd_config
 # SETUP APPLICATION WITH CURL
 #=================================================

+### Use these lines only if the app installation needs to be finalized through
+### web forms. We generally don't want to ask the final user,
+### so we're going to use curl to automatically fill the fields and submit the
+### forms.
+
 # Set right permissions for curl install
 chown -R $app: $final_path

@@ -156,16 +210,29 @@ systemctl reload nginx
 # Installation with curl
 ynh_local_curl "/INSTALL_PATH" "key1=value1" "key2=value2" "key3=value3"

+# Remove the public access
+if [ $is_public -eq 0 ]
+then
+	ynh_app_setting_delete $app skipped_uris
+fi
+
 #=================================================
 # MODIFY A CONFIG FILE
 #=================================================

+### `ynh_replace_string` is used to replace a string in a file.
+### (It's compatible with sed regular expressions syntax)
+
 ynh_replace_string "match_string" "replace_string" "$final_path/CONFIG_FILE"

 #=================================================
-# STORE THE CHECKSUM OF THE CONFIG FILE
+# STORE THE CONFIG FILE CHECKSUM
 #=================================================

+### `ynh_store_file_checksum` is used to store the checksum of a file.
+### That way, during the upgrade script, by using `ynh_backup_if_checksum_is_different`,
+### you can make a backup of this file before modifying it again if the admin had modified it.
+
 # Calculate and store the config file checksum into the app settings
 ynh_store_file_checksum "$final_path/CONFIG_FILE"

@@ -175,6 +242,10 @@ ynh_store_file_checksum "$final_path/CONFIG_FILE"
 # SECURE FILES AND DIRECTORIES
 #=================================================

+### For security reason, any app should set the permissions to root: before anything else.
+### Then, if write authorization is needed, any access should be given only to directories
+### that really need such authorization.
+
 # Set permissions to app files
 chown -R root: $final_path

@@ -182,6 +253,14 @@ chown -R root: $final_path
 # SETUP LOGROTATE
 #=================================================

+### `ynh_use_logrotate` is used to configure a logrotate configuration for the logs of this app.
+### Use this helper only if there is effectively a log file for this app.
+### If you're not using this helper:
+###		- Remove the section "BACKUP LOGROTATE" in the backup script
+###		- Remove also the section "REMOVE LOGROTATE CONFIGURATION" in the remove script
+###		- As well as the section "RESTORE THE LOGROTATE CONFIGURATION" in the restore script
+###		- And the section "SETUP LOGROTATE" in the upgrade script
+
 # Use logrotate to manage application logfile(s)
 ynh_use_logrotate

@@ -189,16 +268,20 @@ ynh_use_logrotate
 # ADVERTISE SERVICE IN ADMIN PANEL
 #=================================================

+### `yunohost service add` is a CLI yunohost command to add a service in the admin panel.
+### You'll find the service in the 'services' section of YunoHost admin panel.
+### This CLI command would be useless if the app does not have any services (systemd or sysvinit)
+### If you're not using these lines:
+###		- You can remove these files in conf/.
+###		- Remove the section "REMOVE SERVICE FROM ADMIN PANEL" in the remove script
+###		- As well as the section ADVERTISE SERVICE IN ADMIN PANEL" in the restore script
+
 yunohost service add NAME_INIT.D --log "/var/log/FILE.log"

 #=================================================
 # SETUP SSOWAT
 #=================================================

-if [ $is_public -eq 0 ]
-then	# Remove the public access
-	ynh_app_setting_delete $app skipped_uris
-fi
 # Make app public if necessary
 if [ $is_public -eq 1 ]
 then
--- a/scripts/remove
+++ b/scripts/remove
@@ -34,6 +34,7 @@ ynh_remove_systemd_config
 # REMOVE SERVICE FROM ADMIN PANEL
 #=================================================

+# Remove a service from the admin panel, added by `yunohost service add`
 if yunohost service status | grep -q $app
 then
 	echo "Remove $app service"
@@ -88,7 +89,7 @@ ynh_remove_logrotate

 if yunohost firewall list | grep -q "\- $port$"
 then
-	echo "Close port $port"
+	echo "Close port $port" >&2
 	yunohost firewall disallow TCP $port 2>&1
 fi

--- a/scripts/restore
+++ b/scripts/restore
@@ -13,6 +13,10 @@ source /usr/share/yunohost/helpers
 # MANAGE SCRIPT FAILURE
 #=================================================

+ynh_clean_setup () {
+	#### Remove this function if there's nothing to clean before calling the remove script.
+	true
+}
 # Exit if an error occurs during the execution of the script
 ynh_abort_if_errors

--- a/scripts/upgrade
+++ b/scripts/upgrade
@@ -20,7 +20,7 @@ path_url=$(ynh_app_setting_get $app path)
 admin=$(ynh_app_setting_get $app admin)
 is_public=$(ynh_app_setting_get $app is_public)
 final_path=$(ynh_app_setting_get $app final_path)
-port=$(ynh_app_setting_get $app port)
+language=$(ynh_app_setting_get $app language)
 db_name=$(ynh_app_setting_get $app db_name)

 #=================================================
@@ -83,17 +83,18 @@ ynh_setup_source "$final_path"

 # Create a dedicated nginx config
 ynh_add_nginx_config
-if [ "$path_url" != "/" ]
-then
-	ynh_replace_string "^#sub_path_only" "" "/etc/nginx/conf.d/$domain.d/$app.conf"
-fi
-ynh_store_file_checksum "/etc/nginx/conf.d/$domain.d/$app.conf"
+
+#=================================================
+# UPGRADE DEPENDENCIES
+#=================================================
+
+ynh_install_app_dependencies deb1 deb2

 #=================================================
 # CREATE DEDICATED USER
 #=================================================

-# Create a system user
+# Create a dedicated user (if not existing)
 ynh_system_user_create $app

 #=================================================
@@ -109,9 +110,10 @@ ynh_add_fpm_config
 # ...
 #=================================================

-# Verify the checksum and backup the file if it's different
+### Verify the checksum of a file, stored by `ynh_store_file_checksum` in the install script.
+### And create a backup of this file if the checksum is different. So the file will be backed up if the admin had modified it.
 ynh_backup_if_checksum_is_different "$final_path/CONFIG_FILE"
-# Recalculate and store the config file checksum into the app settings
+# Recalculate and store the checksum of the file for the next upgrade.
 ynh_store_file_checksum "$final_path/CONFIG_FILE"

 #=================================================
@@ -134,17 +136,13 @@ ynh_add_systemd_config
 # SECURE FILES AND DIRECTORIES
 #=================================================

-# Set right permissions for curl installation
+# Set permissions on app files
 chown -R root: $final_path

 #=================================================
 # SETUP SSOWAT
 #=================================================

-if [ $is_public -eq 0 ]
-then	# Remove the public access
-	ynh_app_setting_delete $app skipped_uris
-fi
 # Make app public if necessary
 if [ $is_public -eq 1 ]
 then