diff --git a/README.md b/README.md index 40e7524..df120d3 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,82 @@ -# Example app for YunoHost - -- [Yunohost project](https://yunohost.org) -- [Exemple app website](https://example.com) - -Description of the app. - -## Usage -- Copy this app before work on it. +# Usage of this package (REMOVE THIS SECTION BEFORE RELEASE) +- Copy this app before working 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`. -**More information on the documentation page:** +# 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:** -`sudo yunohost app upgrade --verbose example -u https://github.com/YunoHost-Apps/example_ynh` +## Links -**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 +``` diff --git a/check_process.default b/check_process.default index d7e2812..480a103 100644 --- a/check_process.default +++ b/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 diff --git a/conf/nginx.conf b/conf/nginx.conf index 8c40e3a..d496165 100644 --- a/conf/nginx.conf +++ b/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; diff --git a/manifest.json b/manifest.json index 0179154..a807cbf 100644 --- a/manifest.json +++ b/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" } ] } diff --git a/scripts/backup b/scripts/backup index db64b8a..b7448e5 100755 --- 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" diff --git a/scripts/change_url b/scripts/change_url index cc1a7e2..f71fc77 100644 --- 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 diff --git a/scripts/install b/scripts/install index f9f3919..ce7ca86 100755 --- 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 diff --git a/scripts/remove b/scripts/remove index 9f6aa8e..f3e6ebe 100755 --- 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 diff --git a/scripts/restore b/scripts/restore index 837eaa4..92c999d 100755 --- 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 diff --git a/scripts/upgrade b/scripts/upgrade index 015e6b6..6a76809 100755 --- 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