Créer le paquet Pétrolette pour Yunohost

J’ai récemment découvert comment créer un paquet YunoHost avec l’application Whitebophir (présenté ici même. Suite à la dépêche sur Pétrolette et voyant dans les commentaires une demande pour un paquet YunoHost, je me dis que c’est l’occasion.

Sommaire

• Présentation de Yunohost
• Installation de Pétrolette en local
• Création du paquet YunoHost
  • L’architecture
  • manifest.json
  • Le dossier de configuration
  • Les scripts
• Ajout au catalogue
• L’intégration continue

Présentation de Yunohost

Le projet YunoHost a déjà été présenté plusieurs fois sur linuxfr mais pour rappel :

YunoHost est un système d’exploitation qui vise à simplifier autant que possible l’administration d’un serveur pour ainsi démocratiser l’auto-hébergement tout en restant fiable, sécurisé, éthique et léger. C’est un projet de logiciel libre maintenu exclusivement par des bénévoles. Techniquement, il peut être vu comme une distribution basée sur Debian GNU/Linux et peut s’installer sur de nombreux types de matériel.

Installation de Pétrolette en local

Dans un premier temps, on vérifie comment s’installe l’application ciblée et quelles sont les possibilités d’installation. Il faut notamment savoir s’il est possible de :

• configurer le/les ports de l’application ;
• installer l’application sur un sous chemin du domaine ;
• installer plusieurs instances de l’application sur la même machine ; 
• s’installer derrière l’authentification de YunoHost.

Dans notre cas, l’application n’a aucun système d’authentification et peut donc se mettre facilement derrière le portail captif de YunoHost. En revanche, on ne peut pas installer l’application dans un sous-répertoire du domaine ni choisir le port de l’application. Ce dernier point empêche donc aussi l’installation de plusieurs instances. Heureusement, une pull request rapidement acceptée corrige ce dernier point.

Création du paquet YunoHost

YunoHost propose une documentation plutôt bien fournie pour créer un nouveau paquet. Un dépôt d’exemple est aussi disponible comme base de travail.

L’architecture

Un paquet YunoHost est une collection de scripts bash associés à des templates de configuration suivant une architecture bien définie. À la racine, un fichier manifest.json, un dossier scripts et un dossier de configuration. Un dossier sources peut être ajouté contenant d’éventuels correctif mais n’est pas utile dans notre cas.

├── check_process
├── conf
│   ├── app.src
│   ├── nginx.conf
│   └── systemd.service
├── issue_template
├── LICENSE
├── manifest.json
├── README_fr.md
├── README.md
└── scripts
    ├── backup
    ├── _common.sh
    ├── install
    ├── remove
    ├── restore
    └── upgrade

manifest.json

C’est la définition du paquet, il comprend les informations comme le nom, la description et la licence de l’application ainsi que les informations demandées lors de l’installation.

Dans notre cas, l’application ne s’installe qu’à la racine d’un domaine, donc on demande simplement le domaine où installer l’application et si celle-ci doit être accessible publiquement.

{
    "name": "Petrolette",
    "id": "petrolette",
    "packaging_format": 1,
    "description": {
        "en": "The news reader that doesn't know you",
        "fr": "La page d'actu qui ne sait rien de toi"
    },
    "url": "https://framagit.org/yphil/petrolette",
    "version": "1.2.5~ynh1",
    "license": "GPL-3.0-only",
    "maintainer": [{
        "name": "oiseauroch.",
        "email": "xxx@xx.xx"
    }],
    "requirements": {
        "yunohost": ">= 4.1.0"
    },
    "multi_instance": true,
    "services": [
        "nginx"
    ],
    "arguments": {
        "install" : [
            {
                "name": "domain",
                "type": "domain",
                "example": "domain.org"
            },
            {
                "name": "is_public",
                "type": "boolean",
                "default": true,
                "help" : {
                    "fr" : "Cette page sera accessible par n'importe qui. En revanche, la configuration reste personnelle",
                    "en" : "The page will be accessible by anyone."
                }
            }
        ]
    }
}

Le dossier de configuration

Celui-ci contient au moins un fichier app.src contenant l’adresse et le checksum de l’application. Il contient aussi les templates de configuration. YunoHost utilise nginx comme reverse-proxy et DBus pour le lancement des applications. Il faut donc au minimum un template pour nginx et un pour systemd.

Les scripts

Écrits en bash, les scripts permettent d’effectuer les opérations (installation, suppression, sauvegarde…) sur l’application. Afin de simplifier la vie du mainteneur et de normaliser ces opérations, YunoHost mets à disposition de nombreux helper.

Pour notre script install par exemple, on va dans un premier temps sourcer notre helper ainsi que ceux de YunoHost et s’assurer de retourner dans un état stable en cas d’erreur.

source _common.sh
source /usr/share/yunohost/helpers

# Exit if an error occurs during the execution of the script
ynh_abort_if_errors

Ensuite, on récupère les arguments du manifest. Ceux-ci sont nommés par convention $YNH_APP_ARG_NOM-DANS-LE-MANIFEST. On définit aussi le chemin de l’application pour l’instant en dur étant donné qu’il ne peut s'installer qu’à la racine. Les variables domaine, is_public, app et path_url sont aussi des conventions qu’il convient de respecter parce qu’elles sont recherchées par défaut dans certains helpers.

domain=$YNH_APP_ARG_DOMAIN
is_public=$YNH_APP_ARG_IS_PUBLIC
app=$YNH_APP_INSTANCE_NAME

path_url="/"

Vient après la définition du dossier de l’application appelé final_path lui aussi par convention. YunoHost m’indique que pour une application possédant un serveur web, le chemin est par défaut /opt/yunohost/$app. Cette opération étant la première à pouvoir prendre du temps, on indique un message de log qui sera visible pendant d’installation.

ynh_script_progression --message="Validating installation parameters..."

final_path=/opt/yunohost/$app
test ! -e "$final_path" || ynh_die --message="This path already contains a folder"

# Register (book) web path
ynh_webpath_register --app=$app --domain=$domain --path_url=$path_url

Yunohost stocke les informations d’installation des applications dans le dossier /home/yunohost.conf sous forme de yaml. Bien entendu, on n’édite pas nous-mêmes ces fichiers, mais on passe par d’autres helpers.

ynh_script_progression --message="Storing installation settings..."

ynh_app_setting_set --app=$app --key=domain --value=$domain
ynh_app_setting_set --app=$app --key=path_url --value=$path_url

YunoHost utilise un utilisateur différent pour chaque app installée, créons-le.

# Create a system user
ynh_system_user_create --username=$app --home_dir=$final_path

Viennent les parties plus spécifiques à notre application. Notre application utilise son propre serveur web, donc on cherche un port disponible (deux dans notre cas) puis on installe les dépendances. Pétrolette se base sur nodejs qui est une dépendance fréquente. YunoHost propose donc un helper spécifique pour gérer les différentes versions de node et appeler la bonne pour chaque application.

# Find an available port
port=$(ynh_find_port --port=8001)
https_port=$(ynh_find_port --port=8002)
ynh_app_setting_set --app=$app --key=port --value=$port
ynh_app_setting_set --app=$app --key=https_port --value=$https_port

ynh_install_nodejs --nodejs_version=$NODEJS_VERSION

Nous en sommes à l’installation proprement dite. Pétrolette utilise bower qui stocke des informations dans le répertoire de l’utilisateur courant. L’installation étant réalisée en root, il faut changer son répertoire pour stocker ces informations dans le répertoire de l’application.

ynh_app_setting_set --app=$app --key=final_path --value=$final_path
ynh_setup_source --dest_dir="$final_path"

pushd $final_path
# use custom home value to avoid bower storing values in root and have right errors
    TMP_HOME=$HOME
    HOME=$(pwd)
    ynh_use_nodejs
    ynh_npm install 
    HOME=$TMP_HOME
popd

chown -R $app:$app $final_path
chmod -R o-rwx $final_path

Pour finir, on s’occupe de l’intégration à YunoHost. On applique le template de Nginx et D-bus et on l’intègre au portail captif. C’est là qu’on est heureux d’avoir respecté les conventions pour les noms de variables, on a ainsi qu’à lister nos variables spécifiques à remplacer.

ynh_add_nginx_config 

yunohost service add $app --description="The news reader that doesn't know you" --log="/home/yunohost.app/${app}/storage/logs/petrolette.log"

ynh_add_systemd_config  --others_var="port ynh_node_load_PATH"

ynh_systemd_action --service_name=$app --action=start --log_path=systemd 

if [ $is_public -eq 1 ]
then
    # unprotected_uris allows SSO credentials to be passed anyway.
    ynh_permission_update --permission="main" --add="visitors"
fi

ynh_systemd_action --service_name=nginx --action=reload

Notre script est terminé. Les autres scripts suivent le même principe. On remarque que, dans notre cas, une grande partie de notre script est générique. On se dit donc qu’une bonne partie est encore automatisable mais toutes les applications ne sont pas aussi simples à installer et le projet s’améliore continuellement sur ce point.

Ajout au catalogue

Maintenant que notre paquet est fait, il serait bon qu’il apparaisse dans la liste de YunoHost. Pour cela, on lance une pull request sur le dépôt yunohost/apps avec les informations concernant notre application. On peut aussi demander à intégrer notre application à l’organisation YunoHost-Apps.

    "Petrolette": {
        "branch": "master",
        "revision": "HEAD",
        "url": "https://github.com/YunoHost-Apps/petrolette_ynh",
        "state": "working"
    }

L’intégration continue

Afin d’assurer une certaine qualité des applications, YunoHost a mis en place un système d’intégration continue. Celui-ci teste un certain nombre de scénarios : (installation, suppression, sauvegarde, restauration, installation dans un sous-dossier…) pour valider le bon fonctionnement de notre application. Cependant, certaines applications ne supportent pas tous les tests lancés par l’intégration continue. On écrit donc un fichier check_process qui spécifie quels tests doivent être effectués.

Voici notre liste de tests :

;; Test complet
    ; Checks
        pkg_linter=1
        setup_sub_dir=0
        setup_root=1
        setup_nourl=0
        setup_private=1
        setup_public=1
        upgrade=1
        backup_restore=1
        multi_instance=1
        port_already_use=0
        change_url=0

Une intégration continue de test est disponible et peut être lancée via un commentaire !testme dans une pull request. L’intégration continue de production est quant à elle automatiquement lancée et mise à jour le vendredi.

Aller plus loin

• Yunohost (45 clics)
• Une précédente dépèche sur Yunohost (12 clics)
• Paquet Yunohost de Pétrolette (39 clics)
• Pétrolette (129 clics)
• Documentation de Yunohost (19 clics)
• application d'exemple (22 clics)