doc/packaging_apps_helpers_fr.md

Packaging d’application

Commandes pratiques en Shell

À partir de YunoHost 2.4, de nouvelles commandes pratiques (helpers) en shell sont disponible pour faciliter le packaging, particulièrement pour des tâches répétitives comme la génération de mot de passe, la création de base de donnés MySQL…

Des exemples sont disponibles dans l’application d’exemple. Il est conseillé d’utiliser les commandes pratiques.

Vous pourrez les retrouver dans ce dépôt.

Pour pouvoir utiliser les helpers, il faudra ajouter les lignes suivantes au début des scripts shell :

# Source app helpers
. /usr/share/yunohost/helpers

Le script helpers va exécuter tout les scripts présent dans helpers.d et donc charger les fonctions des helpers. Afin qu'elles puissent être appelées simplement.

Liste non exhaustive des helpers disponibles:

Base de données:

ynh_mysql_execute_as_root SQL DB

Cette commande exécute la commande SQL SQL sur la base de donnée DB avec les droit de l'utilisateur root de mysql.

ynh_mysql_execute_file_as_root FILE DB

Cette commande éxecute un ensemble de commande SQL contenu dans le fichier FILE sur la base de donnée DB avec les droit de l'utilisateur root de mysql.

ynh_mysql_create_db DB USER PWD

Cette commande créer la base de donnée DB et l'utilisateur USER qui a comme mot de passe PWD.
L'utilisateur créé dispose de droits administrateur sur cette seule base de donnée.

ynh_mysql_drop_db DB

Cette commande supprime la base de donnée DB.

ynh_mysql_dump_db DB > ./FILE

Cette commande exporte la base de donnée DB dans le fichier FILE.

Gestion des paquets debian:

ynh_package_is_installed PACKAGE

Cette commande vérifie si le paquet PACKAGE est installé sur le système.
La sortie de la commande doit être testée pour en connaître le résultat.

ynh_package_is_installed "yunohost"
if [[ $? -eq 0 ]]; then
  echo "Le package est installé."
fi

ynh_package_version PACKAGE

Cette commande renvoie le numéro de version du paquet PACKAGE installé sur le système.

ynh_package_update

Cette commande met à jour la liste des applications disponible de façon silencieuse et non interactive.
C'est un apt-get update avec les options -y -qq et noninteractive.

ynh_package_install PACKAGE1 PACKAGE2

Cette commande installe les paquets PACKAGE1, PACKAGE2, etc de manière non interactive et silencieuse.
C'est un apt-get install avec les options -y -qq et noninteractive.

ynh_package_remove PACKAGE1 PACKAGE2

Cette commande supprime les paquets PACKAGE1, PACKAGE2, etc de manière non interactive et silencieuse.
C'est un apt-get remove avec les options -y -qq et noninteractive.

ynh_package_autoremove PACKAGE1 PACKAGE2

Cette commande supprime les paquets PACKAGE1, PACKAGE2, etc ainsi que leurs dépendances, si elles ne sont plus utilisées, de manière non interactive et silencieuse.
C'est un apt-get autoremove avec les options -y -qq et noninteractive.

Configuration des applications:

ynh_app_setting_set APP KEY VALUE

Cette commande permet de stocker le réglage nommé KEY dont la valeur est VALUE pour l'application APP , afin de le réutiliser plus tard (typiquement dans le script upgrade) ou pour que YunoHost puisse se configurer automatiquement (par exemple pour le SSO).
Les réglages sont stockés dans le fichier /etc/yunohost/apps/${APP}/settings.yml.
Par exemple, pour stocker le paramètre de visibilité, privé ou public, d'une application, on notera ainsi:

ynh_app_setting_set nom_app is_public "yes"

Le SSO fait appel aux réglages stockés pour l'application afin de déterminer si cette dernière peux être accessible publiquement ou non.
Pour cela, 6 key différents sont disponible:

Tout d'abord les key skipped_uris, unprotected_uris et protected_uris. Ces 3 key sont relatif au path de l'application.

Par exemple

ynh_app_setting_set nom_app skipped_uris "/"

concernera la racine de l'application. Soit https://domain.tld/path_app/ ainsi que tout ce qui suivra. Alors que

ynh_app_setting_set nom_app skipped_uris "/blog"

concernera le path /blog de l'application. Soit https://domain.tld/path_app/blog et ce qui suivra. Mais pas https://domain.tld/path_app/

