diff --git a/architecture.png b/architecture.png new file mode 100644 index 00000000..12c1f471 Binary files /dev/null and b/architecture.png differ diff --git a/architecture.xml b/architecture.xml new file mode 100644 index 00000000..b1084892 --- /dev/null +++ b/architecture.xml @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/contribs_fr.md b/contribs_fr.md index a5b78c61..4dcc6df2 100644 --- a/contribs_fr.md +++ b/contribs_fr.md @@ -2,21 +2,54 @@ Liste non exhaustive des principaux contributeurs : -* kload +#### Fondateurs +* kload * beudbeud +#### Conseil + +* Bram +* ju +* ljf +* Maniack +* Moul +* opi +* Théodore + +#### Groupe Core Dev + +* AlexAubin +* Bram +* Ju +* ljf +* Moul +* opi + +#### Groupe Apps + +* Bram +* Ju +* ljf +* Maniack C +* Moul +* Scith +* Tostaki + +#### Groupe Communication + +* Bram +* Moul +* ljf +* opi +* Théodore +* Jean-Baptiste + +#### Groupe Distribution +* Heyyounow + +#### Autres contributeurs * jerome : développeur de la [Moulinette](moulinette_fr) - -* opi : développeur de l’[interface d’admininstation web](admin_fr) - -* ju : applications - -* Moul : - * Documentation - * Cubieboard - * moul[at]moul.re - * courgette : design - -* titoko \ No newline at end of file +* titoko +* Genma diff --git a/packaging_apps_fr.md b/packaging_apps_fr.md index bbfad997..e61519cd 100644 --- a/packaging_apps_fr.md +++ b/packaging_apps_fr.md @@ -8,6 +8,8 @@ Pour packager une application, voici les prérequis : * Maîtriser un minimum `git`, le Shell et d’autres notions de programmation ; * Une [machine virtuelle ou sur un serveur distant](/install_fr) ou un [environnement de développement](https://github.com/yunohost/ynh-dev) pour packager et tester son paquet. +Si vous ne comprenez pas ces prérequis, ou si vous ne savez pas comment écrire du code, consulter d'abord l'[introduction au packaging](/packaging_apps_start_fr). + ### Contenu Un paquet YunoHost est composé : diff --git a/packaging_apps_guidelines_fr.md b/packaging_apps_guidelines_fr.md index c8a8ac29..6c07277d 100644 --- a/packaging_apps_guidelines_fr.md +++ b/packaging_apps_guidelines_fr.md @@ -3,7 +3,7 @@
Cette page est en cours d'élaboration. Tant que cet avertissement n'est pas enlevé. Considérez ces informations comme potentiellement fausse. -Le nom YEP n'est à priori pas définitif, ni les niveaux, ni les bonnes pratiques en elle même. +Le nom YEP n'est à priori pas définitif, ni les niveaux, ni les bonnes pratiques en elle-même.
@@ -13,15 +13,15 @@ Ce document a pour but de lister les différentes bonnes pratiques concernant la Chaque bonne pratique est numérotée avec un numéro suffixé par les lettres YEP (YunoHost Enhancement Proposals), ceci afin de pouvoir y faire référence facilement dans les outils d'analyse automatique de paquet ([package checker](https://github.com/YunoHost/package_check), [package linter](https://github.com/YunoHost/package_linter)), mais également lors des revues de code. Chaque YEP est associée à : -* un status indiquant si la régle a été validé ou si elle fait encore l'objet de discussion (brouillon, validé, refusé, obsolète) ; +* un statut indiquant si la règle a été validé ou si elle fait encore l'objet de discussion (brouillon, validé, refusé, obsolète) ; * une indication sur le type de test à mener (manuel ou auto si un outil automatique peut vérifier) ; * une indication du niveau d'app à partir duquel la règle est nécessaire (NOTWORKING, INPROGRESS, WORKING, OFFICIAL), certaines règles sont optionnelles ; ### Index des YEP -| ID | Titre | Status | Test | Niveau | +| ID | Titre | Statut | Test | Niveau | |----|--------|--------|------|--------| | **YEP 1** | **Communiquer avec la communauté** | | | | -| YEP 1.1 | Nommer son app et son dépot | validé | manuel | NOTWORKING | +| YEP 1.1 | Nommer son app et son dépôt | validé | manuel | NOTWORKING | | YEP 1.2 | Inscrire l'app sur un "répertoire" connu | validé | manuel | NOTWORKING | | YEP 1.3 | Indiquer la licence associée au paquet | validé | AUTO | WORKING | | YEP 1.4 | Informer sur l'intention de maintenir un paquet | brouillon | manuel | OFFICIAL | @@ -33,7 +33,7 @@ Chaque YEP est associée à : | YEP 1.10 | Garder un historique de version propre | brouillon | manuel | OFFICIAL | | YEP 1.11 | Ajouter l'app au [bugtracker YunoHost](https://dev.yunohost.org) | brouillon | manuel | OFFICIAL | | | | | | | -| **YEP 2** | **Stabiliser une app** | | | | +| **YEP 2** | **Stabiliser une app** | **Statut** | **Test** | **Niveau** | | YEP 2.1 | Respecter le format du manifeste | validé | auto | INPROGRESS | | YEP 2.2 | Utiliser bash pour les scripts principaux | validé | auto | WORKING | | YEP 2.3 | Sauvegarder les réponses lors de l'installation | validé | manuel | WORKING | @@ -46,28 +46,28 @@ Chaque YEP est associée à : | YEP 2.10 | Configurer les logs de l'application | brouillon | manuel | WORKING | | YEP 2.11 | Utiliser une variable plutôt que l'app id directement | validé | manuel | OFFICIAL | | YEP 2.12 | Utiliser les commandes pratiques (helpers) | validé | auto | OFFICIAL | -| YEP 2.13 | Traduire le package en anglais | brouillon | manuel | OFFICIAL | +| YEP 2.13 | Traduire le paquet en anglais | brouillon | manuel | OFFICIAL | | YEP 2.14 | Remplir correctement un fichier de conf | brouillon | manuel | OFFICIAL | -| YEP 2.15 | Vérifier les paramètres saisies par l'utilisateur | validé | manuel | OFFICIAL | +| YEP 2.15 | Suivre les instructions d'installation de l'application | validé | manuel | OFFICIAL | | YEP 2.16 | Vérifier la disponibilité des dépendances sur ARM, x86 et x64 | validé | manuel | OFFICIAL | | YEP 2.17 | Prendre en compte la version d'origine lors des mises à jour | validé | manuel | OFFICIAL | | | | | | | -| **YEP 2.18** | **Stabiliser une webapp** | | | | +| **YEP 2.18** | **Stabiliser une webapp** | **Statut** | **Test** | **Niveau** | | YEP 2.18.1 | Lancer le script d'installation d'une webapp correctement | validé | manuel | WORKING | -| YEP 2.18.2 | Supporter l'installation sur un domaine | validé | auto | WORKING | -| YEP 2.18.3 | Supporter l'installation sur un sous-domaine | validé | auto | WORKING | -| YEP 2.18.4 | Supporter l'installation sur un sous-dossier | validé | auto | OFFICIAL | -| YEP 2.18.5 | Ajouter la tuile YunoHost pour naviguer facilement entre les applications | validé | manuel | OFFICIAL | +| YEP 2.18.2 | Gérer l'installation à la racine d’un nom de domaine | validé | auto | WORKING | +| YEP 2.18.3 | Gérer l'installation sur un sous-domaine | validé | auto | WORKING | +| YEP 2.18.4 | Gérer l'installation sur un chemin `/path` | validé | auto | OFFICIAL | +| YEP 2.18.5 | Gérer la tuile YunoHost pour faciliter la navigation entre les applications | validé | manuel | OFFICIAL | | | | | | | -| **YEP 3** | **Sécuriser une app** | | | | +| **YEP 3** | **Sécuriser une app** | **Statut** | **Test** | **Niveau** | | YEP 3.1 | Ne pas demander ou stocker de mot de passe LDAP | brouillon | manuel | NOTWORKING | | YEP 3.2 | Ouvrir un port correctement | brouillon | manuel | WORKING | | YEP 3.3 | Faciliter le contrôle de l'intégrité des sources | brouillon | manuel | OFFICIAL | | YEP 3.4 | Isoler l'app | brouillon | manuel | OFFICIAL | -| YEP 3.5 | Suivre les recommendations de la documentation de l'app | validé | manuel | OFFICIAL | +| YEP 3.5 | Suivre les recommandations de la documentation de l'app | validé | manuel | OFFICIAL | | YEP 3.6 | Mettre à jour les versions contenant des CVE | draft | manuel | OFFICIAL | | | | | | | -| **YEP 4** | **Intégrer une app** | | | | +| **YEP 4** | **Intégrer une app** | **Statut** | **Test** | **Niveau** | | 4.1 | Lier au ldap | validé | manuel | OFFICIAL | | YEP 4.2 | Lier l'authentification au sso | validé | manuel | OFFICIAL | | YEP 4.2.1 | Déconnexion | validé | manuel | OFFICIAL | @@ -82,100 +82,270 @@ Chaque YEP est associée à : ### YEP 1 - Communiquer avec la communauté La YEP 1 est une meta YEP, elle explique ce qu'il faut faire pour échanger avec la communauté autour d'un paquet d'application YunoHost. -#### YEP 1.1 - Nommer son app et son dépot | validé | manuel | NOTWORKING | -Chaque application YunoHost possède un id inscrit dans le manifest de l'application. +#### YEP 1.1 - Nommer son app et son dépôt | validé | manuel | NOTWORKING | +Chaque application YunoHost possède un id inscrit dans le manifeste de l'application. Cet identifiant doit être unique entre chaque paquet d'application. Il est donc recommandé de vérifier sa disponibilité en consultant la liste des applications référencées dans les dépôts d'applications connus (official, community, internetcube). -De plus l'identifiant doit respecter l'expression régulière suivante `^[a-z1-9]((_|-)?[a-z1-9])+$` . Autrement dit, il doit respecter les règles suivantes : +De plus l'identifiant doit respecter l'expression régulière suivante `^[a-z1-9]((_|-)?[a-z1-9])+$`. Autrement dit, il doit respecter les règles suivantes : * être en minuscule * commencer par une lettre ou un chiffre -* être alphanumerique (le underscore est autorisé) -* ne pas contenir 2 underscores ou tirets qui se suivent +* être alphanumérique (le underscore est autorisé) +* ne pas contenir deux underscores ou tirets qui se suivent * ne pas terminer par un underscore ou un tiret -Pour les noms d'applications contenant des espaces la quasitotalité des paquets actuels les retirent simplement sans les remplacer par des tirets ou underscores. +Pour les noms d'applications contenant des espaces la quasi-totalité des paquets actuels les retirent simplement sans les remplacer par des tirets ou underscores. -Par convention, les dépôts d'applications YunoHost sont toujours nommés de leur ID suivis de la chaine de caractère "\_ynh". Ainsi on peut distinguer le dépôt upstream de l'application, du dépôt du package yunohost. Cette notation permet également de trouver des applications non répertoriés à travers les moteurs de recherche des plateformes proposant des gestionnaire de version (github par exemple). +Par convention, les dépôts d'applications YunoHost sont toujours nommés de leur ID suivis de la chaîne de caractère "\_ynh". Ainsi on peut distinguer le dépôt upstream de l'application, du dépôt du paquet yunohost. Cette notation permet également de trouver des applications non répertoriées à travers les moteurs de recherche des plateformes proposant des gestionnaires de version (GitHub par exemple). Exemple : ID : exemple Nom de dépôt : exemple_ynh -#### YEP 1.2 - Inscrire l'app sur un "répertoire" connu | validé | manuel | NOTWORKING | -Il est conseillé dés le début du packaging d'inscrire une app sur un des dépôts d'application YunoHost. +#### YEP 1.2 - Inscrire l'app sur un « répertoire » connu | validé | manuel | NOTWORKING | +Il est conseillé dès le début du packaging d'inscrire une app sur un des dépôts d'application YunoHost. Ces dépôts ont plusieurs fonctions : * communiquer l'existence d'un paquet ; -* indiquer la dernière version associée au paquet (afin de permetre à la mise à jour de l'app par YunoHost) ; +* indiquer la dernière version associée au paquet (afin de permettre à la mise à jour de l'app par YunoHost) ; * indiquer l'état de fonctionnement du paquet ; * indiquer des informations sur le support d'un paquet. -
- -TODO Lien ou information pour réaliser l'inscription. - -
+Pour les listes `official.json` et `community.json`, l'inscription se fait sur [le dépôt git "apps"](https://github.com/YunoHost/apps). + +#### YEP 1.3 - Indiquer la licence associée au paquet | brouillon | AUTO | WORKING | +La licence du paquet est à indiquer dans un fichier `LICENSE` à la racine du paquet. Attention à ne pas confondre avec la licence de l'application qui va être installée dont l'acronyme est à renseigner dans le champ `license` du manifeste. + +Les listes d'applications official.json et community.json n'acceptent que les paquets dont la licence est libre, de même pour la licence de l'application contenue. Certaines applications libres nécessitent des dépendances non-libres (exemple: mp3, drivers, etc.). Dans ce cas, il faut ajouter `&dep-non-free` à l'acronyme et si possible donner des précisions dans le README.md du paquet, l'intégration sera dans ce cas acceptée au cas par cas. + +Dans le futur, YunoHost affichera sans doute des détails sur la licence de l'application. Pour y parvenir, l'acronyme doit être celui issu de cette [liste de licences répertoriées du SPDX](https://spdx.org/licenses/) (si il y a 2 acronymes, il faut prendre celui contenant le numéro de version). Pour plus de cohérence, la casse doit être respectée. + +Si la licence n'est pas présente dans la liste, dans ce cas il faut indiquer `free` ou `non-free` selon qu'elle est libre ou non et donner l'occasion à l'utilisateur de se renseigner dans le README.md (lien, explications, ...). + +Exemple: pour une licence `GNU Lesser General Public License (LGPL), version 3` l'acronyme est `LGPL-3.0` si toutefois des dépendances non libres sont utilisées dans ce cas il faudra mettre `LGPL-3.0&dep-non-free` dans le manifeste. + +Si une application a des modules liés avec une autre licence (Exemple: Odoo 9 LGPL-3.0 + un module sous licence AGPL-3.0 ), dans ce cas on indiquera les deux licences séparées par un `&`. + +Si deux applications distinctes sont dans le même paquet d'installation et ont des licences distinctes, dans ce cas on peut utiliser le `,` pour séparer les licences. + +Dans les deux cas, le mainteneur est encouragé à réfléchir à la possibilité de créer deux paquets distincts. Le manifeste de chaque application permet de poser des questions de type `app` de façon à faire référence à une autre application déjà installée. + +Rappel: une question de type `app` prend pour réponse l'identifiant d'une des apps déjà installée. + +Quelques liens intéressants pour aider au choix de licence: +* [Des fiches explicatives sur les licences libres](https://www.inria.fr/content/download/5896/48452/version/2/file/INRIA_recueil_fiches_licences_libres_vf.pdf) +* [La documentation sur les licences du projet GNU](https://www.gnu.org/licenses/licenses.fr.html) +* [Un guide du projet GNU pour aider au choix d'une licence](https://www.gnu.org/licenses/license-recommendations.fr.html) -#### YEP 1.3 - Indiquer la licence associée au paquet | validé | AUTO | WORKING | #### YEP 1.4 - Informer sur l'intention de maintenir un paquet | brouillon | manuel | OFFICIAL | Le mainteneur de l'application doit s'engager à maintenir son app sur la durée si il souhaite que celle-ci rejoigne la liste des applications officielles. Cela implique de surveiller les mises à jour de l'application upstream, de respecter les nouvelles règles de packaging et de répondre aux demandes des utilisateurs. #### YEP 1.5 - Mettre à jour régulièrement le statut de l'app | brouillon | manuel | WORKING | #### YEP 1.6 - Se tenir informé sur l'évolution du packaging d'apps | validé | manuel | OFFICIAL | +Afin de suivre l'évolution du format de packaging ainsi que des bonnes pratiques, il est recommandé de: +* s'inscrire à la liste de discussion `apps@list.yunohost.org` +* suivre [la catégorie Apps packaging du forum](https://forum.yunohost.org/c/apps-packaging) + +Pour suivre l'évolution de YunoHost de façon plus générale : +* rejoindre le salon XMPP dev@conference.yunohost.org ([trois jours de logs sont disponibles](https://im.yunohost.org/logs/dev/)) +* suivre [la catégorie Annoucement du forum](https://forum.yunohost.org/c/announcement) +* suivre les discussions sur contrib@list.yunohost.org + #### YEP 1.7 - Ajouter l'app à l'[organisation YunoHost-Apps](https://github.com/YunoHost-Apps) | validé | manuel | OFFICIAL | +L'ajout d'une app sur l'[organisation YunoHost-Apps](https://github.com/YunoHost-Apps) permet de faire connaitre l'apps auprès des autres contributeurs qui pourraient être tentés de packager l'application visée. + +C'est aussi un moyen pour permettre de déployer rapidement un correctif de sécurité si nécessaire dans le cas où le mainteneur ne serait pas disponible. + #### YEP 1.8 - Publier des demandes de test | validé | manuel | OFFICIAL | +Afin d'assurer le bon fonctionnement d'un paquet, il convient de publier une annonce afin d'ouvrir les tests sur le paquet. Cette annonce peut se faire sur le forum dans [la catégorie Apps du forum](https://forum.yunohost.org/c/apps). + +Il est recommandé d'indiquer si certains tests n'ont pas été menés. + +* Vérifier le package avec Package linter. +* Installation en sous-dossier. +* Installation à la racine d'un domaine ou d'un sous-domaine. +* Suppression, dans les 2 cas d'installations précédent. +* Accès à l'interface web de l'application, avec le / final dans l'adresse, et en l'omettant. +* Upgrade sur la même version du package. +* Upgrade depuis une ancienne version du package. +* Installation privée (sécurisée par le SSO). +* Installation publique. +* Installation multi-instance. +* Erreur de nom d'utilisateur. +* Erreur de nom de domaine. +* Path mal écrit (path/ au lieu de /path par exemple). +* Port déjà utilisé par une autre application. +* Source corrompue après téléchargement. +* Erreur de téléchargement de la source. +* Dossier déjà utilisé par une autre application. +* Backup et restore. + #### YEP 1.9 - Documenter l'app | validé | AUTO | OFFICIAL | +Avant tout, il convient de faire une description correcte de l'app dans le champ `description` du manifest. L'insertion de mot clé dans cette description peut être une bonne idée, dans la mesure où un utilisateur pourrait être amené à faire une recherche (CTRL+F) parmi toutes les applications. + +Il y a également le README.md, ce dernier doit et peut contenir : +* le nom de l'app +* un bref résumé de ce qu'elle fait +* des éventuels compléments d'installation si le script ne suffit pas lui-même +* des instructions pour l'utiliser (par exemple pour relier son smartphone ou son ordinateur) +* l'endroit pour signaler un dysfonctionnement / une demande +* la roadmap/TODO +* éventuellement les pré-requis en termes de mémoires ram, processeur etc. (certains équipements ont moins de 512Mo de ram) + #### YEP 1.10 - Garder un historique de version propre | brouillon | manuel | OFFICIAL | #### YEP 1.11 - Ajouter l'app au [bugtracker YunoHost](https://dev.yunohost.org) | brouillon | manuel | OFFICIAL | ### YEP 2 - Stabiliser une app #### YEP 2.1 - Respecter le format du manifeste | validé | auto | INPROGRESS | +Le manifeste permet de décrire une app afin que YunoHost puisse lui appliquer les bons traitements. Pour plus d'information voir la [documentation dédiée](https://yunohost.org/#/packaging_apps_manifest). + #### YEP 2.2 - Utiliser bash pour les scripts principaux | validé | auto | WORKING | Les scripts d'action (install, upgrade, remove, backup et restore) doivent être en bash afin que la cli/api yunohost puisse correctement les appeler. -Ceci étant rien n'empèche à l'intérieur de ces scripts de faire appel à d'autres scripts ou bibliothèques de fonction. Ceux ci ne sont pas obligés d'être en bash. +Ceci étant, rien n'empêche à l'intérieur de ces scripts de faire appel à d'autres scripts ou bibliothèques de fonction. Ceux-ci ne sont pas obligés d'être en bash. + +Cependant, il faudra porter une attention particulière à l'affichage correct des logs d'information, de warning, ou d'erreurs. Afin qu'un utilisateur de la cli/api yunohost puisse comprendre le fonctionnement du script venant d'être exécuté et au besoin réparer son instance YunoHost. -Cependant, il faudra porter une attention particulière à l'affichage correcte des logs d'information, de warning, ou d'erreurs. Afin qu'un utilisateur de la cli/api yunohost puisse comprendre le fonctionnement du script venant d'être executé et au besoin réparer son instance YunoHost. - #### YEP 2.3 - Sauvegarder les réponses lors de l'installation | validé | manuel | WORKING | Lors de l'installation, il est nécessaire de sauvegarder chaque réponse aux questions du manifeste. En effet, même si au début il n'est pas nécessaire d'écrire un script de mise à jour, par la suite ce sera sans doute le cas. Or, sans les informations initiales, la mise à jour peut être plus fastidieuse. #### YEP 2.4 - Détecter et gérer les erreurs | brouillon | manuel | WORKING | #### YEP 2.5 - Copier correctement des fichiers | brouillon | manuel | WORKING | #### YEP 2.6 - Annuler l'action si les valeurs d'entrées sont incorrectes | validé | manuel | WORKING | +Chaque script devrait vérifier que les valeurs d'entrées sont correctes. + +Voici quelques exemples : +* Vérifier que le nom de domaine existe +* Vérifier que l'utilisateur existe +* Vérifier que le chemin choisi est disponible + +Dans le cas où l'une des valeurs est incorrecte, il est alors nécessaire d'annuler toutes modifications réalisées préalablement sur l'instance. Le mieux étant de faire tous ces contrôles avant de modifier le système. + + #### YEP 2.7 - Donner des permissions suffisantes aux instructions bash | validé | auto | WORKING | +Certaines instructions nécessitent les droits sudo. Il faut dans ce cas ne pas oublier de préfixer ces instructions par `sudo `. + +Dans d'autres cas il est nécessaire de donner des droits à l'aide de chmod et de chown. + #### YEP 2.8 - Modifier correctement une configuration système | brouillon | manuel | WORKING | #### YEP 2.9 - Enlever toutes traces de l'app lors de la suppression | brouillon | manuel | WORKING | +À l’exception de dépendances (pax exemple : paquets Debian) utilisés par d’autres services ou applications. + #### YEP 2.10 - Configurer les logs de l'application | brouillon | manuel | WORKING | #### YEP 2.11 - Utiliser une variable plutôt que l'app id directement | validé | manuel | OFFICIAL | +Il est conseillé de rendre les scripts le plus générique possible, un bon moyen d'y parvenir est d'utiliser une variable pour le nom de l'app afin d'éviter qu'il se retrouve partout dans les scripts. Ainsi, un autre packageur pourra plus facilement se servir du script pour une autre app. + #### YEP 2.12 - Utiliser les commandes pratiques (helpers) | validé | auto | OFFICIAL | -#### YEP 2.13 - Traduire le package en anglais | brouillon | manuel | OFFICIAL | +Afin de simplifier le packaging, d'uniformiser les pratiques, d'éviter les erreurs et d'augmenter la durée de vie d'un script vis-à-vis des futures versions de YunoHost. Un ensemble de helpers permettant de faire de nombreuses actions est proposé. + +Pour plus d'informations : +* consulter [la documentation des helpers](https://yunohost.org/#/packaging_apps_helpers_fr) +* explorer [le répertoire des helpers](https://github.com/YunoHost/yunohost/tree/unstable/data/helpers.d) + +#### YEP 2.13 - Traduire le paquet en anglais | brouillon | manuel | OFFICIAL | #### YEP 2.14 - Remplir correctement un fichier de conf | brouillon | manuel | OFFICIAL | -#### YEP 2.15 - Vérifier les paramètres saisies par l'utilisateur | validé | manuel | OFFICIAL | +#### YEP 2.15 - Suivre les instructions d'installation de l'application | validé | manuel | OFFICIAL | + #### YEP 2.16 - Vérifier la disponibilité des dépendances sur ARM, x86 et x64 | validé | manuel | OFFICIAL | +YunoHost s'installe sur ARM, sur x86 et x64. Un paquet devrait donc être testé sur ces trois architectures processeur. + +Certains paquets ne sont pas disponibles sur ARM, il convient dans ce cas d'étudier d'autres solutions ou d'indiquer dans le README.md que l'application ne fonctionne pas sur ARM et de bloquer l’installation par détection du type d’architecture. + #### YEP 2.17 - Prendre en compte la version d'origine lors des mises à jour | validé | manuel | OFFICIAL | +Le script de mise à jour doit pouvoir fonctionner même si les mises à jour précédentes n'ont pas été effectuées. + +Ainsi, il doit être possible de faire des sauts de mise à jour d'une version N-x vers une version N. Pour ce faire il est conseillé d'enregistrer les numéros de version dans les settings de l'app. ### YEP 2.18 - Stabiliser une webapp +La majeure partie des applications YunoHost sont des web apps, mais certaines n'en sont pas. Les YEP 2.18.x développent certaines spécificités liées aux web app. + #### YEP 2.18.1 - Lancer le script d'installation d'une webapp correctement | validé | manuel | WORKING | -#### YEP 2.18.2 - Supporter l'installation sur un domaine | validé | auto | WORKING | -#### YEP 2.18.3 - Supporter l'installation sur un sous-domaine | validé | auto | WORKING | -#### YEP 2.18.4 - Supporter l'installation sur un sous-dossier | validé | auto | OFFICIAL | -#### YEP 2.18.5 - Ajouter la tuile YunoHost pour naviguer facilement entre les applications | validé | manuel | OFFICIAL | +Bien souvent une web app s'installe à partir de formulaires affichés sur une page web. Cette façon de faire, bien que pratique pour un humain, l'est moins pour un programme. + +Il convient donc de vérifier si l'application ne propose pas une solution d'installation en ligne de commande. + +Si ce n'est pas le cas, il convient d'utiliser l'option -H de curl. En effet, dans certains cas la redirection DNS pourrait ne pas être active au moment de l'installation. +``` +curl -kL -H "Host: $domain" --data "¶m1=Text1¶m2=text2" https://localhost$path/install.php > /dev/null 2>&1 +``` + +#### YEP 2.18.2 - Gérer l'installation à la racine d’un nom de domaine | validé | auto | WORKING | +Une web app devrait pouvoir s'installer à la racine d’un nom de domaine. + +#### YEP 2.18.3 - Gérer l'installation sur un sous-domaine | validé | auto | WORKING | +Une web app devraient pouvoir s'installer sur un sous-domaine directement sans sous dossiers. + +#### YEP 2.18.4 - Gérer l'installation sur un chemin `/path` | validé | auto | OFFICIAL | +Une web app devraient pouvoir s'installer sur un chemin `/path`. + +#### YEP 2.18.5 - Gérer la tuile YunoHost pour naviguer facilement entre les applications | validé | manuel | OFFICIAL | +Sauf dans de rare cas il est conseillé d'intégrer la tuile YunoHost qui permet de retourner sur le menu du SSO. Cette intégration se fait dans la configuration nginx. + +Certains utilisateurs ont remplacé ce carré par un script ajoutant un menu en haut de chaque webapp. ### YEP 3 - Sécuriser une app #### YEP 3.1 - Ne pas demander ou stocker de mot de passe LDAP | brouillon | manuel | NOTWORKING | #### YEP 3.2 - Ouvrir un port correctement | brouillon | manuel | WORKING | #### YEP 3.3 - Faciliter le contrôle de l'intégrité des sources | brouillon | manuel | OFFICIAL | #### YEP 3.4 - Isoler l'app | brouillon | manuel | OFFICIAL | -#### YEP 3.5 - Suivre les recommendations de la documentation de l'app | validé | manuel | OFFICIAL | +#### YEP 3.5 - Suivre les recommandations de la documentation de l'app | validé | manuel | OFFICIAL | +En général, une application propose une documentation afin d'aider les administrateurs systèmes à réaliser l'installation. Il est conseiller d'en suivre les recommandations, notamment celles concernant les permissions à accorder par fichier ou répertoire. + +Le mainteneur de paquet doit toutefois rester vigilant, certaines documentations pouvant être erronées ou insuffisante. + #### YEP 3.6 - Mettre à jour les versions contenant des CVE | draft | manuel | OFFICIAL | ### YEP 4 - Intégrer une app +Cette meta YEP traite de l'intégration d'une app avec l'environnement YunoHost. Une bonne intégration est en général un gage de qualité et de confort pour les utilisateurs. + #### YEP 4.2 - Lier l'authentification au sso | validé | manuel | OFFICIAL | +Le Single Sign On permet d'éviter d'avoir à créer les mêmes utilisateurs pour chaque app. Ainsi, un utilisateur YunoHost pourra se connecter via le Single Sign On à l'ensemble des apps. + +Pour se faire, il convient de lier son app au LDAP et/ou d'utiliser des hooks pour dupliquer les identifiants du compte dans la base de données de l'app. + +Une fois cette opération appliquée, le mainteneur peut utiliser l'instruction HTTP REMOTE_USER pour vérifier si un utilisateur est connecté ou non. En général, des modules existent (que ce soit au niveau de la technologie, du framework ou même de l'app elle-même). + +Au besoin, SSOwat permet de sécuriser l'accès à une ou plusieurs parties de l'app. Il peut ainsi être pertinent de sécuriser l'accès à une page d'administration avec le SSO plutôt qu'un `.htaccess` et de rendre le reste de l'app accessible à tous les visiteurs. + #### YEP 4.2.1 - Déconnexion | validé | manuel | OFFICIAL | +Lorsque l'on clique sur une action de déconnexion au sein de l'app, celle-ci devrait déconnecter l'utilisateur du SSO. Sinon, il y a un risque que l'utilisateur laisse par mégarde une session ouverte. + #### YEP 4.3 - Fournir un script de sauvegarde YunoHost fonctionnel | validé | auto | OFFICIAL | #### YEP 4.4 - Fournir un script de restauration YunoHost fonctionnel | validé | auto | OFFICIAL | #### YEP 4.5 - Utiliser les hooks | validé | manuel | OPTIONAL | -#### YEP 4.6 - Gère le multi-instance | validé | manuel | OPTIONAL | +YunoHost offre la possibilité de lancer des actions à chaque traitement effectué par la ligne de commande. Ceci peut être pratique dans de nombreux cas. + +Exemples : +* Ajouter/supprimer un utilisateur dans la base de données de l'app lorsque l'on utilise `yunohost user create` ou `yunohost user remove` +* Gérer l’ajout d'un nouveau nom de domaine lors de l'action `yunohost domain add` +* Lancer un script après que le pare-feu ait été rechargé + +Liste des hooks : +* post_domain_add +* post_domain_remove +* post_user_create +* post_user_delete +* post_backup_create +* post_backup_restore +* pre_backup_delete +* post_backup_delete +* post_app_addaccess +* post_app_removeaccess +* post_app_clearaccess +* post_app_addaccess +* post_iptable_rules + +Ces scripts sont à placer dans un répertoire `hooks` comme dans ce paquet : https://github.com/YunoHost-Apps/owncloud_ynh/tree/master/hooks . + + +#### YEP 4.6 - Gèrer le multi-instance | validé | manuel | OPTIONAL | +Il est parfois pratique de pouvoir installer plusieurs fois une même app. Par exemple, pour plusieurs noms de domaine différents. + +Il faut toutefois faire attention à la façon de gérer les chemins de fichier, les dépendances, les ports utilisés etc. de sorte qu'il n'y ait pas de collision. + #### YEP 4.7 - Ajouter un module à la CLI | validé | manuel | OPTIONAL | +Il est possible de créer un module afin d'ajouter des commandes à la ligne de commandes yunohost. + +Pour ce faire, il faut ajouter un actionmaps dans `/usr/share/moulinette/actionsmap/`. Cet actionmaps doit commencer par `ynh_`. + +Les paquets [menu_ynh](https://github.com/YunoHost-Apps/menu_ynh/) et [subscribe_ynh](https://github.com/YunoHost-Apps/subscribe_ynh/) bien qu’anciens (et non à jour) peuvent servir de base pour mettre en place ce genre de module. #### YEP 4.8 - Ajouter un module à l'admin web | brouillon | manuel | OPTIONAL | diff --git a/packaging_apps_start_fr.md b/packaging_apps_start_fr.md new file mode 100644 index 00000000..cdd8d7fc --- /dev/null +++ b/packaging_apps_start_fr.md @@ -0,0 +1,53 @@ +Petite introduction au packaging d'application, pour comprendre de quoi nous parlons et comment ça marche. +Cette documentation s'adresse avant tout aux packageurs débutants qui ne sont pas à l'aise avec les concepts de shell, parsing et administration système de manière générale. + +Nous verrons ici ce qu'est un package d'application YunoHost, comment cela fonctionne, comment faire pour écrire un package et comment se lancer dans l'aventure sans être tout seul. + +### De quoi on parle en fait ? + +Avant de démarrer, la bonne question c'est "Qu'est-ce qu'un package d'application !?" + +Pour répondre à cette question, il faut revenir à ce qu'est YunoHost, c'est un système d’exploitation serveur visant à simplifier l’auto-hébergement de services Internet. Et pour faire ça, YunoHost met à disposition, entre autre, une interface d'administration permettant d'installer des applications en quelques clics. +Or si vous avez déjà installé une application web à la main, vous savez qu'en réalité c'est bien plus compliqué que quelques clics sur une jolie interface. + +C'est là que le package d'application entre en jeu, c'est un ensemble de scripts qui automatise l'installation d'une application web et la préconfigure pour que l'utilisateur final n'ai besoin que de quelques clics pour l'installer facilement. + +### Mais alors, comment ça marche ? + +Du point de vue de l'utilisateur, c'est très simple, on choisit une application, on répond à quelques questions, ça mouline et c'est prêt. + +Mais il se passe bien plus de choses derrière. +Tout d'abord, lorsque l'application est sélectionnée, YunoHost va aller chercher son package sur Github, par exemple l'application [Custom Webapp](https://github.com/YunoHost-Apps/my_webapp_ynh). +Ensuite, YunoHost lit le fichier manifest.json pour connaître les questions à poser à l'utilisateur. + +Mais ces questions anodines sont très importantes, on retrouvera souvent le domaine sur lequel installer l'application, l'adresse à laquelle elle sera accessible, l'utilisateur qui en sera l'administrateur et la langue par défaut de l'application. + +Ce sont là des éléments essentiels pour configurer correctement notre application web lors de son installation. Pour ce faire, YunoHost va récupérer les réponses données par l'utilisateur et les envoyer au script install qui se trouve dans le dossier scripts du package. + +Le script install va se charger d'installer l'application, en prenant en compte les réponses données par l'utilisateur. Ce script va simplement faire ce que vous auriez fait si vous aviez installé l'application à la main. + +Si par la suite l'utilisateur souhaite supprimer l'application, YunoHost utilisera le script remove du dossier script, qui se chargera à la place de l'utilisateur de supprimer l'application, ses dossiers et tout ses fichiers de configuration. + +### Qu'il y a-t-il dans ces scripts pour que tout soit si simple pour l'utilisateur ? + +Les scripts d'un package d'application sont simplement des commandes bash les unes à la suite des autres. + +#### ... Et c'est quoi une commande bash ? + +Une commande [bash](https://fr.wikipedia.org/wiki/Bourne-Again_shell) c'est une ligne de texte qui sera interprétée et produira un résultat. C'est ce qu'on a l'habitude d'appeler la ligne de commande. +Or puisque votre serveur, sur lequel est installé YunoHost, ne dispose pas d'une interface graphique, vous n'avez que la ligne de commande de disponible. Vous l'atteignez en général après vous être connecté avec [ssh](/ssh_fr). + +Les scripts d'un package ne sont donc qu'une succession de commandes bash, comme si vous les aviez tapées directement dans la console ssh pour installer l'application. + +Pour savoir quoi écrire dans un script bash, je vous conseille de commencer par la lecture d'un [tuto simple](https://debian-facile.org/doc:programmation:shells:debuter-avec-les-scripts-shell-bash). Et si vous avez vraiment envie de lire, il y a aussi un [tuto plus complet](http://aral.iut-rodez.fr/fr/sanchis/enseignement/bash/index.html) + +### Ok, je crois que j'ai compris ! Par où on commence? + +Avant d'envisager de faire un package d'application, il faut réussir à installer correctement la dites application. Car le script ne fera que ce que vous lui direz de faire. + +Ensuite, il faut aller lire (et oui encore) la documentation sur le packaging, mais la vrai cette fois, [celle qui emploie des mots bizarres](/packaging_apps_fr). +Mais maintenant vous devriez les comprendre tout ces mots étranges. + +Mais heureusement, vous n'êtes pas seul pour affronter cette épreuve titanesque, il y a d'autres packageurs que vous pouvez venir rencontrer sur le [forum](https://forum.yunohost.org/c/apps-packaging) et sur le [salon de discussion](xmpp:apps@conference.yunohost.org?join). +N'hésitez pas à venir poser des questions sur ce que vous ne comprenez pas, il y aura toujours quelqu'un pour vous répondre. +Et vous constaterez bien vite que ce n'est pas si difficile de packager une application. diff --git a/sitemap_fr.md b/sitemap_fr.md index 550b1e97..5d027138 100644 --- a/sitemap_fr.md +++ b/sitemap_fr.md @@ -95,6 +95,7 @@ * [Présentation du fonctionnement de YunoHost](/package_list_fr) * Applications : * [Packager des applications](/packaging_apps_fr) + * [Introduction](packaging_apps_start_fr.md) * [Manifeste](packaging_apps_manifest_fr) * [Scripts](packaging_apps_scripts_fr) * [Gestion des arguments](packaging_apps_arguments_management_fr)