Merge pull request #47 from YunoHost/add_comments

Add comments

README.md

@@ -1,22 +1,82 @@
-# Example app for YunoHost
+# Usage of this package (REMOVE THIS SECTION BEFORE RELEASE)
-
+- Copy this app before working on it.
-- [Yunohost project](https://yunohost.org)
-- [Exemple app website](https://example.com)
-
-Description of the app.
-
-## Usage
-- Copy this app before work on it.
 - Edit `conf/nginx.conf` file to match application prerequisites.
 - Edit `manifest.json` with application specific information.
 - Edit the `install`, `upgrade`, `remove`, `backup`, and `restore` scripts.
 - Add a `LICENSE` file for the package.
 - Edit `README.md`.
 
+# Example app for YunoHost
+
+[![Integration level](https://dash.yunohost.org/integration/REPLACEBYYOURAPP.svg)](https://ci-apps.yunohost.org/jenkins/job/REPLACEBYYOURAPP%20%28Community%29/lastBuild/consoleFull)  
+[![Install REPLACEBYYOURAPP with YunoHost](https://install-app.yunohost.org/install-with-yunohost.png)](https://install-app.yunohost.org/?app=REPLACEBYYOURAPP)
+
+> *This package allow you to install REPLACEBYYOURAPP quickly and simply on a YunoHost server.  
+If you don't have YunoHost, please see [here](https://yunohost.org/#/install) to know how to install and enjoy it.*
+
+## Overview
+Quick description of this app.
+
+**Shipped version:** 1.0
+
+## Screenshots
+
+![](Link to an screenshot for this app)
+
+## Demo
+
+* [Official demo](Link to a demo site for this app)
+
+## Configuration
+
+How to configure this app: by an admin panel, a plain file with ssh, or any other way.
+
+## Documentation
+
+ * Official documentation: Link to the official documentation of this app
+ * YunoHost documentation: There no other documentations, feel free to contribute.
+
+## YunoHost specific features
+
+#### Multi-users support
+
+Are LDAP and HTTP auth supported?
+Can the app be used by multiple users?
+
+#### Supported architectures
+
+* x86-64b - [![Build Status](https://ci-apps.yunohost.org/jenkins/job/REPLACEBYYOURAPP%20(Community)/badge/icon)](https://ci-apps.yunohost.org/jenkins/job/REPLACEBYYOURAPP%20(Community)/)
+* ARMv8-A - [![Build Status](https://ci-apps-arm.yunohost.org/jenkins/job/REPLACEBYYOURAPP%20(Community)%20(%7EARM%7E)/badge/icon)](https://ci-apps-arm.yunohost.org/jenkins/job/REPLACEBYYOURAPP%20(Community)%20(%7EARM%7E)/)
+* Jessie x86-64b - [![Build Status](https://ci-stretch.nohost.me/jenkins/job/REPLACEBYYOURAPP%20(Community)/badge/icon)](https://ci-stretch.nohost.me/jenkins/job/REPLACEBYYOURAPP%20(Community)/)
+
+## Limitations
+
+* Any known limitations.
+
+## Additional informations
+
+* Other informations you would add about this application
+
 **More information on the documentation page:**  
 https://yunohost.org/packaging_apps
 
-**Upgrade this package:**  
+## Links
-`sudo yunohost app upgrade --verbose example -u https://github.com/YunoHost-Apps/example_ynh`
 
-**Multi-user:** Yes/No. How about the ldap and HTTP auth support.
+ * Report a bug: https://github.com/YunoHost-Apps/REPLACEBYYOURAPP_ynh/issues
+ * App website: Link to the official website of this app
+ * YunoHost website: https://yunohost.org/
+
+---
+
+Developers infos
+----------------
+
+**Only if you want to use a testing branch for coding, instead of merging directly into master.**
+Please do your pull request to the [testing branch](https://github.com/YunoHost-Apps/REPLACEBYYOURAPP_ynh/tree/testing).
+
+To try the testing branch, please proceed like that.
+```
+sudo yunohost app install https://github.com/YunoHost-Apps/REPLACEBYYOURAPP_ynh/tree/testing --debug
+or
+sudo yunohost app upgrade REPLACEBYYOURAPP -u https://github.com/YunoHost-Apps/REPLACEBYYOURAPP_ynh/tree/testing --debug
+```

check_process.default

@@ -29,9 +29,9 @@
 	Level 1=auto
 	Level 2=auto
 	Level 3=auto
-# Level 4: 
+# Level 4: If the app supports LDAP and SSOwat, turn level 4 to '1' and add a link to an issue or a part of your code to show it.
+# If the app does not use LDAP nor SSOwat, and can't use them, turn level 4 to 'na' and explain as well.
 	Level 4=0
-# Level 5: 
 	Level 5=auto
 	Level 6=auto
 	Level 7=auto

conf/nginx.conf

@@ -4,11 +4,12 @@ location __PATH__/ {
   # Path to source
   alias __FINALPATH__/ ;
 
+  # Force usage of https
   if ($scheme = http) {
     rewrite ^ https://$server_name$request_uri? permanent;
   }
 
-  # Example PHP configuration (remove if not used)
+### Example PHP configuration (remove it if not used)
   index index.php;
 
   # Common parameter to increase upload size limit in conjuction with dedicated php-fpm file
@@ -19,20 +20,13 @@ location __PATH__/ {
     fastcgi_split_path_info ^(.+?\.php)(/.*)$;
     fastcgi_pass unix:/var/run/php5-fpm-__NAME__.sock;
 
-    # If you don't use a dedicated fpm config for your app,
-    # use a general fpm pool.
-    # This is to be used INSTEAD of line above
-    # Don't forget to adjust scripts install/upgrade/remove/backup accordingly
-    #
-    #fastcgi_pass unix:/var/run/php5-fpm.sock;
-
     fastcgi_index index.php;
     include fastcgi_params;
     fastcgi_param REMOTE_USER $remote_user;
     fastcgi_param PATH_INFO $fastcgi_path_info;
     fastcgi_param SCRIPT_FILENAME $request_filename;
   }
-  # PHP configuration end
+### End of PHP configuration part
 
   # Include SSOWAT user panel.
   include conf.d/yunohost_panel.conf.inc;

manifest.json

@@ -6,7 +6,7 @@
         "en": "Example package for YunoHost application.",
         "fr": "Exemple de package d’application pour YunoHost."
     },
-    "version": "1.0",
+    "version": "1.0~ynh1",
     "url": "https://example.com",
     "license": "free",
     "maintainer": {
@@ -15,7 +15,7 @@
         "url": "http://example.com"
     },
     "requirements": {
-        "yunohost": ">= 2.7.2"
+        "yunohost": ">= 2.7.14"
     },
     "multi_instance": true,
     "services": [
@@ -70,6 +70,19 @@
                 },
                 "choices": ["fr", "en"],
                 "default": "fr"
+            },
+            {
+                "name": "password",
+                "type": "password",
+                "ask": {
+                    "en": "Set the administrator password",
+                    "fr": "Définissez le mot de passe administrateur"
+                },
+                "help": {
+                    "en": "Use the help field to add an information for the admin about this question.",
+                    "fr": "Utilisez le champ aide pour ajouter une information à l'intention de l'administrateur à propos de cette question."
+                },
+                "example": "Choose a password"
             }
         ]
     }

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"

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

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
+### 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 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 instance number is available as $YNH_APP_INSTANCE_NUMBER (equals "1", "2", ...)
-# The app instance name is available as $YNH_APP_INSTANCE_NAME
+### The app instance name is available as $YNH_APP_INSTANCE_NAME
-#    - the first time the app is installed, YNH_APP_INSTANCE_NAME = ynhexample
+###    - 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
+###    - the second time the app is installed, YNH_APP_INSTANCE_NAME = ynhexample__2
-#    - ynhexample__{N} for the subsequent installations, with N=3,4, ...
+###    - 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
+### 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,
+### guaranteed to be unique. This is a good unique identifier to define installation path,
-# db names, ...
+### 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

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
 

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
 

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"
+# UPGRADE DEPENDENCIES
-fi
+#=================================================
-ynh_store_file_checksum "/etc/nginx/conf.d/$domain.d/$app.conf"
+
+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