skipped_uris
Une url ajoutée avec le key skipped_uris sera totalement ignorée par le SSO, donc l'accès sera publique et ne prendra pas en compte un utilisateur déjà connecté.

unprotected_uris
Une url ajoutée avec le key unprotected_uris sera accessible publiquement, mais un utilisateur connecté au SSO pourra se connecter en utilisant le header HTTP.

protected_uris
Une url ajoutée avec le key protected_uris sera bloquée par le SSO et accessible uniquement aux utilisateurs authentifiés.

Les key skipped_regex, unprotected_regex et protected_regex sont les équivalents en "expressions régulières" des 3 key précédentes

Il est important de noter que ce ne sont pas véritablement des expressions régulières qui seront interprétés, mais des patterns lua, dont la syntaxe différe légèrement.
Plus d'infos sur la syntaxe des patterns lua. Ainsi que quelques exemples.
Le pattern étant recherché sur l'ensemble des urls soumises, afin d'éviter des débordements on préfera ajouter au pattern l'url complète qui doit être prise en compte par ssowat. Par exemple, si on souhaite placer skipped_regex sur /blog en considérant une suite de chiffres indéfinie en argument. On indiquera ceci:

ynh_app_setting_set nom_app skipped_regex "$domain$path/blog%?%d+$"

Cela pose toutefois un éventuel problème, si les variables $domain ou $path contiennent un tiret (-), celui-ci sera interprété comme étant un caractère magique du pattern. Il faut donc échapper les éventuels tirets avec un %.

domainregex=$(echo "$domain" | sed 's/-/\%&/g')
pathregex=$(echo "$path" | sed 's/-/\%&/g')
ynh_app_setting_set nom_app skipped_regex "$domainregex$pathregex/blog%?%d+$"

ynh_app_setting_get APP KEY

Cette commande récupère le paramètre KEY stocké précémment pour l'application APP à l'aide de ynh_app_setting_set
Par exemple

is_public=$(ynh_app_setting_get nom_app is_public)

ynh_app_setting_delete APP KEY

Cette commande supprime le paramètre KEY enregistré pour l'application APP.

Gestion des utilisteurs:

ynh_user_exists USERNAME

Cette commande vérifie l'existence de l'utilisateur USERNAME dans Yunohost.
La sortie de la commande doit être testée pour en connaître le résultat.

ynh_user_exists "johndoe"
if [[ $? -eq 0 ]]; then
  echo "L'utilisateur existe."
fi

ynh_user_get_info USERNAME KEY

Cette commande récupère l'information KEY sur l'utilisateur USERNAME. Les informations pouvant être récupérés sur un utilisateur sont:

• firstname
• fullname
• lastname
• mail
• mail-aliases
• mailbox-quota
  Par exemple

mailadmin=$(ynh_user_get_info $admin mail)

ynh_system_user_exists USERNAME

Cette commande vérifie l'existence de l'utilisateur USERNAME sur le système.
La sortie de la commande doit être testée pour en connaître le résultat.

ynh_system_user_exists "www-data"
if [[ $? -eq 0 ]]; then
  echo "L'utilisateur existe sur le système."
fi

Autres commandes:

ynh_string_random LENGTH

Cette commande génère une chaine de caractères aléatoires de longueur LENGTH.

ynh_die MSG RETCODE

Cette commande affiche le message MSG sur stderr et exécute la commande exit avec le code de sortie RETCODE

sudo yunohost app checkport PORT

Cette commande vérifie le PORT et retourne une erreur si il est déjà utilisé.
La sortie de la commande doit être testée pour en connaître le résultat.

port=PORT_PAR_DEFAUT
sudo yunohost app checkport $port
while [[ ! $? -eq 0 ]]; do
    port=$((port+1))
    sudo yunohost app checkport $port
done

sudo yunohost app checkurl DOMAINPATH -a APP

Cette commande vérifie la disponibilité du chemin DOMAIN/PATH. Il est utile pour les applications web et vous permet d’être sûr que le chemin n’est pas utilisé par une autre application. Si le chemin est inutilisé, elle le « réserve » pour l'application APP.

Remarque : ne pas préfixer par http:// ou par https:// dans le DOMAINPATH.

sudo yunohost app ssowatconf

Cette commande régénère la configuration du SSO. Elle est appelée automatiquement à la fin du script.
Mais peux être appelée avant si nécessaire.