From 000f918fef6ff494afa4751c945515ff511fd05e Mon Sep 17 00:00:00 2001 From: "ljf (zamentur)" Date: Wed, 20 Sep 2017 09:22:23 +0200 Subject: [PATCH] [enh] List variable for hooks and script to manage apps (#538) * [enh] List variable for hooks and script to manage apps * Ajoute un lien sur pour les variables --- packaging_apps_hooks_fr.md | 16 ++++- packaging_apps_scripts.md | 109 ++++++++++++++++++----------------- packaging_apps_scripts_fr.md | 108 +++++++++++++++++----------------- 3 files changed, 128 insertions(+), 105 deletions(-) diff --git a/packaging_apps_hooks_fr.md b/packaging_apps_hooks_fr.md index 2ca12a7b..0ff4fd75 100644 --- a/packaging_apps_hooks_fr.md +++ b/packaging_apps_hooks_fr.md @@ -26,6 +26,14 @@ Après l'ajout d'un utilisateur autorisé sur une application. Après la suppression de l'autorisation d'un utilisateur sur une application. - `post_app_clearaccess` Après l'effacement de toute les règles d'accès sur une application. +- `post_app_install` +Après l'installation d'une application +- `post_app_upgrade` +Après l'upgrade d'une applications +- `post_app_remove` +Après la supression d'une applications +- `post_app_change_url` +Après avoir modifié le chemin et ou le nom de domaine d'une application - `conf_regen` Avant et après la régénération de la configuration d'un service. Services pris en charge par regen-conf: @@ -84,7 +92,6 @@ password=$3 # Clear password firstname=$4 lastname=$5 ``` - ##### `post_user_delete` ```bash @@ -105,6 +112,13 @@ ipv6=$2 # True/False Indique si l'IPV6 est activé ou non. backup_name=$1 ``` +##### `post_app_install`, `post_app_upgrade`, `post_app_remove` et `post_app_change_url` + +Les variables utilisables dans ces scripts sont les mêmes que celles disponibles dans [les scripts d'actions associés](/packaging_apps_scripts_fr). + + +Example: pour `post_app_install` les variables sont les mêmes que pour le script `install` + ##### `post_app_addaccess` et `post_app_removeaccess` ```bash diff --git a/packaging_apps_scripts.md b/packaging_apps_scripts.md index 17ee5194..3db089a5 100644 --- a/packaging_apps_scripts.md +++ b/packaging_apps_scripts.md @@ -2,60 +2,65 @@ ## Scripts -For now, a YunoHost package must contain five Shell scripts: `install`, `remove`, `upgrade`, `backup` and `restore`. -These scripts will be executed as `admin` on the YunoHost instances. +For now, a YunoHost package must contain five Shell scripts: `install`, `remove`, `upgrade`, `backup` and `restore`. A 6th script `change_url` can also be added optionally. +These scripts will be executed as `root` on the YunoHost instances. -Here is an example: -```bash -# Retrieve arguments -domain=$1 -path=$2 - -# Check domain/path availability -sudo yunohost app checkurl $domain$path -a roundcube -if [[ ! $? -eq 0 ]]; then - exit 1 -fi - -# Generate random DES key & password -deskey=$(dd if=/dev/urandom bs=1 count=200 2> /dev/null | tr -c -d '[A-Za-z0-9]' | sed -n 's/\(.\{24\}\).*/\1/p') -db_pwd=$(dd if=/dev/urandom bs=1 count=200 2> /dev/null | tr -c -d '[A-Za-z0-9]' | sed -n 's/\(.\{24\}\).*/\1/p') - -# Use 'roundcube' as database name and user -db_user=roundcube - -# Initialize database and store mysql password for upgrade -sudo yunohost app initdb $db_user -p $db_pwd -s $(readlink -e ../sources/SQL/mysql.initial.sql) -sudo yunohost app setting roundcube mysqlpwd -v $db_pwd - -# Copy files to the right place -final_path=/var/www/roundcube -sudo mkdir -p $final_path -sudo cp -a ../sources/* $final_path -sudo cp ../conf/main.inc.php $final_path/config/ -sudo cp ../conf/db.inc.php $final_path/config/ -sudo mv $final_path/plugins/managesieve/config.inc.php.dist $final_path/plugins/managesieve/config.inc.php - -# Change variables in Roundcube configuration -sudo sed -i "s/rcmail-ynhDESkeyTOchange/$deskey/g" $final_path/config/main.inc.php -sudo sed -i "s/yunouser/$db_user/g" $final_path/config/db.inc.php -sudo sed -i "s/yunopass/$db_pwd/g" $final_path/config/db.inc.php -sudo sed -i "s/yunobase/$db_user/g" $final_path/config/db.inc.php - -# Set permissions to roundcube directory -sudo chown -R www-data: $final_path - -# Modify Nginx configuration file and copy it to Nginx conf directory -sed -i "s@PATHTOCHANGE@$path@g" ../conf/nginx.conf -sed -i "s@ALIASTOCHANGE@$final_path/@g" ../conf/nginx.conf -sudo cp ../conf/nginx.conf /etc/nginx/conf.d/$domain.d/roundcube.conf - -# Reload nginx and regenerate SSOwat conf -sudo service nginx reload -sudo yunohost app ssowatconf -``` +Examples scripts are available in the [example app](https://github.com/YunoHost/example_ynh/tree/master/scripts) ### Usage You have to put everything in the `install` script in order to get the app to install without issue. It means that you have to install dependencies, create required repositories, initialize potential databases, copy sources and configure everything in the single `install` script (and of course do the reverse process in the `remove` script). -**Be careful**: for security reasons, the script is executed as the **admin** user in YunoHost. Be sure to test it as **admin** and prepend `sudo` to commands that require it. \ No newline at end of file +It's possible to use helpers and import function library by example from a `_common.sh` file. + +### Available variables for these scripts +#### YNH_CWD +This var contains the current working directory path of the executed script. It can be useful for find out the initial path if we have move of directory during the script execution. It is used by some helpers to be sure to use the good directory. + +#### YNH_APP_ID +It contains the application's identifier without the instance's number. + +Example: strut + +#### YNH_APP_INSTANCE_NAME +It contains the instance name which will is used in a lot of situation to manage multiple setup of the same app. + +Example: strut__3 +#### YNH_APP_INSTANCE_NUMBER +It contains the instance's number. Warning, it's not the number of running instances because an old app might be deleted. + +Example: 3 + +### Specific variables to use in `install` +#### YNH_APP_ARG_XXXXXXX +An environment variable is available for each question asked in the installation. + +For example, if in the manifest we have a question like this +``` +{ + "name": "domain", + "type": "domain", + "ask": { + "en": "Choose a domain for OpenSondage", + "fr": "Choisissez un nom de domaine pour OpenSondage", + "de": "Wählen Sie bitte einen Domain für OpenSondage" + }, + "example": "domain.org" +}, +``` + +The name of the question is `domain` so in the script we can access it with YNH_APP_ARG_DOMAIN. The usage is to create a shorter name in the script like this: + +``` +domain=$YNH_APP_ARG_DOMAIN +``` + +### Variables spécifiques pour `change_url` +#### YNH_APP_OLD_DOMAIN +The old domain where the app was installed. +#### YNH_APP_OLD_PATH +The old path where the app was installed. +#### YNH_APP_NEW_DOMAIN +The new domain where move the app. +#### YNH_APP_NEW_PATH +The new path where move the app. + diff --git a/packaging_apps_scripts_fr.md b/packaging_apps_scripts_fr.md index 5cb174e0..17658af1 100644 --- a/packaging_apps_scripts_fr.md +++ b/packaging_apps_scripts_fr.md @@ -2,60 +2,64 @@ ## Les scripts -Un paquet YunoHost doit contenir cinq scripts Shell : `install`, `remove`, `upgrade`, `backup` et `restore`. -Ces scripts seront exécutés en tant qu’`admin` sur les serveurs YunoHost. +Un paquet YunoHost doit contenir cinq scripts Shell : `install`, `remove`, `upgrade`, `backup` et `restore`. Un 6ème script `change_url` peut aussi être ajouté de façon optionnelle +Ces scripts seront exécutés en tant que `root` sur les serveurs YunoHost. -Voici un exemple de script d’`install` : -```bash -# Retrieve arguments -domain=$1 -path=$2 - -# Check domain/path availability -sudo yunohost app checkurl $domain$path -a roundcube -if [[ ! $? -eq 0 ]]; then - exit 1 -fi - -# Generate random DES key & password -deskey=$(dd if=/dev/urandom bs=1 count=200 2> /dev/null | tr -c -d '[A-Za-z0-9]' | sed -n 's/\(.\{24\}\).*/\1/p') -db_pwd=$(dd if=/dev/urandom bs=1 count=200 2> /dev/null | tr -c -d '[A-Za-z0-9]' | sed -n 's/\(.\{24\}\).*/\1/p') - -# Use 'roundcube' as database name and user -db_user=roundcube - -# Initialize database and store mysql password for upgrade -sudo yunohost app initdb $db_user -p $db_pwd -s $(readlink -e ../sources/SQL/mysql.initial.sql) -sudo yunohost app setting roundcube mysqlpwd -v $db_pwd - -# Copy files to the right place -final_path=/var/www/roundcube -sudo mkdir -p $final_path -sudo cp -a ../sources/* $final_path -sudo cp ../conf/main.inc.php $final_path/config/ -sudo cp ../conf/db.inc.php $final_path/config/ -sudo mv $final_path/plugins/managesieve/config.inc.php.dist $final_path/plugins/managesieve/config.inc.php - -# Change variables in Roundcube configuration -sudo sed -i "s/rcmail-ynhDESkeyTOchange/$deskey/g" $final_path/config/main.inc.php -sudo sed -i "s/yunouser/$db_user/g" $final_path/config/db.inc.php -sudo sed -i "s/yunopass/$db_pwd/g" $final_path/config/db.inc.php -sudo sed -i "s/yunobase/$db_user/g" $final_path/config/db.inc.php - -# Set permissions to roundcube directory -sudo chown -R www-data: $final_path - -# Modify Nginx configuration file and copy it to Nginx conf directory -sed -i "s@PATHTOCHANGE@$path@g" ../conf/nginx.conf -sed -i "s@ALIASTOCHANGE@$final_path/@g" ../conf/nginx.conf -sudo cp ../conf/nginx.conf /etc/nginx/conf.d/$domain.d/roundcube.conf - -# Reload Nginx and regenerate SSOwat conf -sudo service nginx reload -sudo yunohost app ssowatconf -``` +Des exemples de ces scripts sont disponibles dans l'[application d'exemple](https://github.com/YunoHost/example_ynh/tree/master/scripts) ### Utilisation Vous devez tout mettre dans le script d’`install` pour que votre application soit entièrement installée. Cela signifie que vous devez installer les dépendances, créer les répertoires requis, initialiser les bases de données nécessaires, copier les sources et configurer tout dans l’unique script `install` (et bien sûr faire la procédure inverse dans le script `remove`). -**Attention** : pour des raisons de sécurité, le script est exécuté en tant qu’**admin** dans YunoHost. Assurez-vous de l’essayer en tant qu’**admin** et de préfixer `sudo` aux commandes requises. \ No newline at end of file +Il est possible d'utiliser des helpers et d'importer une librairie de fonction par exemple depuis un fichier `_common.sh`. + +### Variables disponibles pour tous ces scripts +#### YNH_CWD +Cette variable contient le chemin du répertoire de travail courant du contexte d'execution du script. Elle peut être utile pour retrouver le chemin initial si on s'est déplacé pendant l'execution du script. Elle est utilisée par certains helpers pour être sûr d'utiliser le bon. + +#### YNH_APP_ID +Contient l'identifiant de l'application sans le numéro d'instance + +Exemple: strut +#### YNH_APP_INSTANCE_NAME +Contient le nom d'instance qui sera utilisé dans de nombreuses situation pour pouvoir gérer l'installation multiple d'une même app. + +Exemple: strut__3 +#### YNH_APP_INSTANCE_NUMBER +Contient le numero de l'instance. Attention il ne s'agit pas forcément du nombre d'instance toujours installée, car une ancienne application peut avoir été désinstallée. + +Exemple: 3 + +### Variables spécifiques pour `install` +#### YNH_APP_ARG_XXXXXXX +Pour chaque question posée dans lors de l'installation une variable d'environnement est disponible. + +Par exemple, si dans le manifest nous avons une question de cette forme +``` +{ + "name": "domain", + "type": "domain", + "ask": { + "en": "Choose a domain for OpenSondage", + "fr": "Choisissez un nom de domaine pour OpenSondage", + "de": "Wählen Sie bitte einen Domain für OpenSondage" + }, + "example": "domain.org" +}, +``` + +Le nom de la question `domain` donc dans le script on peut accéder à cette variable via $YNH_APP_ARG_DOMAIN. L'usage est de créer une variable plus courte comme ceci: + +``` +domain=$YNH_APP_ARG_DOMAIN +``` + +### Variables spécifiques pour `change_url` +#### YNH_APP_OLD_DOMAIN +L'ancien domaine où était installée l'app. +#### YNH_APP_OLD_PATH +L'ancien chemin où était installée l'app; +#### YNH_APP_NEW_DOMAIN +Le nouveau domaine où doit être installée l'app. +#### YNH_APP_NEW_PATH +Le nouveau chemin où doit être installée l'app. +