YunoHost/doc
1
0
Fork 0
mirror of https://github.com/YunoHost/doc.git synced 2024-09-03 20:06:26 +02:00
Code Issues Projects Releases Packages Wiki Activity

[enh] List variable for hooks and script to manage apps (#538)

Browse source 
* [enh] List variable for hooks and script to manage apps
* Ajoute un lien sur pour les variables
This commit is contained in:
ljf (zamentur) 2017-09-20 09:22:23 +02:00 committed by Alexandre Aubin
parent e4ea5c918d
commit 000f918fef
3 changed files with 128 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
packaging_apps_hooks_fr.md
View file

@ -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

109
packaging_apps_scripts.md
View file

@ -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.
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.

108
packaging_apps_scripts_fr.md
View file

@ -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.
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.