mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
Rework the app packaging doc... / trash almost everything
This commit is contained in:
Alexandre Aubin
parent
f7f48d302b
commit
8bfc73cbaf
38 changed files with 110 additions and 3050 deletions
|
|
@ -1,98 +0,0 @@
|
|||
---
|
||||
title: Packaging d'applications
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps'
|
||||
---
|
||||
|
||||
|
||||
|
||||
Ce document a pour but de vous apprendre à packager une application pour YunoHost.
|
||||
|
||||
! This page is outdated and should be reworked
|
||||
|
||||
### Prérequis
|
||||
Pour packager une application, voici les prérequis :
|
||||
* Un compte sur un serveur Git comme [GitHub](https://github.com/) pour pouvoir ensuite publier l’application ;
|
||||
* Maîtriser un minimum [Git](/packaging_apps_git), le Shell et d’autres notions de programmation ;
|
||||
* Une [machine virtuelle ou sur un serveur distant](/install) ou un environnement de développement, [ynh-dev](https://github.com/yunohost/ynh-dev) ou [VirtualBox](/packaging_apps_virtualbox), 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).
|
||||
|
||||
### Contenu
|
||||
Un paquet YunoHost est composé :
|
||||
|
||||
* d’un `manifest.json`
|
||||
* d’un dossier `scripts`, composé de six scripts Shell `install`, `remove`, `upgrade`, `backup`, `change_url` et `restore`
|
||||
* de dossiers optionnels, contenant les `sources` ou de la `conf`
|
||||
* d’un fichier `LICENSE` contenant la licence du paquet
|
||||
* d’une page de présentation du paquet contenu dans un fichier `README.md`
|
||||
|
||||
[div class="btn btn-lg btn-default"] [Paquet de base](https://github.com/YunoHost/example_ynh) [/div] n’hésitez pas à vous en servir comme base de travail.
|
||||
|
||||
## Manifeste
|
||||
[div class="btn btn-lg btn-default"] [Manifeste](/packaging_apps_manifest) [/div]
|
||||
|
||||
## Les scripts
|
||||
[div class="btn btn-lg btn-default"] [Scripts](/packaging_apps_scripts) [/div]
|
||||
|
||||
### Architecture et arguments
|
||||
Comme les instances de YunoHost possèdent une architecture unifiée, vous serez capable de deviner la plupart des réglages nécessaires. Mais si vous avez besoin de réglages spécifiques, comme le nom de domaine ou un chemin web pour configurer l’application, vous devrez les demander aux administrateurs lors de l’installation (voir la section `arguments` dans le § **Manifeste** ci-dessus).
|
||||
|
||||
[div class="btn btn-lg btn-default"] [Gestion des arguments](/packaging_apps_arguments_management) [/div]
|
||||
|
||||
### Configuration NGINX
|
||||
[div class="btn btn-lg btn-default"] [Configuration NGINX](/packaging_apps_nginx_conf) [/div]
|
||||
|
||||
### Multi-instance
|
||||
[div class="btn btn-lg btn-default"] [Multi-instance](/packaging_apps_multiinstance) [/div]
|
||||
|
||||
### Hooks
|
||||
[div class="btn btn-lg btn-default"] [Hooks](/packaging_apps_hooks) [/div]
|
||||
|
||||
### Commandes pratiques
|
||||
[div class="btn btn-lg btn-default"] [Commandes pratiques](/packaging_apps_helpers) [/div]
|
||||
|
||||
|
||||
### Améliorer la qualité du paquet d’installation
|
||||
Vous trouverez ci-dessous une liste des points à vérifier concernant la qualité de vos scripts :
|
||||
* Vos scripts utilisent bien `sudo cp -a ../sources/. $final_path` plutôt que `sudo cp -a ../sources/* $final_path` ;
|
||||
* Votre script d’installation contient une gestion en cas d’erreurs du script pour supprimer les fichiers résiduels à l’aide de `set -e` et de [trap](/packaging_apps_trap) ;
|
||||
* Votre script d’installation utilise une méthode d’installation en ligne de commande plutôt qu’un appel curl via un formulaire web d’installation ;
|
||||
* Votre script d’installation enregistre les réponses de l’utilisateur ;
|
||||
* Vous avez vérifié les sources de l’application avec une somme de contrôle (sha256, sha1 ou md5) ou une signature PGP ;
|
||||
* Vos scripts ont été testés sur Debian Buster 32 bits, 64 bits et ARM ;
|
||||
* Les scripts backup et restore sont présents et fonctionnels.
|
||||
|
||||
Pour mesurer la qualité d'un paquet, celui-ci obtiendra un [niveau](/packaging_apps_levels), déterminé en fonction de divers critères d'installation et selon le respect des [règles de packaging](/packaging_apps_guidelines).
|
||||
|
||||
### Script de vérification du paquet
|
||||
[div class="btn btn-lg btn-default"] [Vérificateur de paquets](https://github.com/YunoHost/package_checker) [/div]
|
||||
|
||||
Il s’agit d’un script Python qui vérifie :
|
||||
* que le paquet est à jour concernant les dernières spécifications
|
||||
* que tous les fichiers sont présents
|
||||
* que le manifeste ne comporte pas d’erreur de syntaxe
|
||||
* que les scripts quittent bien avant de modifier le système lors de vérifications.
|
||||
|
||||
### Intégration continue
|
||||
|
||||
Un serveur d'intégration continue est a disposition des packagers désirant tester leurs applications.
|
||||
[div class="btn btn-lg btn-default"] [Intégration continue](packaging_apps_ci) [/div]
|
||||
|
||||
### Publiez et demandez des tests de votre application
|
||||
|
||||
* Demandez des tests et des retours sur votre application en publiant un [post sur le Forum](https://forum.yunohost.org/) dans la [catégorie `Discussion > Apps`](https://forum.yunohost.org/c/discuss/discuss-apps/).
|
||||
|
||||
* Si votre paquet et l'application qu'il contient sont sous licence libre, faites une demande d’ajout de votre application dans le [dépôt des applications](https://github.com/YunoHost/apps) (voir aussi [la liste des apps](/apps)). Vous pouvez ajouter une application même si celle-ci n'est pour le moment pas fonctionelle : l'état d'avancement peut être `notworking`, `inprogress` ou `working`.
|
||||
|
||||
* Si votre application n'est *pas* sous licence libre, il se peut qu'une liste non-officielle soit créée pour gérer ces applications. Ce n'est pour l'instant pas le cas.
|
||||
|
||||
### Officialisation d’une application
|
||||
|
||||
**!! Section obsolète au 08/03/19** - Le fonctionnement du projet est en cours d'évolution sur ce point.
|
||||
|
||||
Pour qu’une application devienne officielle, elle doit être suffisamment testée, stable et fonctionner sous Debian Buster 64 bits, 32 bits et ARM. Si ces conditions vous paraissent réunies, demandez l’[intégration officielle](https://github.com/YunoHost/apps) de votre application.
|
||||
|
|
@ -1,115 +0,0 @@
|
|||
---
|
||||
title: App packaging
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps'
|
||||
---
|
||||
|
||||
|
||||
|
||||
The purpose of this document is to teach you how to package an application for YunoHost.
|
||||
|
||||
! This page is outdated and should be reworked
|
||||
|
||||
### Requirements
|
||||
To package an application, here are the requirements:
|
||||
* An account on a Git server (e.g. [GitHub](https://github.com/)) to publish the application;
|
||||
* Basic knowledge of [Git](/packaging_apps_git), bash shell and other programming stuff;
|
||||
* A testing [virtual machine or a distant server](/install) or [VirtualBox](/packaging_apps_virtualbox), to package and test the package. Alternatively you can also use [ynh-dev](https://github.com/yunohost/ynh-dev), it is meant for the core but can totally be used for developping apps, but be aware that for now the documentation on this part is lacking.
|
||||
|
||||
### Content
|
||||
A YunoHost package is composed of:
|
||||
|
||||
* A `manifest.json` file
|
||||
* A `scripts` directory, which contains five Shell scripts: `install`, `remove`, `upgrade`, `backup` and `restore`
|
||||
* Optional directories, containing `sources` or `conf` files
|
||||
* A `LICENSE` file containing the license of the package
|
||||
* A presentation page of your package in a `README.md` file
|
||||
|
||||
[div class="btn btn-lg btn-default"] [ A basic package](https://github.com/YunoHost/example_ynh) [/div]
|
||||
feel free to use it as a framework.
|
||||
|
||||
## Manifest
|
||||
[div class="btn btn-lg btn-default"] [Manifest](/packaging_apps_manifest) [/div]
|
||||
|
||||
## Scripts
|
||||
[div class="btn btn-lg btn-default"] [Scripts](/packaging_apps_scripts) [/div]
|
||||
|
||||
### Architecture and arguments
|
||||
Since YunoHost has a unified architecture, you will be able to guess most of the settings you need. But if you need variable ones, like the domain or web path, you will have to ask the administrator at installation (see `arguments` section in the manifest above).
|
||||
|
||||
[div class="btn btn-lg btn-default"] [Arguments management](/packaging_apps_arguments_management) [/div]
|
||||
|
||||
### NGINX configuration
|
||||
[div class="btn btn-lg btn-default"] [NGINX configuration](/packaging_apps_nginx_conf) [/div]
|
||||
|
||||
### Multi-instance
|
||||
[div class="btn btn-lg btn-default"] [Multi-instance](/packaging_apps_multiinstance) [/div]
|
||||
|
||||
### Hooks
|
||||
YunoHost provides a hook system, which is accessible via the packager's script callbacks in command line.
|
||||
The scripts have to be placed in the `hooks` repository at the root of the YunoHost package, and must be named `priority-hook_name`, for example: `hooks/50-post_user_create` will be executed after each user creation.
|
||||
|
||||
**Note**: `priority` is optional, default is `50`.
|
||||
|
||||
Take a look at the [Nextcloud package](https://github.com/YunoHost-Apps/nextcloud_ynh/) for a working example.
|
||||
|
||||
### Helpers
|
||||
[div class="btn btn-lg btn-default"] [Helpers](/packaging_apps_helpers) [/div]
|
||||
|
||||
### Test it!
|
||||
In order to test your package, you can execute your script standalone as `admin` (do not forget to append required arguments):
|
||||
```bash
|
||||
su - admin -c "/bin/bash /path/to/my/script my_arg1 my_arg2"
|
||||
```
|
||||
|
||||
Or you can use [command line](/commandline):
|
||||
```bash
|
||||
yunohost app install /path/to/my/app/package
|
||||
```
|
||||
Note that it also works with a Git URL:
|
||||
```bash
|
||||
yunohost app install https://github.com/author/my_app_package.git
|
||||
```
|
||||
|
||||
### Packaging best practices
|
||||
Here is a list of best practices for application install scripts:
|
||||
* scripts should use `sudo cp -a ../sources/. $final_path` instead of `sudo cp -a ../sources/* $final_path`;
|
||||
* install script must contain support in case of script errors to delete residuals files thanks to `set -e` and [trap](/packaging_apps_trap);
|
||||
* install script should use the command-line method instead of calls to curl through web install form;
|
||||
* install script should save install answers;
|
||||
* application sources should be checked with a control sum (sha256, sha1 or md5) or a PGP signature;
|
||||
* scripts should be tested on Debian Buster 32 bits, 64 bits and ARM architectures;
|
||||
* backup and restore scripts should be present and functional.
|
||||
|
||||
To be define the quality of a package, it'll obtained a [level](/packaging_apps_levels), determined according to somes criteria of installation and according to respect to [package guidelines](/packaging_apps_guidelines).
|
||||
|
||||
### Package script checker
|
||||
[div class="btn btn-lg btn-default"] [Package checker](https://github.com/YunoHost/package_checker) [/div]
|
||||
|
||||
This Python script checks:
|
||||
* that the package is up to date wich last specifications
|
||||
* that all files are present
|
||||
* that the manifest doesn't have syntax errors
|
||||
* that scripts exit well before modifing the system during verification.
|
||||
|
||||
### Continuous integration
|
||||
|
||||
A continuous integration server is available for packagers who want to test their apps.
|
||||
[div class="btn btn-lg btn-default"] [Continuous integration](packaging_apps_ci) [/div]
|
||||
|
||||
### Publish and ask for testing your application
|
||||
|
||||
* Publishing a [post on the Forum](https://forum.yunohost.org/) in the [`Discuss > Apps` category](https://forum.yunohost.org/c/discuss/discuss-apps/), to ask for testing and feedback on your application.
|
||||
|
||||
* If your application is released under a free software license, you may ask the YunoHost app team to integrate your application to the [app repository](https://github.com/YunoHost/apps) (c.f. also the [app list](/apps)). You can add your application even if it is not stable or working yet : the current state can be specified to `notworking`, `inprogress`, or `working`.
|
||||
|
||||
* If your application is *not* free software, then in the future, a non-official list might be created to handle them but is non-existent yet.
|
||||
|
||||
### Officalization of an application
|
||||
|
||||
**!! This section is obsolete as of 08/03/19** - The project's organization regarging this point is to be changed.
|
||||
|
||||
To become an official application, it must be tested well enough, be stable and should work on Debian Buster 64 bits, 32 bits and ARM architectures. If you think those conditions are met, ask for [official integration](https://github.com/YunoHost/apps) of your application.
|
||||
|
|
@ -1,93 +0,0 @@
|
|||
---
|
||||
title: Packaging d'application
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_manifest'
|
||||
---
|
||||
|
||||
## Manifeste
|
||||
Le fichier `manifest.json` définit les constantes de l’application, un ensemble de valeurs dont YunoHost a besoin pour identifier l’application et l’installer correctement. Voici un exemple :
|
||||
```json
|
||||
{
|
||||
"name": "Roundcube",
|
||||
"id": "roundcube",
|
||||
"packaging_format": 1,
|
||||
"description": {
|
||||
"en": "Open Source Webmail software",
|
||||
"fr": "Webmail Open Source"
|
||||
},
|
||||
"url": "http://roundcube.net/",
|
||||
"version": "1.0.1~ynh7",
|
||||
"license": "free",
|
||||
"maintainer": {
|
||||
"name": "kload",
|
||||
"email": "kload@kload.fr"
|
||||
},
|
||||
"requirements": {
|
||||
"yunohost": ">= 2.4.0"
|
||||
},
|
||||
"multi_instance": true,
|
||||
"services": [
|
||||
"nginx",
|
||||
"php5-fpm",
|
||||
"mysql"
|
||||
],
|
||||
"arguments": {
|
||||
"install" : [
|
||||
{
|
||||
"name": "domain",
|
||||
"type": "domain",
|
||||
"ask": {
|
||||
"en": "Choose a domain for Roundcube",
|
||||
"fr": "Choisissez un domaine pour Roundcube"
|
||||
},
|
||||
"example": "domain.org"
|
||||
},
|
||||
{
|
||||
"name": "path",
|
||||
"type": "path",
|
||||
"ask": {
|
||||
"en": "Choose a path for Roundcube",
|
||||
"fr": "Choisissez un chemin pour Roundcube"
|
||||
},
|
||||
"example": "/webmail",
|
||||
"default": "/webmail"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* **name** : nom de l’application. Son unicité n’est pas nécessaire. Il est tout de même conseillé étant donné que c’est le nom qui apparaît dans la liste des applications pour les administrateurs de serveurs YunoHost.
|
||||
|
||||
* **id** : identifiant de l’application. Vous devez vous assurer de son unicité.
|
||||
|
||||
- **packaging_format** : version de packaging du paquet. La version **1** est la version actuelle. Cette clé a été mise en place afin de faire évoluer les versions de packaging de manière décorrélée des versions de YunoHost.
|
||||
|
||||
* **description** : description complète de l’application. Vous pouvez la détailler comme bon vous semble. Uniquement le champ `en` (english) est requis, vous pouvez également ajouter la traduction en français :)
|
||||
|
||||
* **url** : site web de l’application.
|
||||
|
||||
* **version** : version du package construit à partir du numéro de version de l’application qui est installée et d'un incrément pour chaque changement du paquet sans changement de version de l'application. "Exemple: 1.0.1~ynh7". Le champ doit être une chaîne de caractères.
|
||||
|
||||
* **license** : licence avec laquelle l’application est distribuée : `free`, `non-free` ou une des valeurs de la colonne Identifier du site https://spdx.org/licenses/. Attention à ne pas confondre avec la licence du paquet qui doit être mise dans le fichier `LICENSE`.
|
||||
|
||||
* **maintainer** : informations à propos du mainteneur du paquet de l’application pour pouvoir le contacter.
|
||||
|
||||
- **requirements** : dépendance du paquet de l’application à la version d’un paquet Debian de YunoHost. Par exemple : "yunohost": ">> 2.3.12", le paquet `yunohost` doit être de version supérieur à `2.3.12`.
|
||||
|
||||
* [**multi_instance**](/packaging_apps_multiinstance) : capacité d’une application d’être installée plusieurs fois.
|
||||
|
||||
* **services** : liste des services nécessaires au fonctionnement de l’application. `nginx`, `php5-fpm`, `mysql`, `uwsgi`, `metronome`, `postfix`, `dovecot`…
|
||||
|
||||
* **arguments** :
|
||||
* **install** : paramètres à demander à l’administrateur lors de l’installation.
|
||||
* **name** : identifiant du paramètre
|
||||
* **type** : (optionnel) type de paramètre parmi `domain`, `path`, `user`, `app`, `boolean`, `string` et `password`. Le champ sera caché dans le cas d’un mot de passe.
|
||||
* **choices** : (optionnel) restreint les réponses possibles à plusieurs choix.
|
||||
* **optional** : (optionnel) champ qui indique si ce paramètre est optionnel. Il peut avoir les valeurs `true` ou `false`.
|
||||
* **ask** : question posée (au minimum en anglais – `en`) que vous pouvez traduire dans plusieurs langues.
|
||||
* **example** : (optionnel) valeur d’exemple pour aider l’administrateur à remplir le formulaire d’installation.
|
||||
* **default** : (optionnel) valeur par défaut.
|
||||
|
|
@ -1,93 +0,0 @@
|
|||
---
|
||||
title: Application packaging
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_manifest'
|
||||
---
|
||||
|
||||
## Manifest
|
||||
The `manifest.json` file defines the app's constants, a bunch of values that YunoHost needs to identify the app and install it correctly. It looks like this:
|
||||
```json
|
||||
{
|
||||
"name": "Roundcube",
|
||||
"id": "roundcube",
|
||||
"packaging_format": 1,
|
||||
"description": {
|
||||
"en": "Open Source Webmail software",
|
||||
"fr": "Webmail Open Source"
|
||||
},
|
||||
"url": "http://roundcube.net/",
|
||||
"version": "1.0.1~ynh7",
|
||||
"license": "free",
|
||||
"maintainer": {
|
||||
"name": "kload",
|
||||
"email": "kload@kload.fr"
|
||||
},
|
||||
"requirements": {
|
||||
"yunohost": ">= 2.4.0"
|
||||
},
|
||||
"multi_instance": true,
|
||||
"services": [
|
||||
"nginx",
|
||||
"php5-fpm",
|
||||
"mysql"
|
||||
],
|
||||
"arguments": {
|
||||
"install" : [
|
||||
{
|
||||
"name": "domain",
|
||||
"type": "domain",
|
||||
"ask": {
|
||||
"en": "Choose a domain for Roundcube",
|
||||
"fr": "Choisissez un domaine pour Roundcube"
|
||||
},
|
||||
"example": "domain.org"
|
||||
},
|
||||
{
|
||||
"name": "path",
|
||||
"type": "path",
|
||||
"ask": {
|
||||
"en": "Choose a path for Roundcube",
|
||||
"fr": "Choisissez un chemin pour Roundcube"
|
||||
},
|
||||
"example": "/webmail",
|
||||
"default": "/webmail"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* **name**: app name. It does not have to be unique, but it should be, since it is the name shown to all the YunoHost administrators in the app list. Any characters are allowed.
|
||||
|
||||
* **id**: ID of the app. You have to ensure that this ID is unique before submit an app integration request. See [packaging_apps_guidelines.md#yep-11](https://github.com/YunoHost/doc/blob/master/packaging_apps_guidelines.md#yep-11) for valid rules.
|
||||
|
||||
- **packaging_format**: package version. Current version is **1**. This key has been set up to make independant packaging evolution versions from YunoHost versions evolution.
|
||||
|
||||
* **description**: complete app description. You can make it as detailed as you feel it should be. Only `en` is required right now, but you can translate the description by prepending the locale prefix.
|
||||
|
||||
* **url**: software website.
|
||||
|
||||
* **version**: version of the package built from the upstream version number and an incremental number for each change in the package without upstream change. Example "1.0.1~ynh7". Must be a string.
|
||||
|
||||
* **license**: application license: `free`, `non-free` or a value from the Identifier column from https://spdx.org/licenses/. Be careful to not confuse with package license which must be put in `LICENSE` file.
|
||||
|
||||
* **maintainer**: informations about the app maintainer for contact.
|
||||
|
||||
- **requirements**: dependency of the application package to a Debian YunoHost package version. For instance, "yunohost": ">> 2.3.12", `yunohost` package version must be up to `2.3.12`.
|
||||
|
||||
* [**multi_instance**](/packaging_apps_multiinstance): it defines app's ability to be installed multiple times.
|
||||
|
||||
* **services**: services needed by the application among `nginx`, `php5-fpm`, `mysql`, `uwsgi`, `metronome`, `postfix`, `dovecot`…
|
||||
|
||||
* **arguments**:
|
||||
* **install**: argument for the YunoHost's administrator to enter at installation.
|
||||
* **name**: argument identification.
|
||||
* **type**: (optional) argument type among `domain`, `path`, `user`, `app`, `boolean`, `string` and `password`. The field will be hidden in the password case.
|
||||
* **choices** : (optional) restrict value to several choices.
|
||||
* **optional** : (optional) field which indicate if this argument is optional. It can have `true` and `false` value.
|
||||
* **ask**: question (at least in `en`) that you can translate.
|
||||
* **example**: (optional) example value to help administrator to fill the input.
|
||||
* **default**: (optional) default value.
|
||||
|
|
@ -1,72 +0,0 @@
|
|||
---
|
||||
title: Scripts
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_scripts'
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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`).
|
||||
|
||||
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'exécution du script. Elle peut être utile pour retrouver le chemin initial si on s'est déplacé pendant l'exécution 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 situations pour pouvoir gérer l'installation multiple d'une même app.
|
||||
|
||||
Exemple: strut__3
|
||||
#### YNH_APP_INSTANCE_NUMBER
|
||||
Contient le numéro de l'instance. Attention il ne s'agit pas forcément du nombre d'instances toujours installées, 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 lors de l'installation, une variable d'environnement est disponible.
|
||||
|
||||
Par exemple, si dans le manifest nous avons une question de cette forme
|
||||
```json
|
||||
{
|
||||
"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 :
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
|
@ -1,71 +0,0 @@
|
|||
---
|
||||
title: Scripts
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_scripts'
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
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
|
||||
|
||||
### Variables specific to `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
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```bash
|
||||
domain=$YNH_APP_ARG_DOMAIN
|
||||
```
|
||||
|
||||
### Variables specific to `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.
|
||||
|
||||
|
|
@ -1,338 +0,0 @@
|
|||
---
|
||||
title: YunoHost Arguments Format
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_arguments_format'
|
||||
---
|
||||
|
||||
In YunoHost application developpement there are several places where you end up
|
||||
writting questions for your user like in the `manifest.json/toml`, the
|
||||
`config_panel.json/toml` or `actions.json/toml`.
|
||||
|
||||
This page documents this format and all available kind of questions you can ask
|
||||
your user. Unless it's stated otherwise, this format applies to everyplace it's
|
||||
usable (for now: installation arguments in `manifest.json/toml`,
|
||||
`config_panel.json/toml` and `actions.json/toml`)
|
||||
|
||||
## YunoHost arguments general format
|
||||
|
||||
The general format for an argument looks like this in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "one_of_the_available_type"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
help.en = "some help text in english" # optional
|
||||
help.fr = "some help text in french" # optional
|
||||
example = "an example value" # optional
|
||||
default = "some stuff" # optional, not available for all types
|
||||
optional = true # optional, will skip if not answered
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "one_of_the_available_type", // "sting" is not specified
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
},
|
||||
"help": {
|
||||
"en": "some help text in english",
|
||||
"fr": "some help text in french"
|
||||
},
|
||||
"example": "an example value", // optional
|
||||
"default", "some stuff", // optional, not available for all types
|
||||
"optional": true // optional, will skip if not answered
|
||||
},
|
||||
```
|
||||
|
||||
## All avaiable types
|
||||
|
||||
### string
|
||||
|
||||
This one is the simpliest one and is the default type if you don't specify one.
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "string" # optional
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
example = "an example value" # optional
|
||||
default = "some stuff" # optional
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "string", // optional
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
},
|
||||
"default": "some stuff", // optional
|
||||
"example": "an example value"
|
||||
},
|
||||
```
|
||||
|
||||
### string with choices
|
||||
|
||||
Like string except the user needs to chose in a list of specifics strings.
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "string"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "la question en français"
|
||||
example = "an example value" # optional
|
||||
choices = ["fr", "en"]
|
||||
default = "en" # optional
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "string",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
},
|
||||
"example": "an example value",
|
||||
"choices": ["fr", "en"],
|
||||
"default": "en" // optional
|
||||
},
|
||||
```
|
||||
|
||||
### domain
|
||||
|
||||
This type will ask the user to chose one of the domains of their YunoHost instance.
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "domain"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "domain",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
### Path
|
||||
|
||||
This type will ask the user to chose an URL path (generally to happen it to a
|
||||
domain) like "/path/to/my/app"
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "path"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
default = "/my_app"
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "path",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
},
|
||||
"default": "/my_app"
|
||||
},
|
||||
```
|
||||
|
||||
### User
|
||||
|
||||
This type will ask the user to select a user in the list of users in their
|
||||
YunoHost installation. Generally this is used to select who is going to be the
|
||||
admin or who is going to have access to this application.
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "user"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "user",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
### Password
|
||||
|
||||
This type will ask the user to input a password. This is generally used to
|
||||
input the password for creating an account on the application.
|
||||
|
||||
In CLI it will behave like any password query and won't print any character on
|
||||
type (not "\*\*\*...") for security reasons.
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "password"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "password",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
### Boolean
|
||||
|
||||
This type will ask the user to answer true or false to a question.
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "boolean"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
default = true
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "boolean",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
},
|
||||
"default": true
|
||||
},
|
||||
```
|
||||
|
||||
### Number
|
||||
|
||||
Like string except the user needs to enter a number
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "number"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
default = 0
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "number",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
},
|
||||
"default": 0
|
||||
},
|
||||
```
|
||||
|
||||
### App
|
||||
|
||||
This type will ask the user to select an application in the list of installed
|
||||
application on their YunoHost.
|
||||
|
||||
Example in toml:
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "app"
|
||||
ask.en = "the question in english"
|
||||
ask.fr = "the question in french"
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "app",
|
||||
"ask": {
|
||||
"en": "the question in english",
|
||||
"fr": "the question in french"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
### display_text
|
||||
|
||||
This is a special type that allows the application packager to write some text
|
||||
that will be simply displayed. This is useful to provide more context.
|
||||
|
||||
```toml
|
||||
[maybe.some.stuff.before.the_name]
|
||||
type = "display_text"
|
||||
ask.en = "the text in english"
|
||||
ask.fr = "the text in french"
|
||||
```
|
||||
|
||||
And in json:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "the_name",
|
||||
"type": "display_text",
|
||||
"ask": {
|
||||
"en": "the text in english",
|
||||
"fr": "the text in french"
|
||||
}
|
||||
},
|
||||
```
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
---
|
||||
title: Gestion des arguments
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_arguments_management'
|
||||
---
|
||||
|
||||
#### Récupérer les arguments du manifeste dans le script d’installation
|
||||
Les arguments sont passés au script d’installation dans l’ordre du manifeste. Par exemple pour Roundcube, les arguments `domain` et `path` seront respectivement récupérés via les variables d’environnement ou les paramètres `$1` et `$2` dans le script d’installation.
|
||||
|
||||
```bash
|
||||
# Retrieve arguments
|
||||
domain=$YNH_APP_ARG_DOMAIN
|
||||
path=$YNH_APP_ARG_PATH
|
||||
```
|
||||
|
||||
#### Sauvegarder des arguments pour les autres scripts
|
||||
Les scripts remove, upgrade, backup et restore peuvent avoir besoin de ces arguments.
|
||||
|
||||
Pour cela, YunoHost peut sauvegarder les arguments avec cette commande :
|
||||
```bash
|
||||
# Store config on YunoHost instance
|
||||
ynh_app_setting_set --app="$app" --key="domain" --value="$domain"
|
||||
```
|
||||
Elle est généralement utilisée dans le script d’installation.
|
||||
|
||||
Ensuite, le script peut récupérer les arguments sauvegardés avec cette commande :
|
||||
```bash
|
||||
domain=$(ynh_app_setting_get --app "$app" --key=domain)
|
||||
```
|
||||
|
||||
Ces données sont sauvegardées dans `/etc/yunohost/apps/<app_name>/settings.yml`.
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
---
|
||||
title: Arguments management
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_arguments_management'
|
||||
---
|
||||
|
||||
#### Retrieve arguments in the install script from manifest
|
||||
Arguments are given to the install script from the manifest in it's order. For instance, for Roundcube, `domain` and `path` arguments will respectively be retreived from environment variables or from `$1` and `$2` parameters in the install script.
|
||||
|
||||
```bash
|
||||
# Retrieve arguments
|
||||
domain=$YNH_APP_ARG_DOMAIN
|
||||
path=$YNH_APP_ARG_PATH
|
||||
```
|
||||
|
||||
#### Save arguments for other scripts
|
||||
Remove, upgrade, backup and restore scripts could need arguments.
|
||||
|
||||
YunoHost could save arguments with this command which is generally used in the install script:
|
||||
```bash
|
||||
# Store config on YunoHost instance
|
||||
ynh_app_setting_set $app domain $domain
|
||||
```
|
||||
|
||||
Then, the script can retrieve saved arguments with this command:
|
||||
```bash
|
||||
domain=$(ynh_app_setting_get $app domain)
|
||||
```
|
||||
|
||||
Those data are saved in `/etc/yunohost/apps/<app_name>/settings.yml`.
|
||||
|
|
@ -1,82 +0,0 @@
|
|||
---
|
||||
title: User groups and permissions
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_permissions'
|
||||
---
|
||||
|
||||
Installing an app creates the permission `app.main` with `all_users` allowed by default.
|
||||
|
||||
If you wish to make the application publicly available, instead of the old `unprotected_urls` mechanism, you should give access to the special group `visitors`:
|
||||
|
||||
```shell
|
||||
ynh_permission_update --permission "main" --add visitors
|
||||
```
|
||||
|
||||
If you wish to create a custom permission for your app (e.g. to restrict access to an admin interface) you may use the following helpers:
|
||||
|
||||
```shell
|
||||
ynh_permission_create --permission "admin" --url "/admin" --allowed "$admin_user" --label "Label for your permission"
|
||||
```
|
||||
|
||||
You don't need to take care of removing permissions or backing up/restoring them as it is handled by the core of YunoHost.
|
||||
|
||||
### Migrating away from the legacy permission management
|
||||
|
||||
When migrating/fixing an app still using the legacy permission system, it should be understood that the accesses are now to be managed by features from the core, outside of the application scripts!
|
||||
|
||||
Application scripts are only expected to:
|
||||
- if relevant, during the install script, initialize the main permission of the app as public (`visitors`) or private (`all_users`) or only accessible to specific groups/users ;
|
||||
- if relevant, create and initialize any other specific permission (e.g. to some admin interface) in the install script (and *maybe* in some migration happening in the upgrade script).
|
||||
|
||||
Applications scripts should absolutely **NOT** mess up with any already-existing app accesses (including `unprotected`/`skipped_uris` settings) during any other case, as *it would reset any admin-defined access rule*!
|
||||
|
||||
When migrating away from the legacy permission, you should:
|
||||
- remove any management of `$is_public`-like or `$admin_user`-like setting, except for any manifest question meant to either *initialize* the app as public/private or specific permissions ;
|
||||
- remove the old legacy permissions. Check out the recommended way to proceed in the example_ynh app (in particular [this code snippet](https://github.com/YunoHost/example_ynh/pull/111/files#diff-57aeb84da86cb7420dfedd8e49bc644fb799d5413d01927a0417bde753e8922f))
|
||||
|
||||
It should boil down to :
|
||||
```bash
|
||||
if ynh_legacy_permissions_exists; then
|
||||
ynh_legacy_permissions_delete_all
|
||||
|
||||
ynh_app_setting_delete --app=$app --key=is_public
|
||||
|
||||
# Create the permission using the new framework (if your app has relevant additional permissions)
|
||||
ynh_permission_create --permission="admin" --url="/admin" --allowed=$admin
|
||||
fi
|
||||
```
|
||||
|
||||
- remove any call to `yunohost app addaccess` and similar actions that are now obsolete and deprecated.
|
||||
- if your app use LDAP and support filter, use the filter `'(&(objectClass=posixAccount)(permission=cn=YOUR_APP.main,ou=permission,dc=yunohost,dc=org))'` to allow users who have this permission. (A complete documentation of LDAP [here](https://moulinette.readthedocs.io/en/latest/ldap.html) if you want to undestand how it works with YunoHost)
|
||||
|
||||
#### Additional features from 4.1
|
||||
|
||||
- Label customization : this is the name displayed to end users in the user portal. You can provide a default label (for example app.admin maybe be labelled 'Admin interface'). The label may be changed later by the admin after installation.
|
||||
- Enabling/disabling tile : this toggles wether or not an app is shown in the user portal (if the user has the corresponding permission). The corresponding option is called `show_tile` which may be `True` or `False`. A single app may have multiple tiles in the SSO. The URL of each tile corresponds to the `url` parameter of the permission.
|
||||
- Multiple URL support: a permission may have additional urls associated to it. This give the possiblity to protect many url with the same permission - in particular for tricky use case (for example several pieces of admin interfaces spread over different subpaths).
|
||||
- Protecting permission: As a packager, you may choose to "protect" a permission if you believe that it's not relevant for the admin to add/remove this permission to/from the visitors group. For example, this is the case for the API permission of Nextcloud, which in the vast majority of cases should be kept publicly because mobile client won't go through the SSO. Note that when using the helper `ynh_permission_update`, it's still possible to add/remove the `visitor` group of this permission.
|
||||
- Disabling auth header: some app authentification mecanism do not appreciate that SSOwat injects the Authorization header (which is an essential mecanism for single sign-on). You can now choose to disable the auth header injection from SSOwat to fix this (instead of the previous hack of using `skipped_uris`)
|
||||
|
||||
##### Correspondance between the old and new permission mecanism
|
||||
|
||||
| | with auth header | no auth header |
|
||||
| :---------- | :--------------- | :------------- |
|
||||
| **public** | unprotected_uris | skipped_uris |
|
||||
| **private** | protected_uris | N/A |
|
||||
|
||||
|
||||
| | with auth header | no auth header |
|
||||
| :---------- | :------------------------------------------ | :------------------------------------------- |
|
||||
| **public** | auth_header=True, visitor group allowed | auth_header=False, visitor group allowed |
|
||||
| **private** | auth_header=True, visitor group not allowed | auth_header=False, visitor group not allowed |
|
||||
|
||||
|
||||
All of theses feature are managable by theses following helper:
|
||||
- `ynh_permission_create`
|
||||
- `ynh_permission_url`
|
||||
- `ynh_permission_update`
|
||||
|
||||
If you have any question, please contact the app team
|
||||
|
|
@ -1,81 +0,0 @@
|
|||
---
|
||||
title: Configuration NGINX
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_nginx_conf'
|
||||
---
|
||||
|
||||
Ce tutoriel a pour but d’aider à la mise en place d’une configuration NGINX pour le packaging d’application.
|
||||
|
||||
#### Configuration NGINX
|
||||
|
||||
La configuration doit être mise dans `conf/nginx.conf`. Il s’agira d’utiliser **FastCGI** ou un **proxy_pass** suivant l’application :
|
||||
* **FastCGI** est utilisé dans les applications PHP :
|
||||
|
||||
```nginx
|
||||
#sub_path_only rewrite ^__PATH__$ __PATH__/ permanent;
|
||||
location __PATH__/ {
|
||||
|
||||
proxy_pass http://127.0.0.1:__PORT__/;
|
||||
proxy_redirect off;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Host $server_name;
|
||||
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
}
|
||||
```
|
||||
|
||||
* **`proxy_pass`** dans le cas d’applications Python, Node.js, Go et Java :
|
||||
|
||||
```nginx
|
||||
#sub_path_only rewrite ^__PATH__$ __PATH__/ permanent;
|
||||
location __PATH__/ {
|
||||
|
||||
proxy_pass http://127.0.0.1:__PORT__/;
|
||||
proxy_redirect off;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Host $server_name;
|
||||
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
}
|
||||
```
|
||||
|
||||
#### Script d’installation
|
||||
|
||||
Il s’agit de modifier le fichier `conf/nginx.conf` avec les paramètres de l’application. Pour cela, on utilise des termes génériques `YNH_EXAMPLE_PATH` que l’on modifie par des valeurs souhaitées avec la commande `sed` :
|
||||
|
||||
```bash
|
||||
sed -i "s@YNH_EXAMPLE_PATH@$path@g" ../conf/nginx.conf
|
||||
sed -i "s@YNH_EXAMPLE_PORT@$port@g" ../conf/nginx.conf
|
||||
sed -i "s@YNH_EXEMPLE_DOMAIN@$domain@g" ../conf/nginx.conf
|
||||
```
|
||||
|
||||
Il faut ensuite déplacer ce fichier de configuration dans la configuration de NGINX, puis recharger la configuration de NGINX :
|
||||
|
||||
```bash
|
||||
cp ../conf/nginx.conf /etc/nginx/conf.d/$domain.d/$app.conf
|
||||
sudo service nginx reload
|
||||
```
|
||||
|
||||
Si NGINX ne redémarre pas, il se peut que le fichier de configuration ne soit pas correct.
|
||||
|
||||
#### Script de suppression
|
||||
|
||||
Il s’agit de supprimer la configuration NGINX pour cette application, puis de recharger la configuration de NGINX :
|
||||
|
||||
```bash
|
||||
rm -f /etc/nginx/conf.d/$domain.d/$app.conf
|
||||
sudo service nginx reload
|
||||
```
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
---
|
||||
title: NGINX configuration
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_nginx_conf'
|
||||
---
|
||||
|
||||
This tutorial aim to help setup NGINX configuration for application packaging.
|
||||
|
||||
#### NGINX configuration
|
||||
|
||||
Configuration must be in `conf/nginx.conf`. We must use **FastCGI** or a **proxy_pass** following the application:
|
||||
* **FastCGI** is used with PHP applications:
|
||||
|
||||
```nginx
|
||||
#sub_path_only rewrite ^__PATH__$ __PATH__/ permanent;
|
||||
location __PATH__/ {
|
||||
|
||||
# Path to source
|
||||
alias __FINALPATH__/;
|
||||
|
||||
index index.php;
|
||||
|
||||
try_files $uri $uri/ index.php;
|
||||
location ~ [^/]\.php(/|$) {
|
||||
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
|
||||
fastcgi_pass unix:/var/run/php/php__PHPVERSION__-fpm-__NAME__.sock;
|
||||
|
||||
fastcgi_index index.php;
|
||||
include fastcgi_params;
|
||||
fastcgi_param REMOTE_USER $remote_user;
|
||||
fastcgi_param PATH_INFO $fastcgi_path_info;
|
||||
fastcgi_param SCRIPT_FILENAME $request_filename;
|
||||
}
|
||||
|
||||
# Include SSOWAT user panel.
|
||||
include conf.d/yunohost_panel.conf.inc;
|
||||
}
|
||||
```
|
||||
|
||||
* **`proxy_pass`** in Python, Node.js, Go and Java applications:
|
||||
|
||||
```nginx
|
||||
#sub_path_only rewrite ^__PATH__$ __PATH__/ permanent;
|
||||
location __PATH__/ {
|
||||
|
||||
proxy_pass http://127.0.0.1:__PORT__/;
|
||||
proxy_redirect off;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Host $server_name;
|
||||
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
}
|
||||
```
|
||||
|
||||
#### Install script
|
||||
|
||||
We must modify `conf/nginx.conf` file with application arguments. For this, we use generic terms `YNH_EXAMPLE_PATH` that we modify by desired values with `sed` command:
|
||||
|
||||
```bash
|
||||
sed -i "s@YNH_EXAMPLE_PATH@$path@g" ../conf/nginx.conf
|
||||
sed -i "s@YNH_EXAMPLE_PORT@$port@g" ../conf/nginx.conf
|
||||
sed -i "s@YNH_EXAMPLE_DOMAIN@$domain@g" ../conf/nginx.conf
|
||||
```
|
||||
We must move that configuration file in NGINX configuration, then reload NGINX configuration:
|
||||
|
||||
```bash
|
||||
cp ../conf/nginx.conf /etc/nginx/conf.d/$domain.d/$app.conf
|
||||
sudo service nginx reload
|
||||
```
|
||||
|
||||
If NGINX won't restart, it's possible that this configuration file isn't right.
|
||||
|
||||
#### Remove script
|
||||
|
||||
We must remove NGINX configuration of this application, then reload NGINX configuration:
|
||||
|
||||
```bash
|
||||
rm -f /etc/nginx/conf.d/$domain.d/$app.conf
|
||||
sudo service nginx reload
|
||||
```
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
title: Multi-instances
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_multiinstance'
|
||||
---
|
||||
|
||||
Le multi-instance est la capacité d’une application à être installée plusieurs fois.
|
||||
|
||||
#### Scripts
|
||||
Lorsque YunoHost installe l’application, il passe au script dans la variable `$YNH_APP_INSTANCE_NAME` la valeur `id__n` avec l’identifiant de l’application `id` provenant du manifeste et `n` un nombre incrémentée à chaque nouvelle instance de l’application.
|
||||
|
||||
**Par exemple** : dans le script Roundcube, il faut nommer la base de données `roundcube`, le dossier d’installation `roundcube` et la [configuration NGINX](/packaging_apps_nginx_conf) `roundcube`. De cette manière, la seconde installation de Roundcube ne rentrera pas en conflit avec la première, et sera installée dans la base de données `roundcube__2`, dans le répertoire `roundcube__2`, et avec la configuration NGINX `roundcube__2`.
|
||||
|
||||
|
||||
Récupération de l'identifiant de l'app (incluant l'id multi-instance) :
|
||||
```bash
|
||||
app=$YNH_APP_INSTANCE_NAME
|
||||
```
|
||||
|
||||
#### Manifeste
|
||||
Passer la variable `multi_instance` à `true` dans le [manifeste](/packaging_apps_manifest) :
|
||||
```json
|
||||
"multi_instance": true,
|
||||
```
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
---
|
||||
title: Multi-instances
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_multiinstance'
|
||||
---
|
||||
|
||||
Multi-instance is application capacity to be installed several times.
|
||||
|
||||
#### Scripts
|
||||
When YunoHost installs the application, it passes `$YNH_APP_INSTANCE_NAME` var to the script, set to value `id__n` with the application `id` coming from the manifest and `n` being an integer incremented each time a new instance of the application is installed.
|
||||
|
||||
**E.g.** in the Roundcube script, database is called `roundcube`, the install directory `roundcube` and the [NGINX configuration](/packaging_apps_nginx_conf) `roundcube`. This way, the second instance of Roundcube will not conflict with the first one, and will be installed in the `roundcube__2` database, in the `roundcube__2`directory, and with the `roundcube__2` NGINX configuration.
|
||||
|
||||
Retrieve app identifier (including the multi-instance id):
|
||||
```bash
|
||||
app=$YNH_APP_INSTANCE_NAME
|
||||
```
|
||||
|
||||
#### Manifest
|
||||
Set `multi_instance` variable to `true` in the [manifest](/packaging_apps_manifest):
|
||||
```json
|
||||
"multi_instance": true,
|
||||
```
|
||||
|
|
@ -1,156 +0,0 @@
|
|||
---
|
||||
title: Actions
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_actions'
|
||||
---
|
||||
|
||||
<div class="alert alert-warning">For now, all those features are <b>EXPERIMENTAL</b>
|
||||
and aren't ready for production and are probably going to change again, if you
|
||||
still decide to use them don't expect them to be stable and follow to core
|
||||
development of YunoHost otherwise <b>they might randomly breaks on your apps</b>
|
||||
</div>
|
||||
|
||||
Applications "actions" is a packaging feature that allow you to ship with your
|
||||
application a list of "actions" executable from both the cli and the admin
|
||||
interfaces.
|
||||
|
||||
"actions" are a list of custom commands that, optionally, has arguments (like
|
||||
the installation script of an application has arguments) and once called will
|
||||
called a specific selected command with those arguments. Like an "actions"
|
||||
restart service with a argument "service name" could called the command
|
||||
`systemctl restart $some_service` (but don't that specific action in your app,
|
||||
it's just for example purpose).
|
||||
|
||||
Like the installation page generated from the manifest those actions can accept
|
||||
a list of arguments.
|
||||
|
||||
Their main purpose is to expose procedures that a sysadmin would normally do on
|
||||
CLI but that your application user would want to do but don't have the
|
||||
knowledge to do by themselves via ssh (or are just too lazy for that).
|
||||
|
||||
For example those could be:
|
||||
|
||||
* importing data in a application
|
||||
* generate a custom backup
|
||||
* start a procedure like synchronising file with the file system (nextcloud for example)
|
||||
* purge a local cache
|
||||
* restart some services
|
||||
* modify a theme
|
||||
|
||||
Actions looks like this in the admin interface:
|
||||
|
||||
|
||||
|
||||
## How to add actions to your application
|
||||
|
||||
Adding actions to your application is pretty simple as it is very similar to
|
||||
writing your manifest for the application installation.
|
||||
|
||||
You need to write an `actions.toml` file in your application at the root level
|
||||
like the `manifest.toml`/`manifest.json`.
|
||||
|
||||
<div class="alert alert-info">
|
||||
The arguments are written in **[YunoHost Arguments
|
||||
Format](/packaging_apps_arguments_format)** like in `manifest.toml/json`
|
||||
</div>
|
||||
|
||||
The general pattern looks like this:
|
||||
|
||||
```toml
|
||||
[first_action]
|
||||
name = "some name"
|
||||
description = "some description that will be displayed"
|
||||
|
||||
# can be a bash command like so:
|
||||
command = "echo pouet $YNH_ACTION_FIRST_ARGUMENT"
|
||||
# or a path to a script like
|
||||
command = "/path/to/some/stuff --some-flag $YNH_ACTION_FIRST_ARGUMENT"
|
||||
|
||||
user = "root" # optional
|
||||
cwd = "/" # optional, "current working directory", by default it's "/etc/yunohost/apps/the_app_id"
|
||||
# also the variable "$app" is available in this variable and will be replace with the app id
|
||||
# for example you can write "/var/www/$app"
|
||||
accepted_return_codes = [0, 1, 2, 3] # optional otherwise only "0" will be a non enorous return code
|
||||
|
||||
[first_action.arguments]
|
||||
# here, you put a list of arguments exactly like in manifest.toml/json
|
||||
[first_action.arguments.first_argument]
|
||||
type = "string"
|
||||
ask.en = "service to restart"
|
||||
example = "nginx"
|
||||
|
||||
... # add more arguments here if needed
|
||||
# you can also have actions without arguments
|
||||
|
||||
[another_action]
|
||||
name = "another name"
|
||||
command = "systemctl restart some_service"
|
||||
|
||||
[another_action.arguments]
|
||||
[another_action.arguments.argument_one]
|
||||
type = "string"
|
||||
ask.en = "some stuff"
|
||||
example = "stuff"
|
||||
|
||||
... # add more arguments here if needed
|
||||
# you can also have actions without arguments
|
||||
```
|
||||
|
||||
You can have as much actions as you want and from zero to as many arguments you want.
|
||||
|
||||
If you prefer, you can also write your actions in JSON like manifest.json:
|
||||
|
||||
```json
|
||||
[{
|
||||
"id": "restart_service",
|
||||
"name": "Restart service",
|
||||
"command": "echo pouet $YNH_ACTION_SERVICE",
|
||||
"user": "root", # optional
|
||||
"cwd": "/", # optional
|
||||
"accepted_return_codes": [0, 1, 2, 3], # optional
|
||||
"description": {
|
||||
"en": "a dummy stupid exemple or restarting a service"
|
||||
},
|
||||
"arguments": [
|
||||
{
|
||||
"name": "service",
|
||||
"type": "string",
|
||||
"ask": {
|
||||
"en": "service to restart"
|
||||
},
|
||||
"example": "nginx"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
... # other action
|
||||
}]
|
||||
```
|
||||
|
||||
## How to use actions
|
||||
|
||||
### In the admin
|
||||
|
||||
<div class="alert alert-warning">For now since those features are still
|
||||
experimental you won't find any direct links to the app actions on the app
|
||||
page</div>
|
||||
|
||||
The actions are located on https://some_domain.tld/yunohost/admin/#/apps/$app_id/actions
|
||||
|
||||
## With the CLI
|
||||
|
||||
The CLI API is very similar to application installation. You have 2 commands:
|
||||
|
||||
* `yunohost app list $app`
|
||||
* `yunohost app run $app $action_id` ("$action_id" is the this between "[]"
|
||||
like "[another_action]" in the example)
|
||||
|
||||
`list` will obviously give you all actions for an application.
|
||||
|
||||
`run` will run an existing action for an application and will ask, if needed,
|
||||
values for arguments. Like with `yunohost app install` you can use the `-a` and
|
||||
pass arguments in the HTTP POST arguments format (like
|
||||
`&path=/app&domain=domain.tld&other_value=stuff`)
|
||||
|
|
@ -1,310 +0,0 @@
|
|||
---
|
||||
title: Configuration panel
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_config_panel'
|
||||
---
|
||||
|
||||
<div class="alert alert-warning">For now, all those features are <b>EXPERIMENTAL</b>
|
||||
and aren't ready for production and are probably going to change again, if you
|
||||
still decide to use them don't expect them to be stable and follow to core
|
||||
development of YunoHost otherwise <b>they might randomly breaks on your apps</b>
|
||||
</div>
|
||||
|
||||
Configuration panel, or "config_panel", is a way for an application to ship a
|
||||
custom configuration panel available in the YunoHost's admin interface for the
|
||||
application. This is generally used to replace the "you need to manually edit
|
||||
this configuration file (or files) in whatever format/language for this
|
||||
application in cli and do all those complex commands" to "just use to
|
||||
configuration panel to change the options of the application".
|
||||
|
||||
Yes, this is one place to add this so asked "how can I make my application from
|
||||
public to private and vice versa" user request.
|
||||
|
||||
config_panel is probably the most complex YunoHost apps feature as you'll need
|
||||
to write both a description of the panel in toml and a script that will need to
|
||||
both work in a "display mode" and "handle inputs" mode. But this is still very
|
||||
doable and very worth it if you need it.
|
||||
|
||||
Here how it looks like in the admin interface:
|
||||
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
### Admin interface
|
||||
|
||||
The configuration panel for an application can be accessed with this URL:
|
||||
|
||||
https://my_domain.tld/yunohost/admin/#/apps/$app_id/config-panel
|
||||
|
||||
<div class="alert alert-warning">For now since those features are still
|
||||
experimental you won't find any direct links to the app actions on the app
|
||||
page</div>
|
||||
|
||||
### CLI
|
||||
|
||||
For now the CLI API for the config panel is not very good at all, you can still
|
||||
use it but it's really impracticable.
|
||||
|
||||
* `yunohost app config show-panel $app_id` will show the panel. **But for now
|
||||
it's very broken and will ask question for unfilled value of the panel**.
|
||||
|
||||
* `yunohost app config apply` will call the script with apply and... no values
|
||||
since you aren't passing them, except if you are ready to play with the `-a`
|
||||
flag and pass every global value in the HTTP POST format (protip: you don't)
|
||||
|
||||
In conclusion: don't use the CLI for now, we need to design something better.
|
||||
|
||||
## How to add a config_ panel to your application
|
||||
|
||||
### config_panel.toml
|
||||
|
||||
First, you need to write a `config_panel.toml` (or `config_panel.json` if you
|
||||
REALLY want to but we really don't recommend it as it is very error prone and
|
||||
frustrating to write by hand) that will be located at the root of you
|
||||
application, next to the manifest.json/toml. It looks like this:
|
||||
|
||||
<div class="alert alert-info">
|
||||
The options are written in **[YunoHost Arguments
|
||||
Format](/packaging_apps_arguments_format)** like in `manifest.toml/json`
|
||||
</div>
|
||||
|
||||
```toml
|
||||
version = "0.1" # version number, not used yet but important
|
||||
name = "name that will be displayed on the admin"
|
||||
|
||||
[section_id]
|
||||
name = "name of the section that will be displayed"
|
||||
|
||||
[section_id.sub_section_id]
|
||||
name = "sub section"
|
||||
|
||||
# those arguments are in yunohost argument format like manifest.json
|
||||
[section_id.sub_section_id.option_id]
|
||||
ask.en = "the text displayed for the option"
|
||||
type = "argument_option"
|
||||
default = true
|
||||
help = "A public Leed will be accessible for third party apps.<br>By turning on 'anonymous readers' in Leed configuration, you can made your feeds public."
|
||||
|
||||
[section_id.sub_section_id.another_option_id]
|
||||
...
|
||||
|
||||
[section_id.another_sub_section_id]
|
||||
name = "stuff"
|
||||
|
||||
[another_section_id]
|
||||
name = "stuff"
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
And a real world example with the rendered admin:
|
||||
|
||||
|
||||
|
||||
As a text format:
|
||||
|
||||
```toml
|
||||
version = "0.1"
|
||||
name = "Leed configuration panel"
|
||||
|
||||
[main]
|
||||
name = "Leed configuration"
|
||||
|
||||
[main.is_public]
|
||||
name = "Public access"
|
||||
|
||||
# those arguments are in yunohost argument format
|
||||
[main.is_public.is_public]
|
||||
ask.en = "Is it a public website ?"
|
||||
type = "boolean"
|
||||
default = true
|
||||
help = "A public Leed will be accessible for third party apps.<br>By turning on 'anonymous readers' in Leed configuration, you can made your feeds public."
|
||||
|
||||
|
||||
[main.overwrite_files]
|
||||
name = "Overwriting config files"
|
||||
|
||||
[main.overwrite_files.overwrite_nginx]
|
||||
ask.en = "Overwrite the nginx config file ?"
|
||||
type = "boolean"
|
||||
default = true
|
||||
help = "If the file is overwritten, a backup will be created."
|
||||
|
||||
[main.overwrite_files.overwrite_phpfpm]
|
||||
ask.en = "Overwrite the php-fpm config file ?"
|
||||
type = "boolean"
|
||||
default = true
|
||||
help = "If the file is overwritten, a backup will be created."
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
### the scripts/config script
|
||||
|
||||
To make your configuration panel functional you need write a "config" script
|
||||
that will be located in the "script" folder (like the "install" script). This
|
||||
script will be called in two different occasions:
|
||||
|
||||
* when the configuration panel is displayed and yunohost needs to fill the values
|
||||
* when the configuration is modified by the user
|
||||
|
||||
Every option of the configuration panel will be sent to the script
|
||||
following this naming convention:
|
||||
|
||||
```bash
|
||||
YNH_{section_id}_{sub_section_id}_{option_id} (everything in upper case)
|
||||
```
|
||||
|
||||
For example, this option value:
|
||||
|
||||
```toml
|
||||
[main]
|
||||
name = "Leed configuration"
|
||||
|
||||
[main.is_public]
|
||||
name = "Public access"
|
||||
|
||||
# those arguments are in yunohost argument format
|
||||
[main.is_public.is_public]
|
||||
...
|
||||
```
|
||||
|
||||
Will be available under this name in the config script:
|
||||
|
||||
```bash
|
||||
YNH_CONFIG_MAIN_IS_PUBLIC_IS_PUBLIC
|
||||
```
|
||||
|
||||
Also, the same "scripts/config" script is called in both situation. To differentiate
|
||||
those situation the first argument passed to the config script is either "show"
|
||||
or "apply".
|
||||
|
||||
A common pattern to handle that is to write your script following this pattern:
|
||||
|
||||
```bash
|
||||
show_config() {
|
||||
# do stuff
|
||||
}
|
||||
|
||||
apply_config() {
|
||||
# do stuff
|
||||
}
|
||||
|
||||
case $1 in
|
||||
show) show_config;;
|
||||
apply) apply_config;;
|
||||
esac
|
||||
```
|
||||
|
||||
#### The "show" part
|
||||
|
||||
The show part is when the user ask to see the current state of the
|
||||
configuration panel (like opening to configuration panel page on the admin
|
||||
interface). The role of the scripts/config script here is to gather all the
|
||||
relevant information, by for example parsing a configuration file or querying a
|
||||
database, and communicate it to YunoHost. To do so, you need to use the helper
|
||||
`ynh_return` like so:
|
||||
|
||||
```bash
|
||||
ynh_return "YNH_CONFIG_SOME_VARIABLE_NAME=some_value"
|
||||
```
|
||||
|
||||
For example, for this config_panel:
|
||||
|
||||
```toml
|
||||
[main]
|
||||
name = "Leed configuration"
|
||||
|
||||
[main.is_public]
|
||||
name = "Public access"
|
||||
|
||||
# those arguments are in yunohost argument format
|
||||
[main.is_public.is_public]
|
||||
...
|
||||
```
|
||||
|
||||
You would do:
|
||||
|
||||
```bash
|
||||
ynh_return "YNH_CONFIG_MAIN_IS_PUBLIC_IS_PUBLIC=1"
|
||||
```
|
||||
|
||||
If you don't provide any value for a configuration **the default value will be used**.
|
||||
|
||||
Expanding our previous example you would have this scripts/config script:
|
||||
|
||||
```bash
|
||||
show_config() {
|
||||
ynh_return "YNH_CONFIG_MAIN_IS_PUBLIC_IS_PUBLIC=1"
|
||||
}
|
||||
|
||||
apply_config() {
|
||||
# do stuff
|
||||
}
|
||||
|
||||
case $1 in
|
||||
show) show_config;;
|
||||
apply) apply_config;;
|
||||
esac
|
||||
```
|
||||
|
||||
#### The "apply" part
|
||||
|
||||
The "apply" part is called when the user click on "submit" on the configuration
|
||||
page on the admin interface. This part is simpler to write:
|
||||
|
||||
- the scripts/config will be called with "apply"
|
||||
- all the values in the config panel (modified or not) are available as global
|
||||
variables in the script following the format `YNH_{section_id}_{sub_section_id}_{option_id}`
|
||||
(exactly the same than for show)
|
||||
- the script is responsible for doing whatever it wants with those information
|
||||
- once the script has succeeded, the admin interface displays the config panel
|
||||
again and triggers the same script in "show" mode
|
||||
|
||||
Expanding the previous script that could look like that:
|
||||
|
||||
```bash
|
||||
show_config() {
|
||||
ynh_return "YNH_CONFIG_MAIN_IS_PUBLIC_IS_PUBLIC=1"
|
||||
}
|
||||
|
||||
apply_config() {
|
||||
value=$YNH_CONFIG_MAIN_IS_PUBLIC_IS_PUBLIC
|
||||
# do some stuff with value
|
||||
}
|
||||
|
||||
case $1 in
|
||||
show) show_config;;
|
||||
apply) apply_config;;
|
||||
esac
|
||||
```
|
||||
|
||||
Or if you want a full useless simple script that store the value in a file,
|
||||
this can look like this:
|
||||
|
||||
```bash
|
||||
dummy_config_file="dummy_config_file.ini"
|
||||
|
||||
show_config() {
|
||||
if [ -e $dummy_config_file ]
|
||||
then
|
||||
ynh_return "YNH_CONFIG_MAIN_IS_PUBLIC_IS_PUBLIC=$(cat $dummy_config_file)"
|
||||
fi
|
||||
|
||||
# the default value will be used
|
||||
}
|
||||
|
||||
apply_config() {
|
||||
echo $YNH_CONFIG_MAIN_IS_PUBLIC_IS_PUBLIC > $dummy_config_file
|
||||
}
|
||||
|
||||
case $1 in
|
||||
show) show_config;;
|
||||
apply) apply_config;;
|
||||
esac
|
||||
```
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
---
|
||||
title: Advanced features of apps packaging
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_advanced'
|
||||
---
|
||||
|
||||
<div class="alert alert-warning">For now, all those features are <b>EXPERIMENTALS</b>
|
||||
and aren't ready for production and are probably going to change again, if you
|
||||
still decide to use them don't expect them to be stable and follow to core
|
||||
development of YunoHost otherwise <b>they might randomly breaks on your apps</b>
|
||||
</div>
|
||||
|
||||
## Actions
|
||||
|
||||
Actions allow you to ship a list of executables "actions" related to your
|
||||
application, for example that could be:
|
||||
|
||||
* import data
|
||||
* generate a custom backup
|
||||
* start a procedure
|
||||
* regenerate a local cache
|
||||
|
||||
[Full documentation](/packaging_apps_actions)
|
||||
|
||||
Example in the admin:
|
||||
|
||||
|
||||
|
||||
## Configuration Panel
|
||||
|
||||
Configuration or "config_panel" allow you to offer a custom configuration panel
|
||||
for your application integrated into YunoHost administration panel. This allow
|
||||
you to expose whatever configuration you want for your application and this is
|
||||
generally used to handle an application configuration file when this is not
|
||||
possible inside the application itself.
|
||||
|
||||
This is generally also the place where you want to add the option to make an
|
||||
application public or not.
|
||||
|
||||
[Full documentation](/packaging_apps_config_panel)
|
||||
|
||||
Example in the admin:
|
||||
|
||||
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
---
|
||||
title: Niveaux de qualité des packages d'applications YunoHost
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_levels'
|
||||
---
|
||||
|
||||
Afin de faciliter le packaging d'applications par des étapes successives à atteindre, chaque package est affublé d'un niveau de qualité, de 0 à 9.
|
||||
Un package doit satisfaire un certain nombre de critères pour atteindre chaque niveau. De plus pour atteindre un niveau, le package doit avoir préalablement atteint le niveau précédent.
|
||||
|
||||
Ce classement des applications par niveaux présente 3 avantages :
|
||||
- Le packaging d'application est d'autant plus ludique, avec des objectifs clairs à atteindre et des étapes successives.
|
||||
- Une application correctement packagée est davantage mise en avant qu'une application ne respectant pas les règles de packaging.
|
||||
- Les utilisateurs peuvent rapidement voir le niveau d'une application et ainsi savoir si le package est de bonne qualité.
|
||||
|
||||
## Résumé des niveaux
|
||||
|
||||
**Niveau 0**
|
||||
L'application ne fonctionne pas.
|
||||
|
||||
**Niveau 1**
|
||||
L'application s'installe et se désinstalle correctement dans certains cas.
|
||||
|
||||
**Niveau 2**
|
||||
L'application s'installe et se désinstalle correctement dans toutes les configurations communes.
|
||||
|
||||
**Niveau 3**
|
||||
L'application peut être mise à jour.
|
||||
|
||||
**Niveau 4**
|
||||
L'application peut-être sauvegardée et restaurée.
|
||||
|
||||
**Niveau 5**
|
||||
Le code du package d'application respecte certaines règles de syntaxe.
|
||||
|
||||
**Niveau 6**
|
||||
Le package d'application est dans l'organisation YunoHost-Apps.
|
||||
|
||||
**Niveau 7**
|
||||
Le package d'application passe avec succès l'ensemble des tests d'intégrité.
|
||||
|
||||
**Niveau 8**
|
||||
Le package d'application respecte toute les recommendations de packaging d'apps. C'est une app de très bonne qualité.
|
||||
|
||||
**Niveau 9**
|
||||
Le package d'application respecte des recommandations de packaging supérieures. Non disponible pour le moment.
|
||||
|
||||
! L'utilisation du niveau 9 est peu à peu arrêtée.
|
||||
|
|
@ -1,77 +0,0 @@
|
|||
---
|
||||
title: Quality levels of YunoHost application packages
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_levels'
|
||||
---
|
||||
|
||||
In order to facilitate the packaging of applications by providing successive steps to achieve, each package is assigned a quality level, from 0 to 9.
|
||||
A package must meet a number of criteria to reach each level. In addition, to reach a level, the package must have previously reached the previous level.
|
||||
|
||||
This classification of applications by levels has 3 advantages:
|
||||
- The application packaging is more fun, with clear objectives to achieve and successive steps.
|
||||
- A properly packaged application is put forward more than an application that does not comply with packaging rules.
|
||||
- Users can quickly see the level of an application and thus know if the package is of good quality.
|
||||
|
||||
The level is automatically computed by the automatic test suite ("the CI") which runs tests [here](https://ci-apps.yunohost.org/ci/) and results are summarized [here](https://dash.yunohost.org/appci/branch/stable).
|
||||
|
||||
<div class="alert alert-info">
|
||||
<b>
|
||||
In the application catalog of the webadmin, an application is only shown to the user if its level is at least 5. Otherwiser, users may have to enable the display of "low-quality" applications to be able to install it.
|
||||
</b>
|
||||
</div>
|
||||
|
||||
## Summary of the level definitions
|
||||
|
||||
The following summarizes the current definition of the levels.
|
||||
|
||||
The exact definitions are likely to shift over time and are heavily dependent on:
|
||||
- the [package linter](https://github.com/YunoHost/package_linter) which performs a static analysis of the app scripts and files to detect issues or deprecated practices
|
||||
- the [package check system](https://github.com/YunoHost/package_check) which actually tests the various operations (installs, upgrades, backup...)
|
||||
|
||||
#### Level 0
|
||||
|
||||
The application does not work at all.
|
||||
|
||||
#### Level 1
|
||||
|
||||
The application can be installed/removed in at least one configuration.
|
||||
|
||||
#### Level 2
|
||||
|
||||
The application can be installed/removed in all common configurations.
|
||||
|
||||
(Typically this corresponds to full domain vs. sub path installs, private/public
|
||||
installs, multi-instance installs)
|
||||
|
||||
#### Level 3
|
||||
|
||||
The application supports upgrading.
|
||||
|
||||
#### Level 4
|
||||
|
||||
The application supports backup/restore.
|
||||
|
||||
#### Level 5
|
||||
|
||||
The application triggers no errors on the package linter
|
||||
|
||||
#### Level 6
|
||||
|
||||
The application repository is part of the YunoHost-Apps organization, which allows the community to contribute to its maintainance.
|
||||
|
||||
#### Level 7
|
||||
|
||||
The application triggers no warnings on the package linter.
|
||||
|
||||
#### Level 8
|
||||
|
||||
The application is long-term good quality, meaning it's been at least level 5 in the application catalog for a certain amount of time (when writing this: level 5+ 90% of the time during the last year)
|
||||
|
||||
#### Level 9
|
||||
|
||||
The application is considered ["high-quality"](https://github.com/YunoHost/apps/blob/master/hq_validation_template.md): it is well-integrated with YunoHost (in particular SSO/LDAP) and follows the recommended development workflow.
|
||||
|
||||
! Using level 9 is being deprecated.
|
||||
|
|
@ -1,467 +0,0 @@
|
|||
---
|
||||
title: Packaging d'applications : les bonnes pratiques
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_guidelines'
|
||||
---
|
||||
|
||||
### Introduction
|
||||
Ce document a pour but de lister les différentes bonnes pratiques concernant la création de paquet d'application YunoHost.
|
||||
|
||||
!!! This page is outdated and should be reworked
|
||||
|
||||
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 statut indiquant si la règle a été validée 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 | Statut | Test | Niveau |
|
||||
|----|--------|--------|------|--------|
|
||||
| **YEP 1** | **Communiquer avec la communauté** | | | |
|
||||
| YEP 1.1 | Nommer son app et son dépot | validé | manuel | NOTWORKING (0) |
|
||||
| YEP 1.2 | Inscrire l'app sur un "répertoire" connu | validé | manuel | NOTWORKING (0) |
|
||||
| YEP 1.3 | Indiquer la licence associée au paquet | validé | AUTO | WORKING (5) |
|
||||
| YEP 1.4 | Informer sur l'intention de maintenir un paquet | brouillon | manuel | OFFICIAL (6) |
|
||||
| YEP 1.5 | Mettre à jour régulièrement le statut de l'app | brouillon | manuel | WORKING (2) |
|
||||
| YEP 1.6 | Se tenir informé sur l'évolution du packaging d'apps | validé | manuel | OFFICIAL (6) |
|
||||
| YEP 1.7 | Ajouter l'app à l'[organisation YunoHost-Apps](https://github.com/YunoHost-Apps) | validé | manuel | OFFICIAL (6) |
|
||||
| YEP 1.8 | Publier des demandes de test | validé | manuel | OFFICIAL (6) |
|
||||
| YEP 1.9 | Documenter l'app | validé | AUTO | OFFICIAL (6) |
|
||||
| YEP 1.10 | Garder un historique de version propre | brouillon | manuel | OFFICIAL (6) |
|
||||
| YEP 1.11 | Ajouter l'app au [bugtracker YunoHost](https://github.com/yunohost/issues/issues) | brouillon | manuel | OFFICIAL (NA) |
|
||||
| YEP 1.12 | Suivre le modèle de [example_ynh](https://github.com/YunoHost/example_ynh) | brouillon | manuel | OFFICIAL (8) |
|
||||
| | | | | |
|
||||
| **YEP 2** | **Stabiliser une app** | **Statut** | **Test** | **Niveau** |
|
||||
| YEP 2.1 | Respecter le format du manifeste | validé | auto | INPROGRESS (5) |
|
||||
| YEP 2.2 | Utiliser bash pour les scripts principaux | validé | auto | WORKING (1) |
|
||||
| YEP 2.3 | Sauvegarder les réponses lors de l'installation | validé | manuel | WORKING (3) |
|
||||
| YEP 2.4 | Détecter et gérer les erreurs | brouillon | manuel | WORKING (8) |
|
||||
| YEP 2.5 | Copier correctement des fichiers | brouillon | manuel | WORKING (1) |
|
||||
| YEP 2.6 | Annuler l'action si les valeurs d'entrées sont incorrectes | validé | manuel | WORKING (7) |
|
||||
| YEP 2.7 | Donner des permissions suffisantes aux instructions bash | validé | auto | WORKING (1) |
|
||||
| YEP 2.8 | Modifier correctement une configuration système | brouillon | manuel | WORKING (8) |
|
||||
| YEP 2.9 | Enlever toutes traces de l'app lors de la suppression | brouillon | manuel | WORKING (6) |
|
||||
| YEP 2.10 | Configurer les logs de l'application | brouillon | manuel | WORKING (9) |
|
||||
| YEP 2.11 | Utiliser une variable plutôt que l'app id directement | validé | manuel | OFFICIAL (9) |
|
||||
| YEP 2.12 | Utiliser les commandes pratiques (helpers) | validé | auto | OFFICIAL (5) |
|
||||
| YEP 2.13 | Traduire le paquet en anglais | brouillon | manuel | OFFICIAL (9) |
|
||||
| YEP 2.14 | Remplir correctement un fichier de conf | brouillon | manuel | OFFICIAL (9) |
|
||||
| YEP 2.15 | Suivre les instructions d'installation de l'application | validé | manuel | OFFICIAL (1) |
|
||||
| YEP 2.16 | Vérifier la disponibilité des dépendances sur ARM, x86 et x64 | validé | manuel | OFFICIAL (8) |
|
||||
| YEP 2.17 | Prendre en compte la version d'origine lors des mises à jour | validé | manuel | OFFICIAL (9) |
|
||||
| | | | | |
|
||||
| **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 (5) |
|
||||
| YEP 2.18.2 | Gérer l'installation à la racine d’un nom de domaine | validé | auto | WORKING (2) |
|
||||
| YEP 2.18.3 | Gérer l'installation sur un sous-domaine | validé | auto | WORKING (2) |
|
||||
| YEP 2.18.4 | Gérer l'installation sur un chemin `/path` | validé | auto | OFFICIAL (2) |
|
||||
| YEP 2.18.5 | Gérer la tuile YunoHost pour faciliter la navigation entre les applications | validé | manuel | OFFICIAL (8) |
|
||||
| | | | | |
|
||||
| **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 (7) |
|
||||
| YEP 3.3 | Faciliter le contrôle de l'intégrité des sources | brouillon | manuel | OFFICIAL (6) |
|
||||
| YEP 3.4 | Isoler l'app | brouillon | manuel | OFFICIAL (8) |
|
||||
| YEP 3.5 | Suivre les recommendations de la documentation de l'app | validé | manuel | OFFICIAL (6) |
|
||||
| YEP 3.6 | Mettre à jour les versions contenant des CVE | draft | manuel | OFFICIAL (6) |
|
||||
| YEP 3.7 | Modifier correctement les dépots sources | draft | manuel | NOTWORKING (0) |
|
||||
| | | | | |
|
||||
| **YEP 4** | **Intégrer une app** | **Statut** | **Test** | **Niveau** |
|
||||
| 4.1 | Lier au LDAP | validé | manuel | OFFICIAL (4) |
|
||||
| YEP 4.2 | Lier l'authentification au SSO | validé | manuel | OFFICIAL (4) |
|
||||
| YEP 4.2.1 | Déconnexion | validé | manuel | OFFICIAL (9) |
|
||||
| YEP 4.3 | Fournir un script de sauvegarde YunoHost fonctionnel | validé | auto | OFFICIAL (6) |
|
||||
| YEP 4.4 | Fournir un script de restauration YunoHost fonctionnel | validé | auto | OFFICIAL (6) |
|
||||
| YEP 4.5 | Utiliser les hooks | validé | manuel | OPTIONAL (8) |
|
||||
| YEP 4.6 | Gère le multi-instance | validé | manuel | OPTIONAL (2) |
|
||||
| YEP 4.7 | Ajouter un module à la CLI | validé | manuel | OPTIONAL |
|
||||
| YEP 4.8 | Ajouter un module à l'admin web | brouillon | manuel | OPTIONAL |
|
||||
|
||||
|
||||
### 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é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 (apps, internetcube).
|
||||
|
||||
De plus l'identifiant doit respecter l'expression régulière suivante `^[a-z0-9]((_|-)?[a-z0-9])+$`. Autrement dit, il doit respecter les règles suivantes :
|
||||
* être en minuscule
|
||||
* commencer par une lettre ou un chiffre
|
||||
* ê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 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 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.
|
||||
|
||||
Ces dépôts ont plusieurs fonctions :
|
||||
* communiquer l'existence d'un paquet ;
|
||||
* 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.
|
||||
|
||||
Pour la liste `apps.json` maintenue par l'équipe du projet YunoHost, l'inscription se fait sur [le dépôt Git "apps"](https://github.com/YunoHost/apps). D'autres listes non-officielles (notamment celles incluant des applications non-libres) peuvent exister, se réferer au [Forum](https://forum.yunohost.org) de la communauté.
|
||||
|
||||
#### 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.
|
||||
|
||||
La liste d'application apps.json n'accepte 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.
|
||||
|
||||
**NB :** Les applications non-présentes dans la liste maintenue par le projet peuvent tout de même être installées : soit manuellement via le lien de l'application, soit de manière plus intégrée via des listes non-officielles (qui peuvent être créées et maintenues par la communauté).
|
||||
|
||||
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.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:
|
||||
* suivre [la catégorie Apps packaging du forum](https://forum.yunohost.org/c/contribute-room/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)
|
||||
|
||||
#### 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.
|
||||
|
||||
Procédure de transfert : demander sur le [salon de discussion `Apps`](/chat_rooms) à être invité à l’organisation en lui fournissant le nom de son compte GitHub.
|
||||
Une fois l’invitation acceptée, [transférer son dépôt sur l’organisation en suivant ce tutoriel](https://help.github.com/articles/transferring-a-repository-owned-by-your-personal-account/#transferring-a-repository-to-another-user-account-or-to-an-organization).
|
||||
|
||||
#### 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/support/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 512 Mo de RAM)
|
||||
|
||||
#### YEP 1.10
|
||||
##### Garder un historique de version propre | brouillon | manuel | OFFICIAL |
|
||||
#### YEP 1.11
|
||||
##### Ajouter l'app au [bugtracker YunoHost](https://github.com/yunohost/issues/issues) | brouillon | manuel | OFFICIAL |
|
||||
|
||||
#### YEP 1.12
|
||||
##### Suivre le modèle de [example_ynh](https://github.com/YunoHost/example_ynh) | brouillon | manuel | OFFICIAL |
|
||||
Afin de faciliter le travail de la communauté concernant un package, il doit suivre le modèle montré par l'application d'exemple.
|
||||
Cela aidera les autres packagers à lire, modifier et débugger le paquet. De plus, cela aidera à prolonger la durée de vie du package en lui donnant un modèle standard que les autres packagers seront en mesure de comprendre rapidement au cas où un package deviendrait orphelin.
|
||||
De plus, un package ne devrait pas utiliser de code exotique ou inutilement compliqué si ce n'est pas vraiment nécessaire. Le cas échéant, cette partie du code devrait être clairement documentée.
|
||||
Gardez votre code aussi simple que possible, gardez tout ce dont un script a besoin directement dedans. Ne déplacez pas les fonctions dans un autre fichier. Restez simple et efficace.
|
||||
|
||||
### 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](/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.
|
||||
|
||||
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.
|
||||
|
||||
#### 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 |
|
||||
Les scripts install, upgrade, backup et restore doivent détecter les erreurs pour éviter la poursuite des scripts en cas d'erreur bloquante ou d'usage de variable vide.
|
||||
L'usage de trap et de `set -eu` est recommandé pour détecter et traiter les erreurs ([Discussion en cours à ce sujet](https://forum.yunohost.org/t/gestion-des-erreurs-set-e-et-ou-trap/2249/5))
|
||||
Il est nécessaire également de vérifier le contenu des variables avant les suppressions du script remove. Par exemple un `rm -Rf /var/www/$app` avec `$app` vide aurait un résultat désastreux.
|
||||
|
||||
Au début des scripts, avant toutes modifications, il faut vérifier l'existence des utilisateurs mentionné à l'installation, ainsi que la disponibilité du path demandé, la disponibilité du dossier final de l'application et la taille des mots de passe le cas échéant.
|
||||
|
||||
N'oubliez pas qu'en cas d'erreur d'installation le script de suppression sera lancé automatiquement par la CLI YunoHost.
|
||||
|
||||
#### 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 |
|
||||
Les modifications du système doivent être réversible pour que la suppression de l'application soit sans conséquences pour le système, ne laisse pas de résidus.
|
||||
Pour celà, il faut recourir autant que possible aux dossiers `.d` des configurations système. Où lorsqu'il n'est pas possible de faire autrement, d'indiquer clairement la configuration modifiée par une application et s'assurer que les modifications seront retirées lors de sa suppression.
|
||||
|
||||
#### YEP 2.9
|
||||
##### Enlever toutes traces de l'app lors de la suppression | brouillon | manuel | WORKING |
|
||||
À l’exception de dépendances (par exemple : paquets Debian) utilisés par d’autres services ou applications.
|
||||
|
||||
#### YEP 2.10
|
||||
##### Configurer les logs de l'application | brouillon | manuel | WORKING |
|
||||
Si possible, l'application doit utiliser un fichier de log, qui sera de préférence dans /var/log.
|
||||
Si le log est mis en place par le script install et non par l'application elle-même, un fichier de configuration pour log-rotate devra être ajouté pour gérer les rotations des logs de l'application.
|
||||
|
||||
#### 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 |
|
||||
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](/packaging_apps_helpers)
|
||||
* 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 |
|
||||
*Juste pour éclaircir un peu cette YEP, mais ça reste à l'état de brouillon.*
|
||||
Le but est de trouver une méthode plus fiable que sed pour modifier les fichiers de configuration. sed pouvant éventuellement avoir des effets de bord en modifiant des parties non désirées du fichier de configuration, en particulier avec l'usage de regex.
|
||||
|
||||
#### 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 |
|
||||
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.
|
||||
```bash
|
||||
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 |
|
||||
Si l'application nécessite l'ouverture d'un port, il est nécessaire de vérifier préalablement que ce port n'est pas déjà utilisé par une autre application. Le cas échéant, le script install doit être capable de trouver un autre port disponible.
|
||||
Il convient également de vérifier si le port doit être ouvert sur le routeur, au delà du réseau local. Si ce n'est pas le cas, l'argument `--no-upnp` doit être ajouté à la commande `yunohost firewall allow` afin de limiter l'ouverture du port au réseau local uniquement.
|
||||
|
||||
#### YEP 3.3
|
||||
##### Faciliter le contrôle de l'intégrité des sources | brouillon | manuel | OFFICIAL |
|
||||
L'application upstream ne doit pas être intégrée en tarball dans le dossier source du package, car cela alourdit le package et le dépôt Git et ne permet pas la vérification de l'intégrité de la source.
|
||||
La source doit donc être téléchargée depuis le site officiel, puis son intégritée doit être vérifiée avant de l'installer.
|
||||
|
||||
#### YEP 3.4
|
||||
##### Isoler l'app | brouillon | manuel | OFFICIAL |
|
||||
Afin d'éviter des effets de bords en cas de compromission éventuelle de l'application, celle-ci doit être isolée pour ne pas risquer d'impacter les autres applications.
|
||||
Pour cela, il convient d'isoler l'application dans son dossier d'exécution en restreignant son environnement par un chroot, soit par un mécanisme interne à l'application lorsque c'est possible (par exemple pour un serveur FTP), soit par l'usage de PHP-FPM.
|
||||
De même, pour restreindre la portée de l'utilisateur exécutant l'application, il est préférable d'utiliser un utilisateur dédiée à l'application. Dont les droits sont restreint à l'usage de l'application uniquement.
|
||||
Toutefois, cela ne doit pas exempter d'une restriction maximale des droits sur les fichiers de l'application. Autant que possible, les fichiers doivent appartenir à root, et l'utilisateur dédié ne doit avoir de droits d'écriture que sur les fichiers le réclamant expressément.
|
||||
|
||||
#### 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 insuffisantes.
|
||||
|
||||
#### YEP 3.6
|
||||
##### Mettre à jour les versions contenant des CVE | draft | manuel | OFFICIAL |
|
||||
Les [CVE](https://fr.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures), ou Common Vulnerabilities and Exposures, recensent les failles de sécurités communes aux applications. Les corrections de ces failles peuvent concerner l'application et il est important dans ce cas de suivre au plus près ces mises à jour.
|
||||
Plus généralement, l'application peut proposer un correctif pour une faille spécifique à elle-même.
|
||||
De manière générale, cette YEP implique de suivre un canal d'information pour suivre les mises à jour de sécurité de l'application et réagir rapidement en mettant à jour le package en conséquence.
|
||||
|
||||
Comme précisé dans la YEP 1.7, si un correctif de sécurité doit être déployé en urgence, un autre membre de YunoHost peut être amené à faire un commit sur le package si nécessaire.
|
||||
|
||||
#### YEP 3.7
|
||||
##### Modifier correctement les dépots sources | draft | manuel | OFFICIAL |
|
||||
La modification ou l'ajout des dépôts sources dans /etc/apt/sources.list ou /etc/apt/sources.list.d/ ne doit se faire que si c'est absolument nécessaire. Dans un tel cas, merci d'utiliser le pinning, afin de s'assurer que le dépôt n'aura pas une priorité supérieur aux dépôts de debian et YunoHost.
|
||||
|
||||
Dans certains cas, il pourra être préférable de télécharger directement le .deb à partir du dépôt source (avec wget par exemple), ceci est à évaluer en fonction des dépendances, de la nature et du rythme des mises à jour.
|
||||
|
||||
L'ajout des backports et des dépôts contrib est autorisée. Le paquet doit demander l'autorisation à l'usager avant de procéder à l'ajout de dépôts nonfree, et si possible, permettre l'installation de l'app sans ce dépôt.
|
||||
|
||||
Lorsque l'on désigne la distribution on doit toujours faire référence à son nom (jessie) et non pas au statut de celle-ci (stable). Sans quoi, il y a un risque le jour où debian change de version.
|
||||
|
||||
Dans tous les cas, une app ne devrait pas modifier les dépôts sources pour les placer sur testing ou une version non supportée par YunoHost (à l'heure où cette yep est rédigé, YunoHost ne supporte pas la nouvelle stable: debian stretch).
|
||||
|
||||
### 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 |
|
||||
L'application doit disposer d'un script backup pour permettre aux utilisateurs de sauvegarder l'application, sa configuration et ses données.
|
||||
|
||||
#### YEP 4.4
|
||||
##### Fournir un script de restauration YunoHost fonctionnel | validé | auto | OFFICIAL |
|
||||
L'application doit disposer d'un script restore pour permettre aux utilisateurs de restaurer une application sauvegardée préalablement avec le script backup.
|
||||
|
||||
#### YEP 4.5
|
||||
##### Utiliser les hooks | 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 |
|
||||
|
|
@ -1,452 +0,0 @@
|
|||
---
|
||||
title: Packing Applications: Good Practise Guidelines
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_guidelines'
|
||||
---
|
||||
|
||||
### Introduction
|
||||
The purpose of this document is to list the various best practices concerning the creation of YunoHost application packages.
|
||||
|
||||
!!! This page is outdated and should be reworked
|
||||
|
||||
Each good practice is numbered with a number suffixed by the letters YEP (YunoHost Enhancement Proposals), so that it can be easily referenced in the ([package checker](https://github.com/YunoHost/package_check) and [package linter](https://github.com/YunoHost/package_linter)) tools, but also during the reviews of code.
|
||||
|
||||
Each YEP is associated with:
|
||||
* a status indicating whether the rule has been validated or is still under discussion (draft, validated, refused, obsolete);
|
||||
* an indication of the type of test to be carried out (manual or auto if an automatic tool can verify);
|
||||
* an indication of the app level from which the rule is required (NOTWORKING, INPROGRESS, WORKING, OFFICIAL), some rules are optional;
|
||||
|
||||
### YEP Index
|
||||
| ID | Title | Status | Test | Level |
|
||||
| ---- | -------- | -------- | ------ | -------- |
|
||||
| ** YEP 1 ** | ** Communicate with the community ** | | | |
|
||||
| YEP 1.1 | App name and deposit | validated | manual | NOTWORKING (0) |
|
||||
| YEP 1.2 | Register the app on a known "directory" | validated | manual | NOTWORKING (0) |
|
||||
| YEP 1.3 | Indicate the license associated with the package | validated | AUTO | WORKING (5) |
|
||||
| YEP 1.4 | Inform about intention to maintain package | draft | manual | OFFICIAL (6) |
|
||||
| YEP 1.5 | Regularly update app status | draft | manual | WORKING (2) |
|
||||
| YEP 1.6 | Keeping up-to-date on the evolution of apps packaging | validated | manual | OFFICIAL (6) |
|
||||
| YEP 1.7 | Add the app to the [YunoHost-Apps Organization](https://github.com/YunoHost-Apps) | validated | manual | OFFICIAL (6) |
|
||||
| YEP 1.8 | Publish test requests | validated | manual | OFFICIAL (6) |
|
||||
| YEP 1.9 | Document the app | validated | AUTO | OFFICIAL (6) |
|
||||
| YEP 1.10 | Keep a clean version history | draft | manual | OFFICIAL (6) |
|
||||
| YEP 1.11 | Add app to [YunoHost bugtracker](https://github.com/YunoHost/issues/issues) | draft | manual | OFFICIAL (NA) |
|
||||
| YEP 1.12 | Follow the template from [example_ynh](https://github.com/YunoHost/example_ynh) | draft | manual | OFFICIAL (8) |
|
||||
| | | | | |
|
||||
| ** YEP 2 ** | ** Stabilize an app ** | ** Status ** | ** Test ** | ** Level ** |
|
||||
| YEP 2.1 | Respect the manifest format | validated | Home | INPROGRESS (5) |
|
||||
| YEP 2.2 | Using bash for main scripts | validated | Home | WORKING (1) |
|
||||
| YEP 2.3 | Save replies during installation | validated | manual | WORKING (3) |
|
||||
| YEP 2.4 | Detect and manage errors | draft | manual | WORKING (8) |
|
||||
| YEP 2.5 | Copy files correctly | draft | manual | WORKING (1) |
|
||||
| YEP 2.6 | Cancel action if input values are incorrect | validated | manual | WORKING (7) |
|
||||
| YEP 2.7 | Give sufficient permissions to bash | validated | Home | WORKING (1) |
|
||||
| YEP 2.8 | Correctly Changing a System Configuration | draft | manual | WORKING (8) |
|
||||
| YEP 2.9 | Remove all traces of the app when deleting | draft | manual | WORKING (6) |
|
||||
| YEP 2.10 | Configure application logs | draft | manual | WORKING (9) |
|
||||
| YEP 2.11 | Use a variable rather than the id app directly | validated | manual | OFFICIAL (9) |
|
||||
| YEP 2.12 | Using Helpers | validated | Home | OFFICIAL (5) |
|
||||
| YEP 2.13 | Translate the package in English | draft | manual | OFFICIAL (9) |
|
||||
| YEP 2.14 | Fill a conf file correctly | draft | manual | OFFICIAL (9) |
|
||||
| YEP 2.15 | Follow the instructions for installing the application | validated | manual | OFFICIAL (1) |
|
||||
| YEP 2.16 | Check availability of dependencies on ARM, x86 and x64 | validated | manual | OFFICIAL (8) |
|
||||
| YEP 2.17 | Take the original version into account when updating | validated | manual | OFFICIAL (9) |
|
||||
| | | | | |
|
||||
| ** YEP 2.18 ** | ** Stabilize a webapp ** | ** Status ** | ** Test ** | ** Level ** |
|
||||
| YEP 2.18.1 | Launch the script to install a webapp correctly | validated | manual | WORKING (5) |
|
||||
| YEP 2.18.2 | Manage installation at the root of a domain name | validated | Home | WORKING (2) |
|
||||
| YEP 2.18.3 | Manage installation on a subdomain | validated | Home | WORKING (2) |
|
||||
| YEP 2.18.4 | Manage installation on a path `/path` | validated | Home | OFFICIAL (2) |
|
||||
| YEP 2.18.5 | Manage the YunoHost tile for easy navigation between applications | validated | manual | OFFICIAL (8) |
|
||||
| | | | | |
|
||||
| ** YEP 3 ** | ** Secure an app ** | ** Status ** | ** Test ** | ** Level ** |
|
||||
| YEP 3.1 | Do not ask or store LDAP password | draft | manual | NOTWORKING (?) |
|
||||
| YEP 3.2 | Open a port correctly | draft | manual | WORKING (7) |
|
||||
| YEP 3.3 | Facilitating Source Integrity Control | draft | manual | OFFICIAL (6) |
|
||||
| YEP 3.4 | Isolate app | draft | manual | OFFICIAL (8) |
|
||||
| YEP 3.5 | Follow the recommendations of the app's documentation | validated | manual | OFFICIAL (6) |
|
||||
| YEP 3.6 | Update versions containing CVE | draft | manual | OFFICIAL (6) |
|
||||
| | | | | |
|
||||
| ** YEP 4 ** | ** Integrate an app ** | ** Status ** | ** Test ** | ** Level ** |
|
||||
| 4.1 | Link to LDAP | validated | manual | OFFICIAL (4) |
|
||||
| YEP 4.2 | Link authentication to SSO | validated | manual | OFFICIAL (4) |
|
||||
| YEP 4.2.1 | Sign Out | validated | manual | OFFICIAL (9) |
|
||||
| YEP 4.3 | Provide YunoHost Backup Script Functional | validated | Home | OFFICIAL (6) |
|
||||
| YEP 4.4 | Provide a YunoHost Restore Functional script | validated | Home | OFFICIAL (6) |
|
||||
| YEP 4.5 | Using Hooks | validated | manual | OPTIONAL (8) |
|
||||
| YEP 4.6 | Manage multi-instance | validated | manual | OPTIONAL (2) |
|
||||
| YEP 4.7 | Add a module to the CLI | validated | manual | OPTIONAL |
|
||||
| YEP 4.8 | Add a module to the web admin | draft | manual | OPTIONAL |
|
||||
|
||||
### YEP 1
|
||||
#### Communicating with the community
|
||||
The YEP 1 is a meta YEP, it explains what it takes to interact with the community around a YunoHost application package.
|
||||
|
||||
#### YEP 1.1
|
||||
##### App name and deposit | validated | manual | NOTWORKING |
|
||||
Each YunoHost application has an id registered in the application manifest.
|
||||
This identifier must be unique between each application packet.
|
||||
It is therefore recommended to verify its availability by consulting the list of applications referenced in the known applications repositories (official, community, internetcube).
|
||||
|
||||
In addition, the identifier must respect the regular expression `^[a-z0-9]((_|-)?[A-z0-9])+$`.
|
||||
In other words, it must respect the following rules:
|
||||
* be in lowercase
|
||||
* start with a letter or number
|
||||
* be alphanumeric (the underscore is allowed)
|
||||
* do not contain two underscores or dashes that follow one another
|
||||
* do not end with an underscore or dash
|
||||
|
||||
For application names containing spaces, virtually all current packages simply remove them without replacing them with dashes or underscores.
|
||||
|
||||
By convention, the YunoHost application repositories are always named their ID followed by the string "\_ynh". Thus one can distinguish the upstream repository of the application, the deposit of the YunoHost package. This notation also makes it possible to find applications not listed by the search engines of platforms offering version managers (GitHub for example).
|
||||
|
||||
Example: ID: Example Filing Name: example_ynh
|
||||
|
||||
#### YEP 1.2
|
||||
##### Register the app on a known "directory" | validated | manual | NOTWORKING |
|
||||
It is advised from the beginning of the packaging to register an app on one of the YunoHost application depots.
|
||||
|
||||
These deposits have several functions:
|
||||
* communicate the existence of a package;
|
||||
* indicate the latest version associated with the package (to allow the update of the app by YunoHost);
|
||||
* indicate the state of operation of the packet;
|
||||
* indicate information about the support of a package.
|
||||
|
||||
For the `apps.json` list maintained by the project team, registration is on [the git apps repository](https://github.com/YunoHost/apps). Other non-official lists may exists (including those for non-free apps for example), see more about that in the [community forum](https//forum.yunohost.org).
|
||||
|
||||
#### YEP 1.3
|
||||
##### Indicate the license associated with the package | draft | AUTO | WORKING |
|
||||
The license of the packet must be specified in a `LICENSE` file at the root of the packet. Be careful not to confuse with the license of the application that will be installed whose acronym is to be entered in the `license` field of the manifest.
|
||||
|
||||
The application list apps.json only accept packages with a free license, as well as the license for the contained application. Some free applications require non-free dependencies (example: MP3, drivers, etc.). In this case, you should add `&dep-non-free` to the acronym and if possible give details in the README.md of the package, in this case the integration will be accepted on a case-by-case basis.
|
||||
|
||||
**NB:** Apps not included in apps.json lists may still be installed: either manually with the URL to the app, or in a more practical way using non-official lists (which can be created and maintained by the community).
|
||||
|
||||
In the future, YunoHost will probably display details about the license of the application. To achieve this, the acronym must be the one from this [list of licenses listed in the SPDX](https://spdx.org/licenses/) (if there are 2 acronyms, the one containing the version number). For consistency, the case must be respected.
|
||||
|
||||
If the license is not present in the list, in this case it is necessary to indicate `free` or `non-free` depending on whether it is free or not and give the user the opportunity to inquire in the README.md (link, explanations...).
|
||||
|
||||
Example: for a GNU Lesser General Public License (LGPL), version 3 the acronym is `LGPL-3.0` if non-free dependencies are used in this case it will be necessary to put LGPL-3.0 & dep-non-free `in the manifesto.
|
||||
|
||||
If an application has modules linked to another license (Example: Odoo 9 LGPL-3.0 + a module licensed AGPL-3.0), in this case we will indicate the two licenses separated by a `&`.
|
||||
|
||||
If two separate applications are in the same installation package and have separate licenses, in this case we can use `,` to separate the licenses.
|
||||
|
||||
In both cases, the maintainer is encouraged to consider creating two separate packages. The manifest of each application is used to ask app-type questions to refer to another application already installed.
|
||||
|
||||
Reminder: a question of type `app` answers the identifier of one of the apps already installed.
|
||||
|
||||
Some interesting links to help with the choice of license:
|
||||
* [Explanatory sheets on free licenses](https://www.inria.fr/content/download/5896/48452/version/2/file/INRIA_recueil_fiches_licences_libres_vf.pdf)
|
||||
* [GNU project licensing documentation](https://www.gnu.org/licenses/licenses.html)
|
||||
* [A Guide to the GNU Project to Help Choose a License](https://www.gnu.org/licenses/license-recommendations.en.html)
|
||||
|
||||
#### YEP 1.4
|
||||
##### Inform about intention to maintain package | draft | manual | OFFICIAL |
|
||||
The maintainer of the application must undertake to maintain its app over time if he wishes it to join the list of official applications.
|
||||
This involves monitoring updates to the upstream application, adhering to the new packaging rules and responding to user requests.
|
||||
|
||||
#### YEP 1.5
|
||||
##### Regularly update app status | draft | manual | WORKING |
|
||||
#### YEP 1.6
|
||||
##### Keeping up-to-date on the evolution of apps packaging | validated | manual | OFFICIAL |
|
||||
In order to keep up with the evolution of the packaging format and best practices, it is recommended to:
|
||||
* follow [the forum's Apps category](https://forum.yunohost.org/c/contribute-room/apps-packaging)
|
||||
|
||||
To follow the evolution of YunoHost more generally:
|
||||
* join XMPP dev@conference.yunohost.org ([three days of logs are available](https://im.yunohost.org/logs/dev/))
|
||||
* follow [Annoucement category of the forum](https://forum.yunohost.org/c/announcement)
|
||||
|
||||
#### YEP 1.7
|
||||
##### Add the app to the [YunoHost-Apps Organization](https://github.com/YunoHost-Apps) | validated | manual | OFFICIAL |
|
||||
Adding an app to the [YunoHost-Apps organization](https://github.com/YunoHost-Apps) lets you share apps with other contributors who might be tempted to package the targeted application.
|
||||
|
||||
It is also a way to quickly deploy a security patch if necessary in the event that the maintainer is unavailable.
|
||||
|
||||
Transfer Procedure: Ask the [chat room](/chat_rooms) to be invited to the organization by providing the name of their GitHub account.
|
||||
Once the invitation is accepted, [transfer its deposit to the organization by following this tutorial](https://help.github.com/articles/transferring-a-repository-owned-by-your-personal-account/# Transferring-a-repository-to-another-user-account-or-to-an-organization).
|
||||
|
||||
#### YEP 1.8
|
||||
##### Publish test requests | validated | manual | OFFICIAL |
|
||||
In order to ensure the proper functioning of a package, it is necessary to publish an announcement in order to open the tests on the package. This announcement can be done on the forum in [Forum Apps category](https://forum.yunohost.org/c/apps).
|
||||
|
||||
It is recommended to indicate if some tests have not been conducted.
|
||||
|
||||
* Check package with Package linter.
|
||||
* Installation in subfolder.
|
||||
* Installation at the root of a domain or subdomain.
|
||||
* Deletion, in the 2 cases of previous installations.
|
||||
* Access to the web interface of the application, with the / final in the address, and omitting it.
|
||||
* Upgrade on the same version of the package.
|
||||
* Upgrade from an older version of the package.
|
||||
* Private installation (secured by SSO).
|
||||
* Public installation.
|
||||
* Multi-instance installation.
|
||||
* User name error.
|
||||
* Domain name error.
|
||||
* Poorly written path (path / instead of / path for example).
|
||||
* Port already used by another application.
|
||||
* Source corrupted after download.
|
||||
* Error downloading source.
|
||||
* Folder already used by another application.
|
||||
* Backup and restore.
|
||||
|
||||
#### YEP 1.9
|
||||
##### Document the app | validated | AUTO | OFFICIAL |
|
||||
Above all, it is appropriate to make a correct description of the app in the `description` field of the manifest. Keyword insertion in this description can be a good idea, as a user might be required to search (CTRL + F) among all applications.
|
||||
|
||||
There is also README.md, which must and can contain:
|
||||
* the name of the app
|
||||
* a brief summary of what it does
|
||||
* any additional installation if the script is not sufficient
|
||||
* instructions to use it (for example to connect your smartphone or computer)
|
||||
* the location to report a malfunction / request
|
||||
* the roadmap / TODO
|
||||
* possibly prerequisites in terms of RAM memories, processor etc. (some equipment has less than 512 MB of RAM)
|
||||
|
||||
#### YEP 1.10
|
||||
##### Keep a clean version history | draft | manual | OFFICIAL |
|
||||
#### YEP 1.11
|
||||
##### Add app to [YunoHost bugtracker](https://github.com/YunoHost/issues/issues) | draft | manual | OFFICIAL |
|
||||
|
||||
#### YEP 1.12
|
||||
##### Follow the template from [example_ynh](https://github.com/YunoHost/example_ynh) | draft | manual | OFFICIAL |
|
||||
In order to facilitate the work of the community regarding a package, it has to follow the template shown by the example app.
|
||||
This will help other packagers to read, modify and debug the package. Also, it will help extend the life of the package by giving it a standard template that other packagers can quickly understand in the event that a package becomes orphaned.
|
||||
As well, a package should not use exotic or uselessly complicated code if it's not really needed. If so, this part of the code should be clearly documented.
|
||||
Keep your code as easy as possible, keep everything a script needs directly into it. Do not move functions in another file. Keep it simple and efficient.
|
||||
|
||||
### YEP 2
|
||||
#### Stabilize an app
|
||||
#### YEP 2.1
|
||||
##### Respect the manifest format | validated | Home | INPROGRESS |
|
||||
The manifest allows to describe an app so that YunoHost can apply the good treatments. For more information see [dedicated documentation](/packaging_apps_manifest).
|
||||
|
||||
#### YEP 2.2
|
||||
##### Using bash for main scripts | validated | Home | WORKING |
|
||||
Action scripts (install, upgrade, remove, backup and restore) must be in the bash so that the CLI/API YunoHost can call them correctly.
|
||||
|
||||
That being said, there is nothing to prevent other scripts or function libraries from using these scripts. These are not obliged to be in bash.
|
||||
|
||||
However, careful attention must be paid to the correct display of logs of information, warning, or errors. So that a user of the CLI/API YunoHost can understand the operation of the script just executed and if necessary repair its YunoHost instance.
|
||||
|
||||
#### YEP 2.3
|
||||
##### Save the answers during the installation | validated | manual | WORKING |
|
||||
During installation, it is necessary to save each answer to the questions in the manifest. Indeed, even if at the beginning it is not necessary to write an update script, thereafter it will probably be the case. However, without the initial information, the update can be more tedious.
|
||||
|
||||
#### YEP 2.4
|
||||
##### Detecting and Managing Errors | draft | manual | WORKING |
|
||||
The install, upgrade, backup, and restore scripts must detect errors to avoid further scripting in case of blocking error or empty variable usage.
|
||||
The use of trap and `set -eu` is recommended to detect and treat errors ([Discussion in progress](https://forum.yunohost.org/t/gestion-des-erreurs-set-e-and-or-trap/2249/5))
|
||||
It is also necessary to check the contents of the variables before removing the remove script. For example, an `rm -Rf /var/www/$app` with `$app` empty would have a disastrous result.
|
||||
|
||||
At the beginning of the scripts, before any modifications, it is necessary to check the existence of the users mentioned at the installation, as well as the availability of the requested path, the availability of the final file of the application and the size of the passwords if necessary.
|
||||
|
||||
Do not forget that in case of installation error the removal script will be launched automatically by the YunoHost CLI.
|
||||
|
||||
#### YEP 2.5
|
||||
##### Copy files correctly | draft | manual | WORKING |
|
||||
#### YEP 2.6
|
||||
##### Cancel action if input values are incorrect | validated | manual | WORKING |
|
||||
Each script should verify that the input values are correct.
|
||||
|
||||
Here are some examples:
|
||||
* Check that the domain name exists
|
||||
* Check that the user exists
|
||||
* Check that the chosen path is available
|
||||
|
||||
If one of the values is incorrect, it is necessary to cancel any modifications made previously to the instance. The best thing is to do all these checks before changing the system.
|
||||
|
||||
#### YEP 2.7
|
||||
##### Give sufficient permissions to bash | validated | Home | WORKING |
|
||||
Some instructions require sudo rights. In this case, do not forget to prefix these instructions with `sudo`.
|
||||
|
||||
In other cases it is necessary to give rights using chmod and chown.
|
||||
|
||||
#### YEP 2.8
|
||||
##### Correctly changing a system configuration | draft | manual | WORKING |
|
||||
Changes to the system must be reversible so that the removal of the application is of no consequence to the system leaves no residue.
|
||||
For this purpose, the `.d` folders of the system configurations must be used as much as possible. Where it is not possible to do otherwise, clearly indicate the configuration as modified by an application and ensure that the changes will be removed when it is removed.
|
||||
|
||||
#### YEP 2.9
|
||||
##### Remove all traces of the app when deleting | draft | manual | WORKING |
|
||||
Except for dependencies (eg, Debian packages) used by other services or applications.
|
||||
|
||||
#### YEP 2.10
|
||||
##### Configure application logs | draft | manual | WORKING |
|
||||
If possible, the application should use a log file, which will preferably be in /var/log.
|
||||
If the log is set up by the install script and not by the application itself, a log-rotate configuration file will have to be added to handle the logs of the application.
|
||||
|
||||
#### YEP 2.11
|
||||
##### Using a variable rather than the app id directly | validated | manual | OFFICIAL |
|
||||
It is advisable to make the scripts as generic as possible, a good way to do this is to use a variable for the app's name to avoid it being found everywhere in scripts. This will make it easier for another package builder to use the script for another app.
|
||||
|
||||
#### YEP 2.12
|
||||
##### Using Helpers | validated | Home | OFFICIAL |
|
||||
In order to simplify packaging, standardize practices, avoid errors and increase the lifetime of a script vis-à-vis future versions of YunoHost. A set of helpers to do many actions is proposed.
|
||||
|
||||
For more information :
|
||||
* consult [helpers documentation](/packaging_apps_helpers)
|
||||
* explore [helpers directory](https://github.com/YunoHost/yunohost/tree/unstable/data/helpers.d)
|
||||
|
||||
#### YEP 2.13
|
||||
##### Translate the package in English | draft | manual | OFFICIAL |
|
||||
#### YEP 2.14
|
||||
##### Fill a conf file correctly | draft | manual | OFFICIAL |
|
||||
* Just to clear up a little this YEP, but it remains in draft form. *
|
||||
The goal is to find a more reliable method than sed to modify the configuration files. sed can possibly have edge effects by modifying unwanted parts of the configuration file, especially with the use of regex.
|
||||
|
||||
#### YEP 2.15
|
||||
##### Follow the instructions for installing the application | validated | manual | OFFICIAL |
|
||||
|
||||
#### YEP 2.16
|
||||
##### Check availability of dependencies on ARM, x86, and x64 | validated | manual | OFFICIAL |
|
||||
YunoHost installs on ARM, x86 and x64. A package should therefore be tested on these three processor architectures.
|
||||
|
||||
Some packages are not available on ARM, in this case it is advisable to study other solutions or to indicate in the README.md that the application does not work on ARM and to block the installation by detection of type d'architecture.
|
||||
|
||||
#### YEP 2.17
|
||||
##### Take the original version into account when updating | validated | manual | OFFICIAL |
|
||||
The update script must be able to run even if the previous updates have not been performed.
|
||||
|
||||
For example, it should be possible to perform update jumps from an N-x version to an N version. To do this, it is advisable to save the version numbers in the app settings.
|
||||
|
||||
### YEP 2.18
|
||||
##### Stabilizing a webapp
|
||||
The majority of YunoHost applications are web apps, but some are not. The YEP 2.18.x develop certain specificities related to the web app.
|
||||
|
||||
#### YEP 2.18.1
|
||||
##### Launch the script to install a webapp correctly | validated | manual | WORKING |
|
||||
Often a web app installs itself from forms displayed on a web page. This practice, while practical for a human, is less so for a program.
|
||||
|
||||
It is therefore necessary to check if the application does not propose a solution of installation on command line.
|
||||
|
||||
If this is not the case, the -H option of curl should be used. In some cases, DNS redirection may not be active at the time of installation.
|
||||
`` `Bash
|
||||
curl -kL -H "Host: $domain" --data "¶m1=Text1¶m2=text2" https: //localhost$path/install.php > /dev/null 2>&1
|
||||
`` `
|
||||
|
||||
#### YEP 2.18.2
|
||||
##### Manage installation at the root of a domain name | validated | Home | WORKING |
|
||||
A web app should be able to install itself at the root of a domain name.
|
||||
|
||||
#### YEP 2.18.3
|
||||
##### Manage installation on a subdomain | validated | Home | WORKING |
|
||||
A web app should be able to install itself on a subdomain directly without subfolders.
|
||||
|
||||
#### YEP 2.18.4
|
||||
##### Manage installation on a path `/path` | validated | Home | OFFICIAL |
|
||||
A web app should be able to install on a path `/path`.
|
||||
|
||||
#### YEP 2.18.5
|
||||
##### Manage the YunoHost tile to easily navigate between applications | validated | manual | OFFICIAL |
|
||||
Except in rare cases it is advisable to integrate the tile YunoHost which allows to return to the menu of the SSO. This integration is done in the NGINX configuration.
|
||||
|
||||
Some users have replaced this square with a script adding a menu at the top of each webapp.
|
||||
|
||||
### YEP 3
|
||||
#### Securing an app
|
||||
#### YEP 3.1
|
||||
##### Do not ask or store LDAP password | draft | manual | NOTWORKING |
|
||||
#### YEP 3.2
|
||||
##### Open a port correctly | draft | manual | WORKING |
|
||||
If the application requires the opening of a port, it is necessary to check beforehand that this port is not already used by another application. If so, the install script must be able to find another available port.
|
||||
It should also be checked whether the port should be open on the router, beyond the local network. If this is not the case, the `--no-upnp` argument must be added to the` yunohost firewall allow` command in order to limit the port opening to the LAN only.
|
||||
|
||||
#### YEP 3.3
|
||||
##### Facilitating Source Integrity Control | draft | manual | OFFICIAL |
|
||||
The upstream application should not be integrated into tarball in the source folder of the package, as this adds to the package and the Git repository and does not allow verification of the integrity of the source.
|
||||
The source must be downloaded from the official website, then its integrity must be checked before installing it.
|
||||
|
||||
#### YEP 3.4
|
||||
##### Isolate app | draft | manual | OFFICIAL |
|
||||
In order to avoid edges in case of possible compromise of the application, it must be insulated in order not to affect the other applications.
|
||||
To do this, it is necessary to isolate the application in its execution folder by restricting its environment by a chroot, either by a mechanism internal to the application where possible (for example for an ftp server), or by the use of phpfpm.
|
||||
Similarly, to restrict the scope of the user running the application, it is preferable to use a user dedicated to the application. Whose rights are restricted to the use of the application only.
|
||||
However, this should not exempt from a maximum restriction of rights on application files. As much as possible, the files must belong to root, and the dedicated user must have write rights only on files that specifically request it.
|
||||
|
||||
#### YEP 3.5
|
||||
##### Follow the recommendations in the app's documentation | validated | manual | OFFICIAL |
|
||||
Typically, an application provides documentation to help system administrators perform the installation. It is advisable to follow the recommendations, including the permissions to be granted per file or directory.
|
||||
|
||||
However, the package maintainer must remain vigilant, some documentation may be erroneous or insufficient.
|
||||
|
||||
#### YEP 3.6
|
||||
##### Update versions with CVE | draft | manual | OFFICIAL |
|
||||
The [CVE](https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures), or Common Vulnerabilities and Exposures, identify security vulnerabilities common to applications. The corrections of these flaws may concern the application and it is important in this case to follow these updates as closely as possible.
|
||||
More generally, the application can propose a patch for a specific vulnerability to itself.
|
||||
Generally, this YEP involves tracking an information channel to track application security updates and reacting quickly by updating the package accordingly.
|
||||
|
||||
As specified in YEP 1.7, if a security patch is to be deployed urgently, another YunoHost member may be required to commit to the package if necessary.
|
||||
|
||||
### YEP 4
|
||||
#### Embedding an app
|
||||
This meta YEP deals with the integration of an app with the YunoHost environment. Good integration is generally a guarantee of quality and comfort for users.
|
||||
|
||||
#### YEP 4.2
|
||||
##### Linking Authentication to sso | validated | manual | OFFICIAL |
|
||||
The Single Sign On makes it possible to avoid having to create the same users for each app. Thus, a YunoHost user can connect via the Single Sign On to all the apps.
|
||||
|
||||
To do this, you must link your app to the LDAP and / or use hooks to duplicate the account credentials in the app's database.
|
||||
|
||||
Once this is done, the maintainer can use the REMOTE_USER HTTP statement to check whether a user is logged on or not. In general, modules exist (whether at the level of the technology, the framework or even the app itself).
|
||||
|
||||
If required, SSOwat can be used to secure access to one or more parts of the app. It may be relevant to secure access to an administration page with the SSO rather than a `.htaccess` and make the rest of the app accessible to all visitors.
|
||||
|
||||
#### YEP 4.2.1
|
||||
##### Logout | validated | manual | OFFICIAL |
|
||||
When you click on a disconnect action within the app, it should disconnect the user from the SSO. Otherwise, there is a risk that the user will inadvertently leave an open session.
|
||||
|
||||
#### YEP 4.3
|
||||
##### Provide YunoHost Backup Script Functional | validated | Home | OFFICIAL |
|
||||
The application must have a backup script to allow users to back up the application, its configuration, and its data.
|
||||
|
||||
#### YEP 4.4
|
||||
##### Provide a functional YunoHost restoration script | validated | Home | OFFICIAL |
|
||||
The application must have a restore script to allow users to restore an application previously backed up with the backup script.
|
||||
|
||||
#### YEP 4.5
|
||||
##### Using Hooks | validated | manual | OPTIONAL |
|
||||
YunoHost offers the possibility to launch actions with each processing carried out by the command line. This can be practical in many cases.
|
||||
|
||||
Examples:
|
||||
* Add / delete a user in the app database when using `yunohost user create` or` yunohost user remove`
|
||||
* Manage the addition of a new domain name during the `yunohost domain add` action
|
||||
* Run a script after the firewall has been reloaded
|
||||
|
||||
List of 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
|
||||
|
||||
These scripts are to be placed in a `hooks` directory as in this package: https://github.com/YunoHost-Apps/owncloud_ynh/tree/master/hooks.
|
||||
|
||||
|
||||
#### YEP 4.6
|
||||
##### Manage multi-instance | validated | manual | OPTIONAL |
|
||||
It is sometimes practical to be able to install the same app several times. For example, for several different domain names.
|
||||
|
||||
However, be careful about how to handle file paths, dependencies, ports used, etc. so that there is no collision.
|
||||
|
||||
#### YEP 4.7
|
||||
##### Add a module to the CLI | validated | manual | OPTIONAL |
|
||||
You can create a module to add commands to the yunohost command line.
|
||||
|
||||
To do this, you need to add an actionmaps to `/usr/share/moulinette/actionsmap/`. This actionmaps must start with `ynh_`.
|
||||
|
||||
The packages [menu_ynh](https://github.com/YunoHost-Apps/menu_ynh/) and [subscribe_ynh](https://github.com/YunoHost-Apps/subscribe_ynh/) are old (and not up to date) can be used as the basis for this type of module.
|
||||
#### YEP 4.8
|
||||
##### Add a module to the web admin | draft | manual | OPTIONAL |
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
---
|
||||
title: Intégration continue
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_ci'
|
||||
---
|
||||
|
||||
! This page is outdated and should be reworked
|
||||
|
||||
Un serveur d'intégration continue est disponible pour tout packager souhaitant tester une application avec [Package_check](https://github.com/YunoHost/package_check).
|
||||
|
||||
[ci-apps-dev](https://ci-apps-dev.yunohost.org?classes=btn,btn-lg,btn-primary)
|
||||
|
||||
Ce serveur est libre d'accès pour chacun d'entre vous, vous avez juste besoin d'un compte.
|
||||
Pour ce faire, demandez à un membre du groupe Apps sur notre [chatroom Applications](/chat_rooms)
|
||||
|
||||
Pour créer un compte sur ce CI, vous aurez besoin de deux choses:
|
||||
- Un nom (Pour créer un utilisateur et lui donner un répertoire).
|
||||
- Une clé ssh publique (Pour votre accès au serveur).
|
||||
|
||||
Une fois cela fait, vous pourrez accéder au serveur et y déposer vos applications.
|
||||
Pour vous connecter au serveur, utilisez :
|
||||
```bash
|
||||
ssh USER@ci-apps-dev.yunohost.org -i YOUR_PRIVATE_KEY
|
||||
```
|
||||
|
||||
Vous trouverez un répertoire vide, prêt à recevoir vos applications.
|
||||
Dès que vous déposer une application dans votre répertoire, dans un délai maximum de 5 minutes, un nouveau job sera créé pour cette application et exécuté par le CI.
|
||||
Chaque fois que vous mettrez à jour cette application, un nouveau test sera exécuté.
|
||||
|
||||
Cependant, pour éviter tout problème de sécurité, votre connexion ssh sera très limitée.
|
||||
Vous ne pouvez utiliser que `sftp` ou `rsync` pour copier vos applications dans ce répertoire. `Git` n'est pas disponible, ni la plupart des commandes bash habituelles.
|
||||
Pour faciliter votre utilisation de ce CI, un petit script peut être utilisé pour copier vos applications dans votre répertoire.
|
||||
|
||||
Copiez ce [script](https://raw.githubusercontent.com/YunoHost/CI_package_check/master/dev_CI/send_to_dev_ci.sh) dans votre répertoire de travail habituel et indiquez vos informations.
|
||||
|
||||
---
|
||||
|
||||
# Autres serveurs d'intégration continue
|
||||
|
||||
Pour votre information, voici la liste de tous nos serveurs d'intégration continue.
|
||||
Ces CI sont automatiques, vous ne pouvez pas les utiliser directement. Ils travaillent seuls.
|
||||
|
||||
- [Official CI](https://ci-apps.yunohost.org): Notre CI officiel, travaillant sur un système x86-64. Il est chargé de déterminer les niveaux pour toutes les applications notées 'working'.
|
||||
- [ARM CI](https://ci-apps-arm.yunohost.org): Ce CI travaille avec plusieurs Raspberry-Pi, appartenant à des membres de la communauté YunoHost. Les tests sont exécutés sur Raspberry-Pi pour déterminer si les applications fonctionnent sur cette architecture.
|
||||
- [Unstable/Testing CI](https://ci-apps-unstable.yunohost.org): CI conçu pour effectuer des tests sur les branches Unstable et Testing de YunoHost. Son rôle est de tester ces branches avant une sortie officielle.
|
||||
- [Jessie CI](https://ci-stretch.nohost.me): CI fonctionnant sur un système Debian Jessie. Ce CI détermine si les applications fonctionnent toujours avec la version précédente de Debian et YunoHost avant la version 3.
|
||||
- [HQ CI](https://ci-apps-hq.yunohost.org): **A venir...** Ce CI exécute des tests automatiques sur les branches des applications High Quality. A l'exception de la branche master, qui est exclue de ce CI, toutes les branches ajoutées à une application High Quality seront ajoutées à ce CI pour être testées.
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
---
|
||||
title: Continuous integration
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_ci'
|
||||
---
|
||||
|
||||
! This page is outdated and should be reworked
|
||||
|
||||
A continuous integration server is available for any packager willing to test an app with [Package_check](https://github.com/YunoHost/package_check).
|
||||
|
||||
[ci-apps-dev](https://ci-apps-dev.yunohost.org?classes=btn,btn-lg,btn-primary)
|
||||
|
||||
This server is free to use for any of you, you just need an account.
|
||||
To do so, ask to a member of the Apps group on our [Applications chatroom](/chat_rooms)
|
||||
|
||||
To create an account on this CI, you'll need two things:
|
||||
- A name (To create an user and to give it a directory).
|
||||
- A public ssh key (For your access to the server).
|
||||
|
||||
When that's done, you'll be able to access the server and put your apps on it.
|
||||
To connect to the server use:
|
||||
```bash
|
||||
ssh USER@ci-apps-dev.yunohost.org -i YOUR_PRIVATE_KEY
|
||||
```
|
||||
|
||||
You will find an empty directory, ready to receive your apps.
|
||||
As soon as you push an app into your directory, in a 5 minutes maximum delay, a new job will be created for this app and executed by the CI.
|
||||
Each time you will update this app, a new test will be executed.
|
||||
|
||||
However, to prevent any security issues, your ssh connection will be very limited.
|
||||
You can only use `sftp` or `rsync` to copy your apps into that directory. `Git` isn't available, neither most of the usual bash commands.
|
||||
To ease your usage of this CI, a small script can be used to copy your apps to your directory.
|
||||
|
||||
Copy this [script](https://raw.githubusercontent.com/YunoHost/CI_package_check/master/dev_CI/send_to_dev_ci.sh) into your usual working directory and fill it with your info.
|
||||
|
||||
Make sure the content of your `check_process` file is correct then transfer your files.
|
||||
When your files have been transfered, you can monitor the CI pipeline on https://ci-apps-dev.yunohost.org.
|
||||
|
||||
---
|
||||
|
||||
# Other continuous integration servers
|
||||
|
||||
For your information, here the list of all our continuous integration servers.
|
||||
Those CI are automatic, you can't use them directly. They're working on their own.
|
||||
|
||||
- [Official CI](https://ci-apps.yunohost.org): Our official CI, working on a x86-64 system. It is in charge of determining levels for all working apps.
|
||||
- [ARM CI](https://ci-apps-arm.yunohost.org): This CI is working with multiple Raspberry-Pi, own by members of the YunoHost community. Tests are running on Raspberry-Pi to determine if apps are working on this architecture.
|
||||
- [Unstable/Testing CI](https://ci-apps-unstable.yunohost.org): CI designed to run tests on the branches Unstable and Testing of YunoHost. Its purpose is to test those branches before an official release.
|
||||
- [Jessie CI](https://ci-stretch.nohost.me): CI running on a Debian Jessie system. This CI determine is apps are still working with the previous version of Debian and YunoHost before the version 3.
|
||||
- [HQ CI](https://ci-apps-hq.yunohost.org): **Incoming...** This CI runs automatic tests on branches of High Quality apps. Except the master branch, which is exclude from this CI, all branches added to a High Quality app will be added to this CI to be tested.
|
||||
110
pages/06.contribute/10.packaging_apps/packaging_apps_intro.md
Normal file
110
pages/06.contribute/10.packaging_apps/packaging_apps_intro.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
title: Introduction to packaging
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_intro'
|
||||
---
|
||||
|
||||
This documentation is here to provide all the basic concepts and vocabulary needed to understand app packaging.i
|
||||
|
||||
We will detail what a YunoHost application package is, how it works, how to make your own package and how to find help if you need it.
|
||||
|
||||
|
||||
# 1. Packaging philosophy
|
||||
|
||||
The ability to easily install applications from a catalog is a key feature of YunoHost. While you dive in the process of YunoHost application packaging, you should remember these key principles:
|
||||
|
||||
- **The admin should not have a PhD in computer science to be able to install, configure and use your application**: try to assume that the admin doesn't know about advanced computer concepts ;
|
||||
|
||||
- **Less is more**, **Keep it simple!**: don't overcrowd the admin with a dozens technical questions ;
|
||||
|
||||
- **Things should work out of the box**: for example, the admin should not have to manually finish the installation process by manually filling in database credentials ;
|
||||
|
||||
- Yunohost app packaging is **not just about installing** sources and dependencies: it's also about maintenance (upgrade, backup, ..) and integrating the app in the YunoHost ecosystem (nginx, sso/ldap, fail2ban, application catalog, ui/ux, ...)
|
||||
|
||||
|
||||
# 2. Prerequisites
|
||||
|
||||
Before diving in, this documentation assumes that:
|
||||
|
||||
1. You already are a Yunohost admin yourself and already know what the install workflow looks like ;)
|
||||
2. You are somewhat familiar with (or are willing to learn) system administration and bash programming ;
|
||||
3. You are somewhat familiar with (or are willing to learn) Git ;
|
||||
4. You are comfortable with tinkering and debugging computer stuff in general.
|
||||
|
||||
You are also encouraged to join the [app packaging chatroom](/chat_rooms) to ask any question you may have!
|
||||
|
||||
At some point, you will also want to have a dev/test environment, either using [VirtualBox](/packaging_apps_virtualbox) or [LXC/ynh-dev](https://github.com/yunohost/ynh-dev) which is meant for the core but can totally be used for developping apps. You can also setup a dev/test VPS on your favourite hosting provider, or even develop on your prod if you like to live dangerously ;).
|
||||
|
||||
# 3. Notes about the history of YunoHost's app packaging
|
||||
|
||||
Many things in Yunohost, and Yunohost app packaging format, are historical or were designed in an organic fashion. Thus some aspects may legitimately feel old.
|
||||
|
||||
The **"v0" of app packaging** consisted in writing raw bash scripts with no real standardization / constrain.
|
||||
|
||||
Over time, recurrent steps (such as installing dependencies with apt, or setting up the nginx config) where formalized into what were called into standardized bash functions that we call "helpers". This pretty much marked **the beginning of the "v1" packaging era**.
|
||||
|
||||
Various tools where implemented to test the app and standardize their behavior.
|
||||
|
||||
After a while, a set of common practices and conventions emerged and is somewhat reflected and maintain in the `example_ynh` template application. While it is tempting for dev-oriented folks to change variable naming schemes or refactorize the structure of scripts, it is also quite important to stick to the common and seemingly arbitrary practices to ease the maintenance of all apps by any member of the packaging community!
|
||||
|
||||
Nevertheless, even though helpers existed, the inherent structure of apps was hard and boring to maintain with too many redundant pieces of code or filled with funky historical conventions. **A new v2 format** [has been designed](https://github.com/YunoHost/yunohost/pull/1289) in the hope to modernize and simplify app packaging and improve the UI/UX of YunoHost.
|
||||
|
||||
However, **a future v3 format** has yet to come to further simplify app packaging (such as taking care of nginx/systemd/... configurations, removing the need to manually write remove/backup/restore scripts, etc ...)
|
||||
|
||||
|
||||
# 4. General overview of a Yunohost app structure
|
||||
|
||||
A YunoHost app consists in a Git repository. You should have a look at the [`helloworld_ynh`](https://github.com/YunoHost-Apps/helloworld_ynh) app and [`example_ynh`](https://github.com/YunoHost/example_ynh) app to get familiar with its structure.
|
||||
|
||||
Among the file contained in a package, the most important ones are:
|
||||
|
||||
- the **app manifest** `manifest.json` <small>(possibly `.toml` in the future)</small>
|
||||
- this can be seen as the ID card of the application, containing various metadatas.
|
||||
- it also contains the questions asked during the installation of the app.
|
||||
- **scripts/** contains a bunch of bash scripts corresponding to actions exposed in YunoHost
|
||||
- `_common.sh` : common variables or custom functions included in other scripts
|
||||
- `install` / `remove` : the install and remove procedure
|
||||
- `upgrade` : the upgrade procedure
|
||||
- `backup` / `restore` : the backup/restore procedures
|
||||
- (`change_url`) :
|
||||
- **conf/** contains a bunch of configuration templates used when installing the app. Here are some example of commonly found files:
|
||||
- `app.src` : contains the URL and checksum to downlowd the application sources
|
||||
- `nginx.conf` : the nginx (=web server) configuration template for this app
|
||||
- `systemd.service` : the systemd service configuration template for this app
|
||||
- `config.json/yaml/???`: the app's configuration template
|
||||
|
||||
Roughly speaking, the install itself generally consists of the following operations (though these may vary depending on the complexity and technologies used by the app) - not necessarily in that exact order:
|
||||
|
||||
1. YunoHost fetches the package's git repository
|
||||
2. YunoHost asks to the admin the install questions defined in `manifest.toml`
|
||||
3. The admin fills the form and starts the install
|
||||
4. YunoHost provisions a bunch of technical prerequisites (called 'resources') such as:
|
||||
- initializes the app'skey/value store `settings.yml` with the admin's answers to the install form
|
||||
- creates a UNIX system user for this app
|
||||
- install apt dependencies needed for this app
|
||||
- picks up a port for internal reverse-proxying
|
||||
- initializes an empty SQL database
|
||||
- configures SSOwat permissions
|
||||
- ...
|
||||
5. The actual app's `install` script is ran and typically does:
|
||||
- fetch and deploy the app sources
|
||||
- configure the app (typically DB credentials, internal reverse-proxy port, ...)
|
||||
- add the nginx configuration
|
||||
- add the systemd configuration the app's daemon
|
||||
- starts the app daemon
|
||||
- various finialization tweaks
|
||||
6. ???
|
||||
7. Application is ready to use !
|
||||
|
||||
|
||||
# 5. Creating your very first YunoHost package
|
||||
|
||||
Unless you really want to start from scratch or from [`example_ynh`](https://github.com/YunoHost/example_ynh), one common practice is to identify an app similar to the one you're trying to package - typically because it relies on the same technologies - clone the corresponding code repository, and adapt the various files.
|
||||
|
||||
- PHP apps:
|
||||
- NodeJS apps:
|
||||
- Python apps:
|
||||
- ???
|
||||
|
|
@ -1,62 +0,0 @@
|
|||
---
|
||||
title: Introduction au packaging
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_start'
|
||||
---
|
||||
|
||||
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'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).
|
||||
|
||||
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).
|
||||
|
||||
### 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 vraie cette fois, [celle qui emploie des mots bizarres](/packaging_apps).
|
||||
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.
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
title: Introduction to packaging
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_start'
|
||||
---
|
||||
|
||||
This documentation is here to provide all the basic concepts and vocabulary needed to understand app packaging. eg: shell, parsing, system administration...
|
||||
|
||||
We will detail what a YunoHost application package is, how it works, how to make your own package and how to find help if you need it.
|
||||
|
||||
## What is a YunoHost application package
|
||||
|
||||
Before we continue, we need to define what is exactly an application package.
|
||||
|
||||
To be able to do that, we need to remember that YunoHost at its core is a server operating system whose mission is to simplify selfhosting of internet services. To accomplish that, YunoHost provides, among other things, an administration panel allowing application installation in a few clicks.
|
||||
|
||||
If you have ever installed a web application manually, you already know that the process is in reality far more complex, usually involving a lot of steps and discipline.
|
||||
|
||||
This is what application packaging is: a series of scripts that automate the installation of a web application and its configuration in order to provide the final user with a few clicks installation process.
|
||||
|
||||
### How it works
|
||||
|
||||
From the final user perspective, it is as simple as it can be:
|
||||
|
||||
1. Pick an application
|
||||
2. Fill a form
|
||||
3. Wait
|
||||
4. Application is ready to use
|
||||
|
||||
There is more to see backstage:
|
||||
|
||||
First, when the application is selected, YunoHost will retrieve the corresponding package from github. eg: [Custom Webapp](https://github.com/YunoHost-Apps/my_webapp_ynh).
|
||||
|
||||
Then, YunoHost will read the manifest.json file to know what questions to ask the user through the form.
|
||||
|
||||
These seemingly trivial questions are very important. Usually you would need to ask for the domain on which to install, the path to access, the user that will be designated administrator and the default language for the application.
|
||||
|
||||
These are critical to appropriately configure the web application during the installation process. To do so, YunoHost will retrieve the answers given by the user and send them to the installation script located in the package "*scripts*" folder.
|
||||
|
||||
The install script will handle the user answers to complete the process as you would have done manually.
|
||||
|
||||
If the user wants to delete the application, YunoHost will use the remove script from the "*scripts*" folder. It will handle the cleaning process for the user and delete all folders and configuration files that was previsouly installed by the application.
|
||||
|
||||
### What is a script?
|
||||
|
||||
Scripts used during application packaging are simply a series of bash commands.
|
||||
|
||||
### ... bash command?
|
||||
|
||||
A [bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) command is a line of text that will be interpreted by the computer and will produce a result. This is commonly refered to as a command line.
|
||||
|
||||
You can ony interact with your server through the command line as it does not provide a graphical interface. Usual access is through [ssh](/ssh).
|
||||
|
||||
Package scripts are therefore a series of bash commands as if you had typed them directly in the ssh console.
|
||||
|
||||
To learn what you can write in a bash script, you should start reading this [simple tutorial](https://debian-facile.org/doc:programmation:shells:debuter-avec-les-scripts-shell-bash) or this [more advanced one](http://aral.iut-rodez.fr/fr/sanchis/enseignement/bash/index.html).
|
||||
|
||||
### Okay, I'm good! Where do I start?
|
||||
|
||||
Before starting the packaging process, you need to successfully install the application. The script will only perform what you instruct it to do.
|
||||
|
||||
Once completed, you need to read a little bit more documentation about application packaging. [This one is more technical](/packaging_apps) but now you should understand all the wizardry.
|
||||
|
||||
### HELP! NEED BACKUP!
|
||||
|
||||
Fortunately, you are not alone in this!
|
||||
|
||||
There are other packagers like you and you can meet them on the [forum](https://forum.yunohost.org/c/apps-packaging) or the [chat](xmpp:apps@conference.yunohost.org?join).
|
||||
|
||||
Feel free to join in and ask your questions, there always will be someone to help.
|
||||
|
||||
Soon enough you'll see for yourself that packaging applications is not that hard after all.
|
||||
Loading…
Add table
Reference in a new issue