mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
202 lines
No EOL
10 KiB
Markdown
202 lines
No EOL
10 KiB
Markdown
# Packaging d’applications <img src="https://yunohost.org/images/yunohost_package.png" width=100/>
|
||
|
||
Ce document a pour but de vous apprendre à packager une application pour YunoHost.
|
||
|
||
### 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`, le Shell et d’autres notions de programmation ;
|
||
* Une [machine virtuelle ou sur un serveur distant](/install_fr) pour packager et tester son paquet.
|
||
|
||
### Contenu
|
||
Un paquet YunoHost est composé :
|
||
|
||
* d’un `manifest.json`
|
||
* d’un dossier `scripts`, composé de cinq scripts Shell `install`, `remove`, `upgrade`, `backup` 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`
|
||
|
||
<a class="btn btn-lg btn-default" href="https://github.com/YunoHost/example_ynh">Paquet de base</a> n’hésitez pas à vous en servir comme base de travail.
|
||
|
||
## Manifeste
|
||
<a class="btn btn-lg btn-default" href="packaging_apps_manifest_fr">Manifeste</a>
|
||
|
||
## Les scripts
|
||
Un paquet YunoHost doit contenir cinq scripts Shell : `install`, `remove`, `upgrade`, `backup` et `restore`.
|
||
Ces scripts seront exécutés en tant qu’`admin` sur les serveurs YunoHost.
|
||
|
||
Voici un exemple de script d’`install`:
|
||
```bash
|
||
# Retrieve arguments
|
||
domain=$1
|
||
path=$2
|
||
|
||
# Check domain/path availability
|
||
sudo yunohost app checkurl $domain$path -a roundcube
|
||
if [[ ! $? -eq 0 ]]; then
|
||
exit 1
|
||
fi
|
||
|
||
# Generate random DES key & password
|
||
deskey=$(dd if=/dev/urandom bs=1 count=200 2> /dev/null | tr -c -d '[A-Za-z0-9]' | sed -n 's/\(.\{24\}\).*/\1/p')
|
||
db_pwd=$(dd if=/dev/urandom bs=1 count=200 2> /dev/null | tr -c -d '[A-Za-z0-9]' | sed -n 's/\(.\{24\}\).*/\1/p')
|
||
|
||
# Use 'roundcube' as database name and user
|
||
db_user=roundcube
|
||
|
||
# Initialize database and store mysql password for upgrade
|
||
sudo yunohost app initdb $db_user -p $db_pwd -s $(readlink -e ../sources/SQL/mysql.initial.sql)
|
||
sudo yunohost app setting roundcube mysqlpwd -v $db_pwd
|
||
|
||
# Copy files to the right place
|
||
final_path=/var/www/roundcube
|
||
sudo mkdir -p $final_path
|
||
sudo cp -a ../sources/* $final_path
|
||
sudo cp ../conf/main.inc.php $final_path/config/
|
||
sudo cp ../conf/db.inc.php $final_path/config/
|
||
sudo mv $final_path/plugins/managesieve/config.inc.php.dist $final_path/plugins/managesieve/config.inc.php
|
||
|
||
# Change variables in Roundcube configuration
|
||
sudo sed -i "s/rcmail-ynhDESkeyTOchange/$deskey/g" $final_path/config/main.inc.php
|
||
sudo sed -i "s/yunouser/$db_user/g" $final_path/config/db.inc.php
|
||
sudo sed -i "s/yunopass/$db_pwd/g" $final_path/config/db.inc.php
|
||
sudo sed -i "s/yunobase/$db_user/g" $final_path/config/db.inc.php
|
||
|
||
# Set permissions to roundcube directory
|
||
sudo chown -R www-data: $final_path
|
||
|
||
# Modify Nginx configuration file and copy it to Nginx conf directory
|
||
sed -i "s@PATHTOCHANGE@$path@g" ../conf/nginx.conf
|
||
sed -i "s@ALIASTOCHANGE@$final_path/@g" ../conf/nginx.conf
|
||
sudo cp ../conf/nginx.conf /etc/nginx/conf.d/$domain.d/roundcube.conf
|
||
|
||
# Reload Nginx and regenerate SSOwat conf
|
||
sudo service nginx reload
|
||
sudo yunohost app ssowatconf
|
||
```
|
||
|
||
### 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és nécessaires, copier les sources et configurer tout dans l’unique script `install` (et bien sûr faire la procédure inverse dans le script `remove`).
|
||
|
||
**Attention** : pour des raisons de sécurité, le script est exécuté en tant qu’**admin** dans YunoHost. Assurez-vous de l’essayer en tant qu’**admin** et de préfixer `sudo` aux commandes requises.
|
||
|
||
### 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).
|
||
|
||
<a class="btn btn-lg btn-default" href="packaging_apps_arguments_management_fr">Gestion des arguments</a>
|
||
|
||
### Configuration Nginx
|
||
<a class="btn btn-lg btn-default" href="packaging_apps_nginx_conf_fr">Configuration Nginx</a>
|
||
|
||
### Commandes pratiques
|
||
La CLI [moulinette](/moulinette) fournit quelques outils pour faciliter le packaging :
|
||
|
||
<br>
|
||
|
||
```bash
|
||
sudo yunohost app checkport <port>
|
||
```
|
||
<blockquote>
|
||
Cette commande vérifie le port et retourne une erreur si le port est déjà utilisé.
|
||
</blockquote>
|
||
|
||
<br>
|
||
|
||
```bash
|
||
sudo yunohost app setting <id> <key> [ -v <value> ]
|
||
```
|
||
<blockquote>
|
||
C'est la commande la plus importante. Elle vous permet de stocker des réglages d’une application spécifique, afin de les réutiliser plus tard (typiquement dans le script ```upgrade```) ou pour que YunoHost puisse se configurer automatiquement (par exemple pour le SSO).
|
||
<br><br>
|
||
La commande définit la valeur si vous ajoutez ```-v <valeur>```, sinon la récupère.
|
||
<br><br>
|
||
|
||
** Quelques paramètres pratiques **<br><br>
|
||
```skipped_uris```<br><br>
|
||
Indique à SSOwat de ne pas s’occuper de la liste d’uris fournies séparées par des virgules. Celles-ci ne seront donc pas protégées et ne pourront pas utiliser le mécanisme d’authentification centralisée.<br><br>
|
||
|
||
```protected_uris```<br><br>
|
||
Protège la liste d’uris fournies séparées par des virgules. Seul un utilisateur connecté y aura accès.<br><br>
|
||
|
||
```unprotected_uris```<br><br>
|
||
Indique à SSOwat de ne pas s’occuper de la liste d’uris fournies séparées par des virgules que si l’utilisateur est connecté. Ces uris sont donc publiquement accessibles mais peuvent utiliser le mécanisme d’authentification centralisée.<br><br>
|
||
|
||
Il existe aussi `skipped_regex`, `protected_regex`, `unprotected_uris`, `unprotected_regex`.<br><br>
|
||
|
||
**Attention** : il est nécessaire de lancer `yunohost app ssowatconf` pour appliquer les effets. Les uris seront alors converties en urls et écrites dans le fichier /etc/ssowat/conf.json.<br><br>
|
||
|
||
Exemple :<br>
|
||
```yunohost app setting myapp unprotected_urls -v "/"```<br>
|
||
```yunohost app ssowatconf```<br>
|
||
Ces commandes vont désactiver le SSO sur la racine de l’aplication soit domain.tld/myapp, ceci est utile pour une application publique.
|
||
</blockquote>
|
||
|
||
<br>
|
||
|
||
```bash
|
||
sudo yunohost app checkurl <domain><path> -a <id>
|
||
```
|
||
<blockquote>
|
||
Cette commande est utile pour les applications web et vous permet d’être sûr que le chemin n’est pas utilisé par une autre application. Si le chemin est inutilisé, elle le « réserve ».
|
||
<br><br>
|
||
**Remarque** : ne pas préfixer par `http://` ou par `https://` dans le `<domain><path>`.
|
||
</blockquote>
|
||
|
||
<br>
|
||
|
||
```bash
|
||
sudo yunohost app initdb [ -d <db_name> ] [ -s <SQL_file> ] [ -p <db_pwd> ] user
|
||
<db_user> [ -p <db_pwd> ] [ -s <SQL_file> ]
|
||
```
|
||
<blockquote>
|
||
Cette commande crée une base de donnée `db_name` et un utilisateur `user` associé à cette base, possédant les permissions nécessaires à manipuler la base de donnée.
|
||
<br>
|
||
Si vous ne définissez pas de nom de base de donnée avec `-d <db_name>`, `user` est utilisé comme nom de base de donnée.
|
||
<br>
|
||
Si vous ne définissez pas de mot de passe avec `-p`, la commande en génère un et le retourne.
|
||
<br>
|
||
Si vous ajoutez un fichier SQL avec `-s`, la commande initialise la base de donnée avec les commandes SQL du fichier.
|
||
</blockquote>
|
||
|
||
<br>
|
||
|
||
```bash
|
||
sudo yunohost app ssowatconf
|
||
```
|
||
<blockquote>
|
||
Cette commande régénère la configuration du SSO. Vous devez l’appeler à la fin des scripts lorsque vous packagez une application Web.
|
||
</blockquote>
|
||
|
||
### Tests
|
||
Afin de tester votre paquet, vous pouvez exécuter votre script en tant qu’`admin` (n'oubliez pas d’ajouter les arguments requis) :
|
||
```bash
|
||
su - admin -c "/bin/bash /répertoire/de/mon/script my_arg1 my_arg2"
|
||
```
|
||
|
||
Ou vous pouvez utiliser la moulinette :
|
||
```bash
|
||
yunohost app install /répertoire/de/mon/paquet
|
||
```
|
||
Remarque : ça fonctionne aussi avec une URL Git :
|
||
```bash
|
||
yunohost app install https://github.com/auteur/mon_paquet.git
|
||
```
|
||
|
||
### Améliorer la qualité du paquet d’installation
|
||
Vous trouverez ci-dessous une liste des point à 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` ;
|
||
* 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é sur Debian Wheezy et Jessie ainsi que sur les architectures 32 bits, 64 bits et ARM ;
|
||
* Les scripts backup et restore sont présents et fonctionnels.
|
||
|
||
### 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 `App integration`](https://forum.yunohost.org/c/app-integration).
|
||
|
||
* Faire une demande d’ajout de votre application dans le [dépôt des applications](https://github.com/YunoHost/apps) afin qu’elle soit affichée dans [la liste des apps non officielles](https://yunohost.org/#/apps_in_progress_en). Préciser également son état d’avancement : `notworking`, `inprogress` ou `working`
|
||
|
||
### Officialisation d’une application
|
||
Pour qu’une application devienne officielle, elle doit être suffisamment testée, stable et fonctionner sous les architectures 64 bits, 32 bits et ARM sur Debian Wheezy et Jessie. Si ces conditions vous paraissent réunies, demandez l’[intégration officielle](https://github.com/YunoHost/apps) de votre application. |