mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
Merge branch 'YunoHost:master' into master
This commit is contained in:
Leandro Noferini
GitHub
commit
b2214cd52d
54 changed files with 1153 additions and 3473 deletions
22
pages/04.applications/10.docs/dex/app_dex.md
Normal file
22
pages/04.applications/10.docs/dex/app_dex.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
title: Dex
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs, apps
|
||||
routes:
|
||||
default: '/app_dex'
|
||||
---
|
||||
|
||||
|
||||
|
||||
[](https://install-app.yunohost.org/?app=dex) [](https://dash.yunohost.org/appci/app/dex)
|
||||
|
||||
Dex is an identity service that uses OpenID Connect to drive authentication for other apps. This YunoHost package will install Dex and setup a canonical OpenID Connect provider for your YunoHost instance, based on the LDAP user base, that can then be used as an authentification server for other YunoHost apps.
|
||||
|
||||
|
||||
## Useful links
|
||||
|
||||
+ Website: [dexidp.io](https://dexidp.io)
|
||||
+ Official documentation: [dexidp.io/docs](https://dexidp.io/docs/)
|
||||
+ Application software repository: [github.com - YunoHost-Apps/dex](https://github.com/YunoHost-Apps/dex_ynh)
|
||||
+ Fix a bug or an improvement by creating a ticket (issue): [github.com - YunoHost-Apps/dex/issues](https://github.com/YunoHost-Apps/dex_ynh/issues)
|
||||
|
|
@ -152,8 +152,8 @@ sudo su
|
|||
|
||||
groupadd multimedia
|
||||
|
||||
usermord nextcloud -a -G multimedia
|
||||
usermord jellyfin -a -G multimedia
|
||||
usermod nextcloud -a -G multimedia
|
||||
usermod jellyfin -a -G multimedia
|
||||
|
||||
chown nextcloud:multimedia -R /media/data/jellyfin
|
||||
```
|
||||
|
|
@ -193,7 +193,7 @@ Collabora permet d'éditer en ligne les documents stockés sur Nextcloud.
|
|||
|
||||
### Architectures autres qu'ARM
|
||||
|
||||
Pour les serveurs ayant une architecture autre qu'ARM (x86...), le plus simple est d'utiliser l'application [https://yunohost.org/fr/app_collabora] Collabora, présente dans le catalogue d'applications de YunoHost.
|
||||
Pour les serveurs ayant une architecture autre qu'ARM (x86...), le plus simple est d'utiliser l'application [Collabora](https://yunohost.org/fr/app_collabora), présente dans le catalogue d'applications de YunoHost.
|
||||
|
||||
Cette application n'est cependant pas compatible avec les architectures ARM. Le projet Collabora a bien développé une version spécifique ARM, mais celle-ci n'est compatible qu'avec Ubuntu, pas Debian, donc ne fonctionne pas sous YunoHost.
|
||||
|
||||
|
|
|
|||
|
|
@ -133,6 +133,12 @@ cd /var/www/nextcloud
|
|||
sudo -u nextcloud php7.3 occ files:scan --all
|
||||
```
|
||||
|
||||
Update the YunoHost setting, so automatic upgrades and backups know where the datadir is located:
|
||||
```bash
|
||||
Case A: yunohost app setting nextcloud datadir -v /media/storage
|
||||
Case B: yunohost app setting nextcloud datadir -v /media/storage/nextcloud_data/nextcloud/data/
|
||||
```
|
||||
|
||||
It's over now. Now test if everything is fine, try connecting to your Nextcloud instance, upload a file, check its proper synchronization.
|
||||
|
||||
### Nextcloud and Cloudflare
|
||||
|
|
|
|||
|
|
@ -9,12 +9,12 @@ routes:
|
|||
|
||||
Logiciel de comptabilité open source développé en PHP.
|
||||
|
||||
Toute les infos sur ce logiciel sont disponible sur le [site du projet](http://www.noalyss.eu)
|
||||
Toute les infos sur ce logiciel sont disponible sur le [site du projet](http://www.noalyss.eu).
|
||||
|
||||
Pour apprendre à l'utiliser je vous invite à lire le [wiki du projet](http://www.noalyss.eu/?page_id=46&lang=fr_FR)
|
||||
Pour apprendre à l'utiliser je vous invite à lire la [documentation utilisateur du projet](https://www.noalyss.eu/?page_id=1031).
|
||||
|
||||
Le github du module YunoHost est [ici](https://github.com/YunoHost-Apps/noalyss_ynh)
|
||||
Le GitHub du module YunoHost est [ici](https://github.com/YunoHost-Apps/noalyss_ynh).
|
||||
|
||||
Vous pouvez essayer le projet [ici](http://demo.noalyss.eu/index.php) avec les identifiants : demo /demo
|
||||
Vous pouvez essayer le projet [ici](http://demo.noalyss.eu/index.php) avec les identifiants : demo / demo
|
||||
|
||||
Enfin pour ne pas galérer comme moi. Les identifiants et mot de passe administrateur lors de la première connexion sont : phpcompta / phpcompta
|
||||
Les identifiants et mot de passe administrateur lors de la première connexion sont ceux définis à l'installation (également envoyés sur l'adresse email de l'administrateur sur votre domaine YNH).
|
||||
|
|
|
|||
|
|
@ -9,12 +9,12 @@ routes:
|
|||
|
||||
Open source accounting software developed in PHP.
|
||||
|
||||
All the information on this software is available on the [project website](http://www.noalyss.eu)
|
||||
All the information on this software is available on the [project website](http://www.noalyss.eu).
|
||||
|
||||
To learn how to use it I invite you to read the [project wiki](http://www.noalyss.eu/?page_id=46&lang=fr_FR_id=46&lang=en_EN)
|
||||
To learn how to use it I invite you to read the [user documentation of the project](https://www.noalyss.eu/?page_id=1031).
|
||||
|
||||
The github of the YunoHost module is [here](https://github.com/YunoHost-Apps/noalyss_ynh_ynh)
|
||||
The GitHub of the YunoHost module is [here](https://github.com/YunoHost-Apps/noalyss_ynh_ynh).
|
||||
|
||||
You can try the project [here](http://demo.noalyss.eu/index.php) with the identifiers: demo /demo
|
||||
You can try the project [here](http://demo.noalyss.eu/index.php) with the identifiers: demo / demo
|
||||
|
||||
I mean, not to have to struggle like me. The administrator IDs and passwords for the first login are: phpcompta / phpcompta
|
||||
The administrator IDs and passwords for the first login are those defined during the package installation (sent as a memo to the email address of this app's administrator at your YNH domain).
|
||||
|
|
|
|||
|
|
@ -39,20 +39,17 @@ You can [contribute to this list by adding something you'd like to be packaged](
|
|||
| [Bitmessage](https://bitmessage.org/) | P2P communication protocol used to send encrypted messages | [Upstream](https://github.com/Bitmessage/PyBitmessage) | |
|
||||
| Blynk | | [Upstream](https://github.com/blynkkk/blynk-library) | |
|
||||
| [Bolt](https://bolt.cm/) | Content Management Tool | | [Package Draft](https://github.com/realitygaps/bolt_ynh) |
|
||||
| [BookWyrm](https://joinbookwyrm.com/fr/) | Social reading and reviewing, decentralized with ActivityPub | [Upstream](https://github.com/mouse-reeve/bookwyrm) | [Package_Draft](https://github.com/YunoHost-Apps/bookwyrm_ynh) |
|
||||
| [Budibase](https://budibase.com/) | Low code platform for creating internal apps, workflows, and admin panels in minutes. | [Upstream](https://github.com/Budibase/budibase) | |
|
||||
| [BTCPay Server](https://btcpayserver.org) | BTCPay Server is a free and open-source Bitcoin payment processor | [Upstream](https://github.com/btcpayserver/btcpayserver) | |
|
||||
| [Cactus Comments](https://cactus.chat/) | Federated comment system, to embed into your webpages, based on the Matrix protocol. | [Upstream](https://gitlab.com/cactus-comments) | [Package Draft](https://github.com/h3ndrik/cactus-comments_ynh) |
|
||||
| [Cagette](https://www.cagette.net/) | A marketplace for local farmers and producers | [Upstream](https://github.com/CagetteNet/cagette) | |
|
||||
| [Cal.com](https://cal.com/) | Formerly Calendso. Volunteer shift management and meeting scheduling. "The open source Calendly alternative." | [Upstream](https://github.com/calcom/cal.com) | |
|
||||
| [Calckey](https://i.calckey.cloud/) | A greatly enhanced fork of Misskey with better UI/UX, security, features, and more!| [Upstream](https://codeberg.org/calckey/calckey) | [Package_Draft](https://github.com/oufmilo/calckey_ynh) |
|
||||
| [Caliopen](https://www.caliopen.org) | A unified inteface for all your private communications | | |
|
||||
| [cgit](https://git.zx2c4.com/cgit/about) | | | |
|
||||
| Chaskiq | A full featured Live Chat, Support & Marketing platform, alternative to Intercom, Drift, Crisp | [Upstream](https://github.com/chaskiq/chaskiq) | |
|
||||
| changedetection.io | Self-hosted open source change monitoring of web pages | [Upstream](https://github.com/dgtlmoon/changedetection.io) | |
|
||||
| [Chatterbox](https://element.io/solutions/chatterbox-embedded-live-chat-for-customer-service) | Embedded live chat for customer service | [Upstream]([https://github.com/sourcegraph/checkup](https://github.com/vector-im/chatterbox)) | |
|
||||
| [Chatwoot](https://www.chatwoot.com/docs/self-hosted/) | Open-source customer engagement suite, an alternative to Intercom, Zendesk, Salesforce Service Cloud | [Upstream](https://github.com/chatwoot/chatwoot) | |
|
||||
| [Chitchatter](https://chitchatter.im/) | chat p2p encrypted serverless ephemeral decentralized | [Upstream](https://github.com/jeremyckahn/chitchatter) | |
|
||||
| [CheckUp](https://sourcegraph.github.io/checkup) | | [Upstream](https://github.com/sourcegraph/checkup) | |
|
||||
| [Checkmk](https://checkmk.com/) | Checkmk provides powerful monitoring of networks, servers, clouds, containers and applications | [Upstream](https://github.com/tribe29/checkmk) | |
|
||||
| [Citadel-suite](https://www.citadel.org) | Groupware platform | | |
|
||||
|
|
@ -83,7 +80,9 @@ You can [contribute to this list by adding something you'd like to be packaged](
|
|||
| Dynette | Dynette is a dyndns server | [Upstream](https://github.com/YunoHost/dynette) | [Package Draft](https://github.com/YunoHost-Apps/dynette_ynh) |
|
||||
| DrakonHub | Online editor for Drakon diagrams | [Upstream](https://github.com/stepan-mitkin/drakonhub) | |
|
||||
| [Drawpile](https://drawpile.net) | Collaborative drawing program that allows multiple users to sketch on the same canvas simultaneously | [Upstream](https://github.com/drawpile/Drawpile) | |
|
||||
| [Earthstar-Project Server](https://earthstar-project.org/tutorials/run-a-server) | Run and configure an Earthstar server capable of syncing with other peers | [Upstream](https://github.com/earthstar-project/earthstar) | |
|
||||
| [Element Call](https://element.io/blog/element-call-beta-2-encryption-spatial-audio-walkie-talkie-mode-and-more/) | Showcase for full mesh video chat powered by Matrix | [Upstream](https://github.com/vector-im/element-call) | |
|
||||
| [Elk](https://elk.zone) | A nimble Mastodon web client. It also works with other Fediverse servers like Pleroma or GotoSocial | [upstream](https://github.com/elk-zone/elk) | |
|
||||
| Endlessh | SSH Tarpit | [upstream](https://github.com/skeeto/endlessh) | |
|
||||
| [erine.email](https://erine.email/) | | [Upstream](https://gitlab.com/mdavranche/erine.email) | |
|
||||
| [ERPnext](https://erpnext.com/) | | [Upstream](https://github.com/frappe/erpnext) | |
|
||||
|
|
@ -98,10 +97,10 @@ You can [contribute to this list by adding something you'd like to be packaged](
|
|||
| [Filestash](https://www.filestash.app/) | | [Upstream](https://github.com/mickael-kerjean/filestash) | |
|
||||
| [fishnet](https://lichess.org/get-fishnet) | Distributed Stockfish analysis for lichess.org | [Upstream](https://github.com/niklasf/fishnet) | |
|
||||
| FitTrackee | | [Upstream](https://github.com/SamR1/FitTrackee) | |
|
||||
| FlareSolverr | Proxy server to bypass Cloudflare protection | [Upstream](https://github.com/FlareSolverr/FlareSolverr) | |
|
||||
| Flask | Skeleton for flask apps | | [Package Draft](https://github.com/YunoHost-Apps/flask_ynh) |
|
||||
| [foodsoft](https://foodcoops.github.io/foodsoft-hosting/) | Manage a non-profit food cooperative | | [Package Draft](https://github.com/YunoHost-Apps/foodsoft_ynh) |
|
||||
| [Forem](https://www.forem.com/) | Forem is open source software for building communities. | [Upstream](https://github.com/forem/selfhost) | |
|
||||
| [Forgejo](https://forgejo.org/) | A self-hosted lightweight software forge. | [Upstream](https://codeberg.org/forgejo/forgejo) | |
|
||||
| [Fossil](https://www.fossil-scm.org) | | | |
|
||||
| [Fractale](https://fractale.co/) | Fractale is a platform for self-organization.| [Upstream](https://github.com/fractal6/fractal6.go) | |
|
||||
| full-text-rss | | [Upstream](https://bitbucket.org/fivefilters/full-text-rss/src/master/) | |
|
||||
|
|
@ -164,6 +163,7 @@ You can [contribute to this list by adding something you'd like to be packaged](
|
|||
| [Lessy](https://lessy.io) | | [Upstream](https://github.com/lessy-community/lessy) | |
|
||||
| [Librarian](https://lbry.bcow.xyz/) | An alternative frontend for LBRY/Odysee | [Upstream](https://codeberg.org/librarian/librarian) | |
|
||||
| [LibreTranslate](https://libretranslate.com/) | Translation API | [Upstream](https://github.com/uav4geo/LibreTranslate) | [Package Draft](https://github.com/YunoHost-Apps/libretranslate_ynh) |
|
||||
| Lichen | Gemtext to HTML translator | [Upstream](https://git.sensorstation.co/lichen.git) | |
|
||||
| [Lila](https://lichess.org/) | Online chess game server | [Upstream](https://github.com/ornicar/lila) | |
|
||||
| [Lingva Translate](https://lingva.ml/) | Alternative front-end for Google Translate | [Upstream](https://github.com/TheDavidDelta/lingva-translate) | |
|
||||
| [LiquidSoap](https://www.liquidsoap.info/) | Audio and video streaming language | [Upstream](https://github.com/savonet/liquidsoap) | |
|
||||
|
|
@ -217,7 +217,6 @@ You can [contribute to this list by adding something you'd like to be packaged](
|
|||
| [OX Open-Xchange](https://www.open-xchange.com) | Linux groupware solution | [Upstream](https://github.com/open-xchange/) | |
|
||||
| [pd3f](https://pd3f.com/) | PDF text extraction (OCR) pipeline using machine-learning | [Upstream](https://github.com/pd3f/pd3f) | |
|
||||
| [Padloc](https://padloc.app/) | Simple, secure password and data management for individuals and teams | [Upstream](https://github.com/padloc/padloc) | |
|
||||
| Paperless-ng | | [Upstream](https://github.com/jonaswinkler/paperless-ng) | |
|
||||
| [Paperwork](https://paperwork.cloud) | | [Upstream](https://github.com/paperwork/paperwork) | |
|
||||
| [Passbolt](https://www.passbolt.com) | Password manager | [Upstream](https://github.com/passbolt) | |
|
||||
| Pelias | | [Upstream](https://github.com/pelias/pelias) | |
|
||||
|
|
@ -282,7 +281,6 @@ You can [contribute to this list by adding something you'd like to be packaged](
|
|||
| sickbeard | Automatic TV show downloader | | [Package Draft](https://github.com/YunoHost-Apps/sickbeard_ynh) |
|
||||
| [sickrage](https://sickchill.github.io/) | Automatic TV shows downloader | | [Package Draft](https://github.com/YunoHost-Apps/sickrage_ynh) |
|
||||
| [Signal Proxy](https://signal.org/blog/help-iran-reconnect/) | Fight censorship and bypass traffic securely to the Signal service | [Upstream](https://github.com/signalapp/Signal-TLS-Proxy) | |
|
||||
| [Signature PDF](https://pdf.24eme.fr) | A free open source online PDF signing software | [Upstream](https://github.com/24eme/signaturepdf) | [Package Draft](https://github.com/YunoHost-Apps/signaturepdf_ynh) |
|
||||
| simpad | Simple markdown editor | [Upstream](https://github.com/beli3ver/SiMPad) | [Package Draft](https://github.com/YunoHost-Apps/simpad_ynh) |
|
||||
| [SimpleLogin](https://simplelogin.io) | Privacy-first e-mail forwarding and identity provider service | [Upstream](https://github.com/simple-login/app) | |
|
||||
| [SimplyTranslate-Web](https://simplytranslate.org/) | This is a simple web interface for SimplyTranslate | [Upstream](https://codeberg.org/SimpleWeb/SimplyTranslate-Web) | |
|
||||
|
|
@ -319,12 +317,12 @@ You can [contribute to this list by adding something you'd like to be packaged](
|
|||
| Tinylist | | [Upstream](https://github.com/baggachipz/tinylist) | |
|
||||
| [TMate](https://tmate.io/) | | [Upstream](https://github.com/tmate-io/tmate) | |
|
||||
| torrelay | | | [Package Draft](https://github.com/matlink/torrelay_ynh) |
|
||||
| Tracim | | [Upstream](https://github.com/tracim/tracim) | |
|
||||
| Traccar | Modern GPS Tracking Platform | [Upstream](https://github.com/traccar/traccar) | |
|
||||
| transpay | Interface to receive and manage donations with Stripe | | [Package Draft](https://github.com/YunoHost-Apps/transpay_ynh) |
|
||||
| transwhat | A gateway to WhatsApp from Jabber | | [Package Draft](https://github.com/Josue-T/transwhat_ynh) |
|
||||
| [Tryton](https://www.tryton.org/) | A solid ERP system | | |
|
||||
| [trivy](https://www.aquasec.com/products/trivy/) | OSS Vulnerability and Misconfiguration Scanning. |[Upstream](https://github.com/aquasecurity/trivy) | |
|
||||
| tubesync | Syncs YouTube channels and playlists to a locally hosted media server | [Upstream](https://github.com/meeb/tubesync) | |
|
||||
| tutao | End-to-end encrypted e-mail client | [Upstream](https://github.com/tutao/tutanota/) | [Package Draft](https://github.com/YunoHost-Apps/tutao_ynh) |
|
||||
| [Twake](https://twake.app/fr)| All of the organizational tools you need to make your projects succeed brought together on one platform.| | |
|
||||
| Twister | | [Upstream](https://github.com/miguelfreitas/twister-core/) | |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
170
pages/06.contribute/10.packaging_apps/10.manifest/manifest.md
Normal file
170
pages/06.contribute/10.packaging_apps/10.manifest/manifest.md
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
---
|
||||
title: Writing app manifest
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_manifest'
|
||||
---
|
||||
|
||||
The app's `manifest.toml` can be seen as the ID card of the app. It declares various basic metadata such as the id, name, description of the app, its version, install questions to be asked to the admin prior to installation, etc.
|
||||
|
||||
In this page, the data are described according to a somewhat dummy app called `helloworld`
|
||||
|
||||
|
||||
## General information
|
||||
|
||||
```toml
|
||||
packaging_format = 2
|
||||
```
|
||||
|
||||
- `packaging_format` (`int`) is the packaging version format used to package this app. Newly packaged apps are strongly encouraged to use the new "v2" format (starting with YunoHost 11.1) while older apps may still be in "v1" format.
|
||||
|
||||
```toml
|
||||
id = "helloworld"
|
||||
name = "Hello World"
|
||||
description.en = "A dummy basic app to illustrate YunoHost's app packaging."
|
||||
description.fr = "Une app simple et bidon pour illustrer comme le packaging d'app de YunoHost fonctionne"
|
||||
```
|
||||
|
||||
- `id` (`str`) is expected to be lower-case alphanumeric (and possibly `-`). This is what will be used for instance in the syntax `yunohost app install <app_id>`. This will also be the name of various folder or conf files such as `/etc/yunohost/apps/<app_id>` or `/etc/nginx/conf.d/<domain>.d/<app_id>.conf` (if applicable), and a dedicated system user.
|
||||
- `name` (`str`) is the display name of the app, shown for example in the webadmin UI or user portal. It is limited to 22 chars <small>(though not sure why this number?)</small>.
|
||||
- `description` (`dict` of `lang code`->`str`) contains *short*, *concise* descriptions of the app in different languages (at least `en`). It is limited to 150 chars. It will be displayed on the app catalog and should allow people to understand what this app is about at a glance. A more extensive description of the app can be provided in `doc/DESCRIPTION.md`.
|
||||
|
||||
```toml
|
||||
version = "0.1~ynh1"
|
||||
```
|
||||
|
||||
- `version` (`str`) is composed of the *upstream* version of the app shipped, and an `~ynhX` suffix. Changing this version is what effectively triggers an available upgrade for YunoHost instances which installed this package (hence no upgrade will be displayed as available if you forget to change it). The point of the `~ynhX` suffix is to have a way to increment the version when commiting changes unrelated to the upstream but still trigger an upgrade.
|
||||
|
||||
```toml
|
||||
maintainers = ["alexAubin"]
|
||||
```
|
||||
|
||||
- `maintainers` (`list` or `str`) may allow to declare which person should be the referring person for this package (though packages are often maintained collectively and not really used in practice). This should contain a list of easily identifiable persons (eg your Github or Matrix username)
|
||||
|
||||
## Upstream section
|
||||
|
||||
This section is meant to provide various metadata about the app upstream such that YunoHost admins can easily obtain further information regarding this app (or, kinda important, try the upstream's demo before deciding to install it).
|
||||
|
||||
Apart from the license, all fields are *optional* and should only be provided if they are relevant (e.g. don't provide `website` if the upstream project has no website...)
|
||||
|
||||
```toml
|
||||
[upstream]
|
||||
license = "WTFPL"
|
||||
website = "https://www.hello-world.com/"
|
||||
code = "https://github.com/octocat/Hello-World"
|
||||
demo = ...
|
||||
admindoc = ...
|
||||
userdoc = ...
|
||||
```
|
||||
|
||||
- `license` (`str`) : the license code of the *upstream* project. (Note that only apps based on free software will be accepted in the official YunoHost app catalog.). The license code should be [a valid SPDX identified](https://spdx.org/licenses/).
|
||||
- (optional) `website` (`url`) : the url of the upstream project's website, if there is indeed a website (please don't just copypasta the git repo url)
|
||||
- (optional) `demo` (`url`) : an url where people can try out the app before installing it (ideally maintained by the upstream project)
|
||||
- (optional) `code` (`url`) : the url of the upstream project's code repository, which is very much expected to exist for free software ... but may not exist for special "no upstream" apps ;)
|
||||
- (optional) `admindoc` (`url`) : the url of the *upstream* project's admin documentation, which may help YunoHost admins with adminstrating the app <small>(YunoHost-specific documentation can be provided in `doc/ADMIN.md`)</small>.
|
||||
- (optional) `userdoc` (`url`) : the url of the *upstream* project's user documentation, which may help YunoHost end-users with effectively using the app.
|
||||
- (optional) `cpe` (`str`) corresponds to the [Common Platform Enumerations code in NIST db](https://nvd.nist.gov/products/cpe). For example for Wekan this is `cpe:2.3:a:wekan_project:wekan`. Not really used at the moment, but may be used in the future to check for known vulnerabilities (CVE) in the app catalog.
|
||||
|
||||
## Integration section
|
||||
|
||||
This section is meant to contain info related to the relation between the app and YunoHost, or things like typical resource usage.
|
||||
|
||||
```toml
|
||||
[integration]
|
||||
yunohost = ">= 11.1"
|
||||
architectures = "all"
|
||||
multi_instance = false
|
||||
ldap = "not_relevant"
|
||||
sso = "not_relevant"
|
||||
disk = "1M"
|
||||
ram.build = "1M"
|
||||
ram.runtime = "1M"
|
||||
```
|
||||
|
||||
- `yunohost` (`str`) contains the minimum YunoHost version required for this app to work.
|
||||
- `architectures` : `"all"` OR a list of supported archs using the `dpkg --print-architecture` nomenclature, i.e. among : `amd64` (= x86 64bit), `i386` (= x86 32bit), `armhf` (= ARM 32bit), `arm64` (= ARM 64bit)
|
||||
- `multi_instance` (`bool`) : wether or not the app supports being installed multiple time <small>(in which case, during installation, the actual app id is not just the `id` of the manifest, but something like `hellowold__2`, `helloworld__3`, etc. for subsequent installs)</small>
|
||||
- `ldap` (`bool` OR `"not_relevant"`) : not to confused with the `sso` key : this corresponds to wether or not the app is configured to use YunoHost's LDAP DB as the user account DB. This should be set to `"not_relevant"` if and only if there is no notion of user account for this app (for example, Hextris). LDAP integration is often a prerequisite for the SSO to work.
|
||||
- `sso` (`bool` OR `"not_relevant"`) : not to be confused with the `ldap` key : this corresponds to wether or not a user is *automatically logged-in* on the app when logged-in on the YunoHost portal. This should be set to `"not_relevant"` if and only if there is no notion of user account for this app (for example, Hextris).
|
||||
- `disk` (size) : an *estimate* minimum disk requirement. For example: 20M, 400M, 1G, ...
|
||||
- `ram.build` (size) : an *estimate* minimum ram requirement when building the app (this may be way different than `ram.runtime` because some apps have a peak 1~2G RAM when building sometimes...). For example: 50M, 400M, 1G, ...
|
||||
- `ram.runtime` (size) : an *estimate* minimum ram requirement when the app is active and running. For example: 50M, 400M, 1G, ...
|
||||
|
||||
|
||||
## Install questions
|
||||
|
||||
This section contains questions that should be asked to the admin prior to starting the actual install
|
||||
|
||||
```toml
|
||||
[install]
|
||||
[install.domain]
|
||||
# this is a generic question - ask strings are automatically handled by YunoHost's core
|
||||
type = "domain"
|
||||
|
||||
[install.path]
|
||||
# this is a generic question - ask strings are automatically handled by YunoHost's core
|
||||
type = "path"
|
||||
default = "/helloworld"
|
||||
|
||||
[install.init_main_permission]
|
||||
# this is a generic question - ask strings are automatically handled by YunoHost's core
|
||||
type = "group"
|
||||
default = "visitors"
|
||||
|
||||
[install.prefered_pet]
|
||||
ask.en = "Do you prefer cats or dogs?"
|
||||
help.en = "Think carefully!"
|
||||
type = "string"
|
||||
choices.cat = "Cats :3 !"
|
||||
choices.dog = "Doggos <3"
|
||||
choices.both = "OMG Both ! I can't choose !"
|
||||
```
|
||||
|
||||
- `domain` and `path` (with `type = "domain"/"path"`) are classic questions to allow the admin to choose where the app is installed (in terms of web url endpoint)
|
||||
- e.g. if the admin answers `domain.tld` and `/foobar`, the app will be available under `domain.tld/foobar`
|
||||
- some webapp do require a full dedicated domain and do not support the "subpath" install scheme. In that case, you typically want to remove the `path` question entirely
|
||||
- these questions are part of YunoHost's generic app questions and therefore you do not need to define the `ask.en` strings that contain the actual question displayed in the UI along the line of "Choose a domain to install this app on"
|
||||
- `init_main_permission` is also a classic question <small>(similar to `is_public` in v1 packaging)</small> and define what user group will be able to access the app after it is installed. Typical answer are : `visitors` (= everybody including anonymous users, the app is "public"), `all_users` (= only people with a YunoHost account, the app is "private"), or any custom user group that may have been defined by the YunoHost admins prior to the install.
|
||||
- `prefered_pet` is a custom question:
|
||||
- `ask.en` defines the human-readable question to be asked (at least the english version)
|
||||
- `help.en` is an optional additional message to provide further info about this question
|
||||
- `type` is the type of question, in this case `string`
|
||||
- in this example, we don't want a free user input but choosing between `cat`, `dog` or `both` (with proper human-readable versions of these choices)
|
||||
- this will later automatically create a yunohost app setting named `prefered_pet`
|
||||
- .. and in the bash install script, the bash variable will automatically be available `$prefered_pet` with the chosen value
|
||||
|
||||
### Regarding install question types
|
||||
|
||||
FIXME : This should be way more documented in a separate section (and is also related to config panels...)
|
||||
|
||||
The full list of question types is : `string`, `text`, `select`, `tags`, `email`, `url`, `date`, `time`, `color`, `password`, `path`, `boolean`, `domain`, `user`, `group`, `number`, `range`, `alert`, `markdown`, `file`, `app`.
|
||||
|
||||
`password`-type questions have special behavior and are NOT automatically saved as setting (user-chosen password should ideally not be stored, at least not hashed...)
|
||||
|
||||
|
||||
## Resource system
|
||||
|
||||
The resource section corresponds to recurring app needs that are to be provisioned/deprovisioned by the core of YunoHost. They include for example: system user, apt dependencies, install dir, data dir, port, permissions, SQL database... Each resource is to be provisioned *before* running the install script, deprovisioned *after* the remove script, and automatically upgraded if needed before running the upgrade script (or provisionned if introduced in the new app version, or deprovisioned if removed w.r.t. the previous app version)
|
||||
|
||||
```toml
|
||||
[resources]
|
||||
[resources.system_user]
|
||||
|
||||
[resources.install_dir]
|
||||
|
||||
[resources.permissions]
|
||||
main.url = "/"
|
||||
|
||||
[resources.apt]
|
||||
packages = "nyancat, lolcat, sl"
|
||||
```
|
||||
|
||||
In this example:
|
||||
- `system_user`: a system (unix) user will be created for this app, using the app id as username.
|
||||
- `install_dir`: an install dir will be initialized, named `/var/www/$app` by default. Additional `owner` and `group` property allow to change the owner/group and r/w/x permissions on the created folder.
|
||||
- `permissions`: an SSOwat `$app.main` permission will be initialized such that the SSO allows access to the app's endpoint according to the chosen `init_main_permission` question. The `main.url = "/"` is here to tell that the main endpoint is the "root" of the app, that is `https://domain.tld/helloworld/` if the app is installed with `domain=domain.tld` and `path=/helloworld`
|
||||
- `apt`: the packages `nyancat`, `lolcat`, `sl` will be installed with `apt`. These are just dummy apt dependencies to illustrate the syntax.
|
||||
|
||||
The full documentation on resources is available [here](/packaging_apps_resources)
|
||||
|
|
@ -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,72 +0,0 @@
|
|||
---
|
||||
title: Intégration continue
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_ci'
|
||||
---
|
||||
|
||||
Le projet Yunohost fournit un [Serveur D'Integration Continue](https://ci-apps-dev.yunohost.org/ci/) que tout le monde peut utiliser pour tester son application.
|
||||
Il execute [package_check](https://github.com/YunoHost/package_check) sur votre repository.
|
||||
|
||||
Pour l'utiliser, il faut:
|
||||
- Que votre repository soit transféré à [YunoHost-Apps repository](https://github.com/YunoHost-Apps)
|
||||
- Avoir un fichier check_process correct [Sa description est ici](https://github.com/YunoHost/package_check#syntax-of-check_process)
|
||||
- Il est recommandé d'avoir fait les tests au préalable en local avec l'outil [Outil Package_check](https://github.com/YunoHost/package_check)
|
||||
|
||||
Il est très facile de demander un nouveau test, grâce à un bot github:
|
||||
- Il vous suffit de créer un Pull Request dans votre repository github, avec un commentaire contenant le texte suivant: !testme
|
||||
- Immédiatement, le bot va ajouter un commentaire vous informant que la demande de test a été prise en compte:
|
||||
|
||||
- Parfois le bot ne semble pas écouter... Il faut juste recommencer, avec le sourire si possible !
|
||||
- Si vous cliquez sur ce commentaire, vous verez le déroulement de votre test sur le serveur d'integration continue.
|
||||
|
||||
Le test sera mis dans une file d'attente, une fois exécuté complètement, il va:
|
||||
- Ajouter le résultat du test and le Pull Request comme commentaire.
|
||||
- Mettre à jour le score d'intégration de votre application dans votre repository ainsi que dans votre fichier README.
|
||||
|
||||
|
||||
A tout moment vous pouvez regarder la [page d'accueil du Serveur d'Integration Continue](https://ci-apps-dev.yunohost.org/ci/) pour vous informer des différents tests en cours.
|
||||
|
||||
! La suite de cette page est obsolète et doit être changé
|
||||
|
||||
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,74 +0,0 @@
|
|||
---
|
||||
title: Continuous integration
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_ci'
|
||||
---
|
||||
|
||||
The YunoHost project manages a [Continuous Integration Server](https://ci-apps-dev.yunohost.org/ci/) you can use to regularly test your integration.
|
||||
It's running [package_check](https://github.com/YunoHost/package_check).
|
||||
|
||||
For this You need to have:
|
||||
- Your repository transferred to [YunoHost-Apps repository](https://github.com/YunoHost-Apps)
|
||||
- A clean check_process file in your repo [See syntax description here](https://github.com/YunoHost/package_check#syntax-of-check_process)
|
||||
- It's recommended to have tested it locally before with [Package_check tool](https://github.com/YunoHost/package_check)
|
||||
|
||||
Thanks to a github bot, it's very easy to run a test:
|
||||
- Just create a Pull Request in your github repo, and add the following comment: !testme
|
||||
- You should then be greeted almost immediatly by a comment from the bot like this
|
||||
|
||||
- Sometimes the bot is not being triggered... Just smile and try again !
|
||||
- Then clicking on this comment will go to the Continuous Integration Server with your status of test
|
||||
|
||||
The test will be scheduled in a queue, once it is run and complete, the following will happen:
|
||||
- The bot will add the result in the PR as a new comment
|
||||
- Your README in the repository will be updated with the test result and the updated integration level of your application.
|
||||
|
||||
At any time you can have a look at [the CI Server homepage](https://ci-apps-dev.yunohost.org/ci/) to see what tests are currently ongoing.
|
||||
|
||||
! The rest of 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.
|
||||
|
|
@ -1,120 +0,0 @@
|
|||
---
|
||||
title: Trap
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_trap'
|
||||
---
|
||||
|
||||
Trap est une commande interne du shell permettant de capturer les signaux de sorties des commandes exécutées dans le shell courant et ses sous-shell.
|
||||
|
||||
Toute commande exécutée dans le shell renvoi un signal de sortie à la fin de son exécution. Soit 0 pour indiquer la fin de l'exécution de la commande, soit une valeur non nulle indiquant une interruption de celle-ci.
|
||||
|
||||
Dans le cas des scripts d'installation, trap va nous permettre de détecter une commande interrompue au milieu de son exécution en raison d'une erreur.
|
||||
La détection de cette erreur permettra de mettre fin à l'installation et de renvoyer vers le script remove en vue d'un nettoyage des résidus.
|
||||
|
||||
Trap s'utilise de la manière suivante :
|
||||
|
||||
```bash
|
||||
trap 'commande' liste_de_signaux
|
||||
```
|
||||
|
||||
Pour simplifier, nous utiliserons le pseudo signal `ERR` pour rassembler tout les signaux d'erreur.
|
||||
|
||||
On pourrait ajouter simplement cette ligne en début de script :
|
||||
|
||||
```bash
|
||||
trap "echo Erreur d'installation" ERR
|
||||
```
|
||||
|
||||
Après cette ligne, toute commande provoquant une erreur déclenchera l'affichage du message indiqué par trap.
|
||||
L'ensemble du shell courant et du sous-shell sera pris en charge par trap.
|
||||
|
||||
Pour arrêter la capture des signaux par trap, on peut simplement désactiver trap.
|
||||
|
||||
```bash
|
||||
trap ERR
|
||||
```
|
||||
|
||||
Ou ignorer complètement les signaux de sorties concernés.
|
||||
|
||||
```bash
|
||||
trap "" ERR
|
||||
```
|
||||
|
||||
Dans ce dernier cas, le signal d'interruption n'aura aucun effet sur le shell. Cela peux être utile pour une commande dont la sortie en erreur ne doit pas impacter le déroulement du script d'installation.
|
||||
|
||||
### Stopper le script d'installation et nettoyer avant de quitter.
|
||||
En cas d'erreur du script d'installation, trap doit nous permettre de stopper l'installation, puis de nettoyer les fichiers résiduels partiellement installés avant de quitter le script.
|
||||
Pour cela, nous allons prévoir une fonction dédiée à l'échec de l'installation.
|
||||
|
||||
```bash
|
||||
# Delete files and db if exit with an error
|
||||
EXIT_PROPERLY () {
|
||||
trap ERR # Disable trap
|
||||
echo -e "\e[91m \e[1m" # Shell in light red bold
|
||||
echo -e "!!\n $app install's script has encountered an error. Installation was cancelled.\n!!"
|
||||
|
||||
echo -e "\e[22m" # Remove bold
|
||||
|
||||
# Clean hosts
|
||||
sudo sed -i '/#leed/d' /etc/hosts
|
||||
|
||||
if [ $ynh_version = "2.2" ]; then
|
||||
/bin/bash ./remove # Call the script remove. In 2.2, this behavior is not automatic.
|
||||
fi
|
||||
exit 1
|
||||
}
|
||||
```
|
||||
|
||||
La fonction EXIT_PROPERLY doit indiquer à l'utilisateur l'échec de l'installation et nettoyer les résidus qui ne seront pas pris en charge par le script remove. Ce dernier sera automatiquement appelé à la suite de l'exit 1 avec YunoHost 2.4
|
||||
|
||||
Après cette fonction, on peut mettre en place la capture des signaux par trap.
|
||||
|
||||
```bash
|
||||
trap EXIT_PROPERLY ERR
|
||||
```
|
||||
|
||||
Si une commande échoue durant l'installation, la fonction EXIT_PROPERLY sera appelée, mettant fin à l'installation.
|
||||
|
||||
Pour simplifier la capture des signaux et les ignorer pour des commandes ponctuelles. Il est possible de placer les appels à trap dans des fonctions.
|
||||
|
||||
```bash
|
||||
TRAP_ON () { # Activate signal capture
|
||||
trap EXIT_PROPERLY ERR # Capturing exit signals on error
|
||||
}
|
||||
TRAP_OFF () { # Ignoring signal capture until TRAP_ON
|
||||
trap '' ERR # Ignoring exit signals
|
||||
}
|
||||
```
|
||||
|
||||
> Ma fonction TRAP_OFF ne fonctionne pas. Pour une raison qui m'échappe. Utiliser `trap '' ERR` directement fonctionne très bien en revanche.
|
||||
|
||||
Pour gérer les éventuelles erreur d'installations, on peut donc simplement ajouter ce morceau de code après la récupération des arguments :
|
||||
|
||||
```bash
|
||||
# Delete files and db if exit with an error
|
||||
EXIT_PROPERLY () {
|
||||
trap ERR # Disable trap
|
||||
echo -e "\e[91m \e[1m" # Shell in light red bold
|
||||
echo -e "!!\n $app install's script has encountered an error. Installation was cancelled.\n!!"
|
||||
|
||||
echo -e "\e[22m" # Remove bold
|
||||
|
||||
# Clean hosts
|
||||
sudo sed -i '/#leed/d' /etc/hosts
|
||||
|
||||
if [ $ynh_version = "2.2" ]; then
|
||||
/bin/bash ./remove # Call the script remove. In 2.2, this behavior is not automatic.
|
||||
fi
|
||||
exit 1
|
||||
}
|
||||
TRAP_ON () { # Activate signal capture
|
||||
trap EXIT_PROPERLY ERR # Capturing exit signals on error
|
||||
}
|
||||
TRAP_OFF () { # Ignoring signal capture until TRAP_ON
|
||||
trap '' ERR # Ignoring exit signals
|
||||
}
|
||||
TRAP_ON
|
||||
```
|
||||
|
|
@ -1,120 +0,0 @@
|
|||
---
|
||||
title: Trap
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_trap'
|
||||
---
|
||||
|
||||
Trap is an internal shell command used to capture the output signals of commands executed in the current shell and its subshells.
|
||||
|
||||
Any command executed in the shell returns an exit signal at the end of its execution. Either 0 to indicate the end of the execution of the command, or a non-zero value indicating an interruption thereof.
|
||||
|
||||
In the case of installation scripts, trap will allow us to detect a command interrupted in the middle of its execution due to an error.
|
||||
Detection of this error will allow the installation to be terminated and returned to the remove script for cleaning up residues.
|
||||
|
||||
Trap is used as follows:
|
||||
|
||||
```bash
|
||||
trap 'commande' liste_de_signaux
|
||||
```
|
||||
|
||||
To simplify, we will use the pseudo signal `ERR` to gather all the error signals.
|
||||
|
||||
We could simply add this line at the beginning of the script:
|
||||
|
||||
```bash
|
||||
trap "echo Erreur d'installation" ERR
|
||||
```
|
||||
|
||||
After this line, any command causing an error will trigger the display of the message indicated by trap.
|
||||
All of the current shell and the subshell will be supported by trap.
|
||||
|
||||
To stop capturing signals with trap, you can simply deactivate trap.
|
||||
|
||||
```bash
|
||||
trap ERR
|
||||
```
|
||||
|
||||
Or completely ignore the affected output signals.
|
||||
|
||||
```bash
|
||||
trap "" ERR
|
||||
```
|
||||
|
||||
In the latter case, the interrupt signal will have no effect on the shell. This can be useful for a command whose error output should not impact the progress of the installation script.
|
||||
|
||||
### Stop the installation script and clean up before exiting.
|
||||
In the event of an error in the installation script, trap must allow to stop the installation, then clean up the partially installed residual files before leaving the script.
|
||||
For this, we will provide a function dedicated to the installation failure.
|
||||
|
||||
```bash
|
||||
# Delete files and db if exit with an error
|
||||
EXIT_PROPERLY () {
|
||||
trap ERR # Disable trap
|
||||
echo -e "\e[91m \e[1m" # Shell in light red bold
|
||||
echo -e "!!\n $app install's script has encountered an error. Installation was cancelled.\n!!"
|
||||
|
||||
echo -e "\e[22m" # Remove bold
|
||||
|
||||
# Clean hosts
|
||||
sudo sed -i '/#leed/d' /etc/hosts
|
||||
|
||||
if [ $ynh_version = "2.2" ]; then
|
||||
/bin/bash ./remove # Call the script remove. In 2.2, this behavior is not automatic.
|
||||
fi
|
||||
exit 1
|
||||
}
|
||||
```
|
||||
|
||||
The `EXIT_PROPERLY` function must indicate to the user that the installation has failed and clean up any residue that will not be taken care of by the remove script. The latter will be automatically called after exit `1` with YunoHost 2.4
|
||||
|
||||
After this function, we can set up signal capture by trap.
|
||||
|
||||
```bash
|
||||
trap EXIT_PROPERLY ERR
|
||||
```
|
||||
|
||||
If a command fails during installation, the `EXIT_PROPERLY` function will be called, ending the installation.
|
||||
|
||||
To simplify the capture of signals and ignore them for specific commands. It is possible to place trap calls in functions.
|
||||
|
||||
```bash
|
||||
TRAP_ON () { # Activate signal capture
|
||||
trap EXIT_PROPERLY ERR # Capturing exit signals on error
|
||||
}
|
||||
TRAP_OFF () { # Ignoring signal capture until TRAP_ON
|
||||
trap '' ERR # Ignoring exit signals
|
||||
}
|
||||
```
|
||||
|
||||
> The `TRAP_OFF` function does not work. For some reason. Using `trap '' ERR` directly works fine however.
|
||||
|
||||
To manage possible installation errors, we can therefore simply add this code after retrieving the arguments:
|
||||
|
||||
```bash
|
||||
# Delete files and db if exit with an error
|
||||
EXIT_PROPERLY () {
|
||||
trap ERR # Disable trap
|
||||
echo -e "\e[91m \e[1m" # Shell in light red bold
|
||||
echo -e "!!\n $app install's script has encountered an error. Installation was cancelled.\n!!"
|
||||
|
||||
echo -e "\e[22m" # Remove bold
|
||||
|
||||
# Clean hosts
|
||||
sudo sed -i '/#leed/d' /etc/hosts
|
||||
|
||||
if [ $ynh_version = "2.2" ]; then
|
||||
/bin/bash ./remove # Call the script remove. In 2.2, this behavior is not automatic.
|
||||
fi
|
||||
exit 1
|
||||
}
|
||||
TRAP_ON () { # Activate signal capture
|
||||
trap EXIT_PROPERLY ERR # Capturing exit signals on error
|
||||
}
|
||||
TRAP_OFF () { # Ignoring signal capture until TRAP_ON
|
||||
trap '' ERR # Ignoring exit signals
|
||||
}
|
||||
TRAP_ON
|
||||
```
|
||||
158
pages/06.contribute/10.packaging_apps/20.scripts/scripts.md
Normal file
158
pages/06.contribute/10.packaging_apps/20.scripts/scripts.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
---
|
||||
title: Writing app scripts
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_scripts'
|
||||
---
|
||||
|
||||
|
||||
App scripts are the essential logic defining what happens when an app is `install`ed, `remove`d, `upgrade`d, `backup`ed, or `restore`d. They are written in [Bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)) which is the same stuff you type in interactive mode in a terminal, though we added a bunch of custom YunoHost functions that we call `helpers` to standardize many common operations - for example adding the nginx configuration.
|
||||
|
||||
Note that starting from packaging v2, the logic or what happens when an app is installed, etc. is also contained partially in the resource configuration in the `manifest.toml`.
|
||||
|
||||
In the `scripts` folder of an app, you can expect to find:
|
||||
|
||||
```text
|
||||
manifest.toml
|
||||
scripts/
|
||||
- _common.sh # Some "common" definition, typically custom helpers or global variables used accross all scripts
|
||||
- install # The install procedure
|
||||
- remove # The remove procedure
|
||||
- upgrade # The upgrade procedure
|
||||
- backup # The backup procedure - in fact it only "declares" what should be backup / no actual real backup happens at this point except dumping SQL databases
|
||||
- restore # The restore procedure
|
||||
- change_url # Some apps do also provide a change url script, which corresponds to changing the URL endpoint of the app, which may be as simple as changing the nginx conf, or may involve significant changes in the app DB
|
||||
```
|
||||
|
||||
Here is an example of the simple install script for the `helloworld` app:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# This is where we load the official YunoHost helpers
|
||||
source /usr/share/yunohost/helpers
|
||||
|
||||
#=================================================
|
||||
# DOWNLOAD, CHECK AND UNPACK SOURCE
|
||||
# This is where we would usually fetch the .tar.gz archive
|
||||
# from the upstream and extract it into our local install dir
|
||||
#=================================================
|
||||
# At the beginning of each major operation, we call this helper
|
||||
# that creates a progress bar
|
||||
ynh_script_progression --message="Setting up source files..." --weight=1
|
||||
|
||||
echo "Hello world!" > $install_dir/index.html
|
||||
chown -R www-data: "$install_dir"
|
||||
|
||||
#=================================================
|
||||
# NGINX CONFIGURATION
|
||||
# This is where the nginx conf snippet for the app is created using the
|
||||
# configuration template provided in conf/nginx.conf
|
||||
# and added to /etc/nginx/conf.d/$domain.d/$app.conf
|
||||
#=================================================
|
||||
ynh_script_progression --message="Configuring nginx web server..." --weight=1
|
||||
|
||||
ynh_add_nginx_config
|
||||
```
|
||||
|
||||
Note that the scripts are run with the `set -eu` options (except for the remove script), which means that any failing command or use of non-existing variable will trigger an error and stop the script execution.
|
||||
|
||||
|
||||
## Variables available in a script context
|
||||
|
||||
Special variables are automatically defined in the context of a script:
|
||||
|
||||
- `$app` is the app ID. It will typically be the ID from the app's manifest.toml, for example `helloworld`, but will be `helloworld__2`, `__3` etc for multi-instance installs.
|
||||
- During install, answers to install questions are automatically available as bash variables. For example, the `$domain` setting corresponds to the `domain` question, same for `$prefered_pet`, etc... Note that - apart from special questions such as `init_main_permission` or user-provided passwords - they are also automatically saved as settings (cf next section).
|
||||
- During other scripts, all app settings are also loaded and automatically available.
|
||||
- Note that some settings are automatically created/updated by app ressources. For example, the `install_dir` setting will automatically be available too and corresponds to typically `/var/www/$app`
|
||||
- In the `change_url` context, variables called `new_domain`, `new_path`, `old_domain`, `old_path` will be available, as well as `change_domain` and `change_path` equal to `0` (false) or `1` (true) depending if the domain / path changed
|
||||
|
||||
|
||||
## Setting system
|
||||
|
||||
Application often need to store long term information in between scripts triggered by the admin. For this, YunoHost has a key-value store for each application called "setting" and is stored in `/etc/yunohost/apps/$app/settings.yml`.
|
||||
|
||||
Apps can interact with this key value store in this way:
|
||||
|
||||
```bash
|
||||
# Retrieve a setting into variable "db_name"
|
||||
db_name=$(ynh_app_setting_get --app=$app --key=db_name)
|
||||
|
||||
# Update a setting
|
||||
ynh_app_setting_set --app=$app --key=db_name --value=$db_name
|
||||
```
|
||||
|
||||
## Helper system
|
||||
|
||||
We call helpers a set of custom bash function created by the YunoHost project to standardize common operations accross all apps. They are all prefixed with `ynh_`. The full list and documentation of these helpers is available on [this page](/packaging_apps_helpers). Some of these helpers are now partially obsolete as they are now handled by the core via app resources.
|
||||
|
||||
Here is the list of the major ones:
|
||||
|
||||
- `ynh_app_setting_get` / `ynh_app_setting_set`
|
||||
- `ynh_script_progression`
|
||||
- `ynh_setup_source`
|
||||
- nginx: `ynh_add_nginx_config` / `ynh_remove_nginx_config`
|
||||
- php: `ynh_add_fpm_config` / `ynh_remove_fpm_config`
|
||||
- systemd: `ynh_add_systemd_config` / `ynh_remove_systemd_config`
|
||||
- fail2ban: `ynh_add_fail2ban_config` / `ynh_remove_fail2ban_config`
|
||||
- custom: `ynh_add_config`
|
||||
- nodejs: `ynh_install_nodejs` / `ynh_use_nodejs`
|
||||
- `ynh_exec_warn_less`
|
||||
- `ynh_local_curl`
|
||||
- `ynh_secure_remove`
|
||||
- `ynh_backup` / `ynh_restore_file`
|
||||
|
||||
## Configuration/template system
|
||||
|
||||
App scripts will often need to create a bunch of configuration files.
|
||||
|
||||
Configuration templates are canonically stored provided in the `conf/` folder of the app, such as `nginx.conf`, `extra_php-fpm.conf`, `systemd.conf`, or `some-custom-app-conf.env` ...
|
||||
|
||||
In these templates, you can use the syntax `__FOOBAR__` which will automatically be replaced by the variable `$foobar` during runtime, when the conf is installed via the `ynh_add_*_config` helpers.
|
||||
|
||||
For example, an app's NGINX conf snippet may look like:
|
||||
|
||||
```text
|
||||
# The next line starting with '#sub_path_only' is automatically uncommented only when $path is not /
|
||||
#sub_path_only rewrite ^__PATH__$ __PATH__/ permanent;
|
||||
location __PATH__/ {
|
||||
|
||||
alias __INSTALL_DIR__/;
|
||||
|
||||
# Some headers and tweaks
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## App sources
|
||||
|
||||
App scripts will often need to download the upsteam app sources to be deployed in the install dir, via `ynh_setup_source`.
|
||||
|
||||
The `ynh_setup_source` is coupled to another conf file, usually `conf/app.src` which describes where to download the sources, how to check integrity, and how to extract the source.
|
||||
|
||||
For example, this is an `app.src` for wordpress:
|
||||
|
||||
```text
|
||||
SOURCE_URL=https://downloads.wordpress.org/release/wordpress-6.1.1.zip # The url of the sources
|
||||
SOURCE_SUM=088280b34aebc7331693e729d8e6b05eb8b9998c.... # The sha256 checksum
|
||||
SOURCE_SUM_PRG=sha256sum
|
||||
SOURCE_FORMAT=zip # The format is zip
|
||||
SOURCE_IN_SUBDIR=true # This is wether or not the sources are directly in the install root
|
||||
SOURCE_EXTRACT=true # (yes, we want to extract the zip)
|
||||
```
|
||||
|
||||
|
||||
## Common operations (TODO/FIXME)
|
||||
|
||||
#### installing/upgrading app sources
|
||||
#### adding configurations
|
||||
#### adding a systemd service
|
||||
#### curl / automatizing install forms
|
||||
#### classic stuff for nodejs apps
|
||||
#### classic stuff for php apps
|
||||
#### classic stuff for python apps
|
||||
#### classic stuff for ??? apps
|
||||
44
pages/06.contribute/10.packaging_apps/30.doc/doc.md
Normal file
44
pages/06.contribute/10.packaging_apps/30.doc/doc.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Adding documentation to your app
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_app_doc'
|
||||
---
|
||||
|
||||
Properly documenting your app is important for user experience ;). YunoHost provides several mechanism to display information to users.
|
||||
|
||||
## Extensive description : `doc/DESCRIPTION.md` and `doc/screenshots/`
|
||||
|
||||
You are encouraged to add a `doc/DESCRIPTION.md` which should contain a more extensive description than the short description contained in `manifest.toml`. This usually corresponds to listing the key features of the app.
|
||||
|
||||
You are also encouraged to add a `.png` or `.jpg` screenshot of what the app looks like in `doc/screenshots/`. There is no constrain on the exact filename, but the file weight should be kept below 512kb.
|
||||
|
||||
This description and screenshot will be shown when the admin open the catalog page for this app and the app info page in the webadmin after the admin installs this app.
|
||||
|
||||
You can also add translated versions of the `.md` file in, for example, `doc/DESCRIPTION_fr.md`, `_es.md`, `_it.md`, etc.
|
||||
|
||||
If your app repository is part of the YunoHost-Apps org, the provided description will be used to auto-regenerate the README.md of your github repo via `yunohost-bot`.
|
||||
|
||||
## Specific notes for admins : `doc/ADMIN.md`, `doc/<whatever>.md`
|
||||
|
||||
Sometimes, you may want to ship YunoHost-specific notes regarding the administration of this app. For example, integrating OnlyOffice inside Nextcloud.
|
||||
|
||||
You can do so by adding a `doc/ADMIN.md` file or even a `doc/<whatever>.md` page for each specific topic - and similarly add `_<lang>` suffix for translations.
|
||||
|
||||
Note that you can even use the `__FOOBAR__` syntax which will automatically be replaced with the `foobar` setting.
|
||||
|
||||
These notes will be available in the app info page in the webadmin after the app installation.
|
||||
|
||||
## Pre/post-install notes, pre/post-upgrade notes
|
||||
|
||||
Sometimes, you may want to display important information to the admin at key points in the app's life cycle. You can do so by providing special markdown files:
|
||||
- `doc/PRE_INSTALL.md`: displayed right before the installation (for example to warn that « This app install is expected to take around 30 minutes, be patient! » or « This app will automatically add 1GB swap to your system »)
|
||||
- NB: try to not overlap with the anti-feature tags from the catalog (cf Publishing your app in the catalog) which can be used to warn that the app's upstream is alpha-stage or deprecated among other things.
|
||||
- `doc/POST_INSTALL.md`: displayed in a popup after the installation AND a dismissable note in the webadmin app info view.
|
||||
- `doc/PRE_UPGRADE.md`: displayed right before any upgrade of this app (NB: the pre-upgrade note from the NEW version will be used, not the one from the installed version)
|
||||
- You can also create `doc/PRE_UPGRADE.d/{version}.md` to have a note displayed before upgrading to a version equal or higher than `{version}`
|
||||
- `doc/POST_UPGRADE.md`: displayed in a popup after the upgrade AND a dismissable note in the webadmin app info view.
|
||||
|
||||
Same as `ADMIN.md` and others: in these files, you can use the `__FOOBAR__` syntax which will automatically be replaced with the `foobar` setting.
|
||||
79
pages/06.contribute/10.packaging_apps/40.testing/testing.md
Normal file
79
pages/06.contribute/10.packaging_apps/40.testing/testing.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
---
|
||||
title: Testing your app
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_testing'
|
||||
---
|
||||
|
||||
Once you're done writing you app package, you'll want to check that everything works correctly. At first, you can manually try to install your app on some test server of your own, but testing everything manually often becomes tedious ;).
|
||||
|
||||
The YunoHost maintains several tools to automatically and somewhat "objectively" analyze and tests our 400+ apps catalog.
|
||||
|
||||
## Package linter
|
||||
|
||||
The [package linter](https://github.com/YunoHost/package_linter) performs a static analysis of your app to check a bunch of recommended practice.
|
||||
|
||||
It is pretty straightforward to run considering that you should only need Python installed.
|
||||
|
||||
## Package check
|
||||
|
||||
[Package check](https://github.com/YunoHost/package_check) is a more elaborate software that will tests many scenarios for you app such as:
|
||||
- installing, removing and reinstalling your app + validating that the app can indeed be accessed on its URL endpoint (with no 404/502 error)
|
||||
- when installing on a root domain (`domain.tld/`)
|
||||
- when installing in a domain subpatch (`domain.tld/foobar`)
|
||||
- installing in private mode
|
||||
- installing multiple instances
|
||||
- upgrading from the same version
|
||||
- upgrading from older versions
|
||||
- backup/restore
|
||||
- ...
|
||||
|
||||
Package check will then summarize the results and compute a quality level ranging from 0 to 8.
|
||||
|
||||
To run its tests, package check uses a LXC container to manipulate the package in a clean environment without any previous installations. Installing LXC/LXD is unfortunately not that straighforward (it kinda depends on your OS/distribution), though we documented how to do so [in the README](https://github.com/YunoHost/package_check#deploying-package_check).
|
||||
|
||||
### Package check's `tests.toml`
|
||||
|
||||
Package check interfaces with your app's `tests.toml` which allows to control a few things about which tests are run - though it is usually pretty empty as many things can be deduced from the app's manifest.
|
||||
|
||||
More info about the syntax here are also available [in the README](https://github.com/YunoHost/package_check#teststoml-syntax)
|
||||
|
||||
### Application quality levels
|
||||
|
||||
Package check will compute a quality level ranging from 0 to 8.
|
||||
|
||||
Apps with level equal or lower than 4 are considered "bad quality" and YunoHost will discourage people from installing such apps.
|
||||
|
||||
While this definition may vary with time, the current definition as of February 2023 is roughly:
|
||||
|
||||
- level 0 (« Broken ») : the application doesn't work at all or doesn't pass level 1 criterias
|
||||
- level 1 (« Installable in at least one scenario ») : At least one install succeeded, and there's no critical issue reported in the linter
|
||||
- level 2 (« Installable in all scenarios ») : All install scenarios tested (typically install on full domain, domain+subpath, multi-instance, private/public) succeeded
|
||||
- level 3 (« Can be upgraded ») : All upgrades tests from the current commit succeeded
|
||||
- level 4 (« Can be backuped/restored ») : All backup/restore tests succeeded
|
||||
- level 5 (« No linter error ») : No red errors reported by the linter
|
||||
- level 6 (« App is in a community-operated git org ») : The app is hosted on YunoHost-Apps organization. (From a maintenance / security point of view, we want to avoid the catalog being filled with apps that are privately-hosted and that the initial maintainer will ultimately abandon and that can't be maintained easily by the community)
|
||||
- level 7 (« All tests succeeded + No linter warning ») : Pass all test (including for example upgrade from past commits) and no warning reported by the linter
|
||||
- level 8 (« Maintained and long-term good quality ») : The app is not flagged as not-maintained / alpha / deprecated / obsolete in the catalog, and has been at least level 5 during the past ~year
|
||||
|
||||
|
||||
## Continous integration (CI)
|
||||
|
||||
The YunoHost project also developed an interface called [`yunorunner`](https://github.com/YunoHost/yunorunner) which interfaces with `package_check`, handles a job queue, and automatically add jobs to the queue using some triggers.
|
||||
|
||||
The two major ones are:
|
||||
- [The "official" CI](https://ci-apps.yunohost.org/ci): This where the "official" quality level of each app comes from. Jobs are triggered after each commit on the repo's master branch.
|
||||
- [The "dev" CI](https://ci-apps-dev.yunohost.org/ci/): This is where people validate their pull request which is often more convenient than running `package_check` yourself, and has the advantage of the results being automatically public, which facilitates collective debugging.
|
||||
|
||||
Members of the YunoHost-Apps organization can trigger jobs on the dev CI directly from a pull request simply by commenting something like `!testme` (cf for example [here](https://github.com/YunoHost-Apps/nextcloud_ynh/pull/532#issuecomment-1402751409)). A .png summary of the tests will be automatically displayed once the job completes (and you can click the link to see the entire job execution and debug it).
|
||||
|
||||
|
||||
#### Why create `package_check` + `yunorunner` rather than using well-known solutions like Gitlab-CI ?
|
||||
|
||||
Constrain 1 : Gitlab-CI or other similar solutions are mostly based around Docker, while we use LXC. In particular, we do want to reuse LXC snapshots of successful install during other tests (upgrade, backup/restore, ..) rather than reinstalling the app from scratch everytime, which drastically reduces the test time. We could do so using Gitlab artifacts, but such artifacts are automatically made public which is not convenient because they contain a full filesystem and their only use it to speed up the test process. Moreover, in the Gitlab-CI paradigm, jobs are not running on the same machine and they would need to download the snapshot which can be lengthy. The other mechanism, caching, is explicitly advertised as not reliable in Gitlab's-CI doc. What would be helpful would be some non-public artifact system (see similar discussion [here](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/336))
|
||||
|
||||
Constrain 2 : Our test workflow is somewhat complex and we have 400+ apps to maintain. It's not acceptable to have to duplicate/maintain the CI logic in app each repository, so we need some sort of repo that handles the CI logic, while still being to supersed some behavior from the app repo itself. Gitlab-CI has some syntax which can allow this, but this remains quite laborious.
|
||||
|
||||
Constrain 3 : Having a common job queue/dashboard UI accross all app. In the Gitlab-CI paradigm, each repository has its own job queue/dashboard UI, but this is not really convenient.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
title: Publishing your app on the catalog
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_publishing'
|
||||
---
|
||||
|
||||
The official YunoHost's app catalog is maintained [in this repository](https://github.com/YunoHost/apps/), in particular [the `apps.toml` file](https://github.com/YunoHost/apps/blob/master/apps.toml).
|
||||
|
||||
For your app to be made available to everybody, you should make a pull request that adds your app inside the `apps.toml` (see the [detailed instructions in the README](https://github.com/YunoHost/apps/#how-to-add-your-app-to-the-application-catalog))
|
||||
|
||||
Note that the "real" catalog used by YunoHost servers is https://app.yunohost.org/default/v3/apps.json which is rebuilt every 4 hours.
|
||||
|
||||
NB: The `level` key is not to be set manually by maintainers. The `yunohost-bot` will [automatically create a pull request](https://github.com/YunoHost/apps/blob/master/tools/update_app_levels/update_app_levels.py) every Friday evening with results from the official CI, which are then to be manually reviewed and merged by the community.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
title: Config panels
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_config_panels'
|
||||
---
|
||||
|
||||
TODO / FIXME ...
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
title: SSO/LDAP integration
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_sso_ldap_integration'
|
||||
---
|
||||
|
||||
One powerful aspect of YunoHost is that apps are meant to be integrated with the SSO/LDAP stack, such that users logged in on YunoHost's user portal can be directly logged in each app without having to create an account in each of them nor having to re-log in each app every time.
|
||||
|
||||
It should be stressed that there are two different aspects here:
|
||||
- the LDAP integration, meaning that the user accounts in the app are directly mapped to YunoHost user accounts
|
||||
- the SSO integration, meaning that a user logged in on the YunoHost user portal is automatically logged in on the app as well.
|
||||
|
||||
Sometimes, LDAP integration is possible, but not SSO integration (though the opposite would be really weird as LDAP integration is somewhat required for the SSO to work)
|
||||
|
||||
The SSO system is handled by [SSOwat](https://github.com/YunoHost/ssowat) and also handles the "permission" system which defines wether or not a user (or anonymous visitor) can access the app.
|
||||
|
||||
## LDAP integration
|
||||
|
||||
LDAP is a de-facto standard when it comes to sharing a common user account database between multiple applications, hence its use in the context of YunoHost.
|
||||
|
||||
However, each app does implement LDAP support in its own specific way (or doesn't), and needs to be provided with parameters to actually talk to YunoHost's LDAP database, usually via its config file. It is advise to look for real-life example of apps implementing these (such as Nextcloud, Wekan...) but you will usually need to provide:
|
||||
|
||||
- LDAP host: `localhost` / `127.0.0.1`
|
||||
- LDAP port: `389`
|
||||
- Base DN : `dc=yunohost,dc=org`
|
||||
- User DN : `ou=users,dc=yunohost,dc=org`
|
||||
- Search filter: `(&(|(objectclass=posixAccount))(uid=%uid)(permission=cn=__APP__.main,ou=permission,dc=yunohost,dc=org))` (this makes sure that only people with the appropriate YunoHost/SSowat permission can access the app)
|
||||
- Username attribute: `uid`
|
||||
- Display name attribute: `displayname`
|
||||
- Email attribute: `mail`
|
||||
|
||||
TODO/FIXME: moar explanations? What is missing?
|
||||
|
||||
## SSO integration
|
||||
|
||||
Internally, SSOwat will on-the-fly inject [HTTP Basic Auth Headers](https://en.wikipedia.org/wiki/Basic_access_authentication) like `Authorization: Basic <base64credentials>`. Some applications may include Basic Auth support out of the box... PHP apps do often require this line in the NGINX config:
|
||||
|
||||
```text
|
||||
fastcgi_param REMOTE_USER $remote_user;
|
||||
```
|
||||
|
||||
`$remote_user` being a special variable in NGINX that maps to the user provided in the HTTP Basic Auth headers. The PHP application will then use the `HTTP_REMOTE_USER` info in its code.
|
||||
|
||||
|
||||
TODO/FIXME: moar explanations of how this is done for non-PHP apps?
|
||||
|
||||
|
||||
## Configuring SSOwat permissions for the app
|
||||
|
||||
SSOwat permissions are configured using the 'permission' resource in your app's manifest.toml
|
||||
|
||||
If relevant, you can create "sub" permissions for your app, for instance to only allow a specific group of people to access the admin UI of the app. For example:
|
||||
|
||||
```toml
|
||||
[resources.permissions]
|
||||
|
||||
# This configures the main permission, i.e. general access to `https://domain.tld/$app/`
|
||||
# Initial access is defined using the `init_main_permission` install question.
|
||||
main.url = "/"
|
||||
|
||||
# This configures an additional "admin" permission regarding access to `https://domain.tld/$app/admin`
|
||||
admin.url = "/admin"
|
||||
admin.show_tile = false # This means that this permission won't correspond to a tile in YunoHost's user portal
|
||||
admin.allowed = "admins" # Initialize the access for the "admins" group ... You can also use an install question called `init_admin_permission` to let the server admin choose this.
|
||||
```
|
||||
|
||||
See the page about app resources for the full description of behavior and properties.
|
||||
|
||||
|
||||
## Logging out on the app vs. Logging out of YunoHost
|
||||
|
||||
A common [known issue](https://github.com/YunoHost/issues/issues/501) is that sometimes, logging out of YunoHost apps will not log people out of every app. This is for example the case for [Nextcloud](https://github.com/YunoHost-Apps/nextcloud_ynh/issues/19), because it uses its own authentication cookies which are not cleared when people log out of YunoHost. This is not trivial to fix.
|
||||
|
||||
Similarly, logging out of the app doesn't necessarily log people from YunoHost entirely (which is more acceptable that clicking Log out and... not being logged out at all because you're still logged-in on the SSO, hence logged in on the app). Some YunoHost app do integrate custom patches such that the logout process of the app does automatically redirects to `https://domain.tld/yunohost/sso/?action=logout` which logs them out.
|
||||
|
|
@ -6,7 +6,7 @@ taxonomy:
|
|||
routes:
|
||||
default: '/packaging_apps_hooks'
|
||||
---
|
||||
YunoHost comprend un mécanisme de hooks déclenchés lors de nombreuses opérations modifiant le système. Vous pouvez utiliser ce mécanisme afin d'étendre le comportement d'une commande yunohost.
|
||||
YunoHost comprend un mécanisme de hooks déclenchés lors de nombreuses opérations modifiant le système. Vous pouvez utiliser ce mécanisme afin d'étendre le comportement d'une commande YunoHost.
|
||||
|
||||
Le cas le plus évident est l'ajout d'un utilisateur. Si vous aviez un hook `post_user_create`, ce hook sera déclenché dès qu'un utilisateur sera ajouté.
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ nano /etc/yunohost/hooks.d/post_user_create/05-add-user-to-samba
|
|||
```
|
||||
|
||||
## Comment ajouter un hook dans un paquetage d'application
|
||||
Si vous empaquetez une application, vous ne devez pas mettre vous-même le hook dans `/etc/yunohost/hooks.d mais vous devez créer un répertoire hooks à la racine de votre paquet.
|
||||
Si vous empaquetez une application, vous ne devez pas mettre vous-même le hook dans `/etc/yunohost/hooks.d` mais vous devez créer un répertoire hooks à la racine de votre paquet.
|
||||
```
|
||||
.
|
||||
├─── conf
|
||||
|
|
@ -7,7 +7,7 @@ routes:
|
|||
default: '/packaging_apps_hooks'
|
||||
---
|
||||
|
||||
YunoHost includes a hook mechanism triggered on a lot of operation changing the system. You can use this mechanism in order to extend the behaviour of a yunohost command.
|
||||
YunoHost includes a hook mechanism triggered on a lot of operation changing the system. You can use this mechanism in order to extend the behaviour of a YunoHost command.
|
||||
|
||||
The most obvious case is adding a user. If you had a `post_user_create` hook, this hook will be triggered as soon as a user is added.
|
||||
|
||||
|
|
@ -201,5 +201,5 @@ With advanced packaging comes [CI_package_check](https://github.com/YunoHost/CI_
|
|||
|
||||
When you do several things at the same time, sometimes you don't remember what is the next step for this or that app.
|
||||
A good tool to keep your TODO list organized is to use a kaban like apps:
|
||||
- [kanboard](https://github.com/YunoHost-Apps/kanboard_ynh)
|
||||
- [wekan](https://github.com/YunoHost-Apps/wekan_ynh)
|
||||
- [Kanboard](https://github.com/YunoHost-Apps/kanboard_ynh)
|
||||
- [Wekan](https://github.com/YunoHost-Apps/wekan_ynh)
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: Packaging v2
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_v2'
|
||||
---
|
||||
|
||||
|
||||
Packaging v2 is a major improvement for the packaging introduced in YunoHost 11.1
|
||||
|
||||
### Motivation
|
||||
|
||||
The motivations for this new format is:
|
||||
- to get rid of some boring or unecessarily complex or duplicateds stuff such as saving/loading settings, creating a system user, etc.. during the install/upgrade/restore script, which are common things accross many apps.
|
||||
- to get rid of funky historical, not-super-semantic stuff such as `__FINALPATH__` being replaced by `$final_path` (with underscore), or `__PATH__` being replaced by `$path_url`, etc.
|
||||
- formalize some aspects such as the existence of the install dir, data dir, apt dependencies, database, etc. which in turn unlock possible future developments such as computing the space used by an app at one given moment, auto-upgrading apt dependencies during Debian major migration, etc.
|
||||
- formalize some meta-info such as LDAP/SSO support, architectures supports, and other pre-install / post-install, pre-upgrade / post-upgrade notifications (replacing the infamous `ynh_send_readme_to_admin`) for better UI/UX during the install and upgrade process.
|
||||
|
||||
However, this "v2" is not the end of the story and should be seen as an intermediate stage before a "v3" packaging. In particular this "v3" packaging should also formalize the handling of the system and app configurations files and ultimately rework the entire paradigm of the install/remove/upgrade/backup/restore scripts.
|
||||
|
||||
|
||||
### Adapting a v1 app to v2
|
||||
|
||||
A script is available in https://github.com/YunoHost/apps/tree/master/tools/packaging_v2 and will attempt to convert what it can from the v1 format to the v2 format, in particular:
|
||||
- initializing a `manifest.toml` and prefilling it with info scrapped from the various scripts
|
||||
- comment out now-unecessary lines in the various scripts
|
||||
|
||||
Usage: `python3 convert_app_to_packaging_v2.py /path/yo/your/app`
|
||||
|
||||
This will edit the file in place and you should then carefully review and iterate over what the script did for you.
|
||||
|
||||
|
||||
### Highlights of the new format
|
||||
|
||||
- **The manifest is now written as toml (`manifest.toml`)** instead of json (`manifest.json`). The structure of the manifest itself has been reworked and now include:
|
||||
- The `upstream` section (now mandatory)
|
||||
- An `integration` section meant to formalize what minimum YunoHost version is required, the list of supported architectures, declare if SSO/LDAP is supported, typical resource usage. This is meant to be displayed both in the catalog (similar to app stores) and on the app info page after installing the app - though this is still work in progress.
|
||||
- A `resource` section (detailed below)
|
||||
- **Install questions are now automatically saved as settings** (except user-provided password and other specific infos)
|
||||
- **All settings are now automatically loaded in app script environments** (so e.g. directly define `$domain`, etc.)
|
||||
- **Auto-enable `set -eu`** a.k.a. `ynh_abort_if_errors` in appropriate scripts
|
||||
- **The safety-backup-before-upgrade is now automatically handled by the core**
|
||||
- **Simplify writing change-url scripts**: old the `new`/`old`/`change` `domain`/`path` are now automatically available in the context and a new helper `ynh_change_url_nginx_config` takes care of tweaking the nginx conf. Your script should essentially just call that helper and possibly tweak the app's conf and possibly restart the app's service
|
||||
- **Introduce a new `resource` mechanism**
|
||||
- Resources are declared in the `manifest.toml`.
|
||||
- They are meant to formalize recurring app needs that are to be provisioned/deprovisioned by the core.
|
||||
- They include for example: system user, apt dependencies, install dir, data dir, port, permissions, SQL database...
|
||||
- Each resource is to be provisioned *before* running the install script, deprovisioned *after* the remove script, and automatically upgraded if needed before running the upgrade script (or provisionned if introduced in the new app version, or deprovisioned if removed w.r.t. the previous app version)
|
||||
- More infos about resources and their options and behavior are available in the dedicated doc page
|
||||
- **Permissions are automatically initialized using the answer to the `init_main_permission` install question** (replacing the `is_public` question). No need to write a boring `if $is_public ...` in the install script to add visitors anymore ! There is a similar mechanism to init other permissions, eg `init_admin_permission` (cf also the doc about the `permission` resource)
|
||||
- **The content of the `doc/` folder is now meant to be integrated in the webadmin** (though this is still WIP as of writing this). In particular:
|
||||
- `DESCRIPTION.md` and the `screenshots/` folder are expected to be displayed prior to the app install form (similar to app stores on mobile)
|
||||
- `ADMIN.md` is expected to be made available somewhere in the info page and should contain technical admin notes. Other pages can be defined (just name it `WHATEVER.md`). Lang codes are also supported following the existing scheme for the README, eg `README_fr.md` is the French version, hence you can create `ADMIN_fr.md`, etc.
|
||||
- Note that the `ADMIN.md` page supports the `__FOOBAR__` notation that will be automatically replaced with the app's `foobar` setting
|
||||
- **Special files called 'notifications' are meant to replace the `ynh_send_readme_to_admin` mechanics**. They are also to be added to the `doc` folder:
|
||||
- `doc/PRE_INSTALL.md`: a note to be displayed prior to the app install. Typically to warn of something unusual, such as "the app install will automatically add 1GB swap to the system".
|
||||
- `doc/POST_INSTALL.md`: a note to be displayed after the app install. Typically to explain post-install operations to be performed manually by the admin and that cannot be automated.
|
||||
- `doc/PRE_UPGRADE.md`: a note to be displayed prior to any upgrade of this app.
|
||||
- `doc/PRE_UPGRADE.d/{version}.md`: a note to be displayed prior to a specific version upgrade.
|
||||
- `doc/POST_UPGRADE.md`: a note to be displayed after the app upgrade. For example in the context of Nextcloud, the fact that you may need to re-enable custom modules manually?
|
||||
- Note that the notifications, like `ADMIN.md`, supports the `__FOOBAR__` notation that will be automatically replaced with the app's `foobar` setting
|
||||
- **Replace some historical names with more sensible ones**, or homogenize some practices:
|
||||
- `final_path` is now `install_dir` (this migration should be automatically handled by the core and the `convert_app_to_packaging_v2.py` script)
|
||||
- `datadir` is now `data_dir` to be consistent with `install_dir` (this migration should be automatically handled by the core and the `convert_app_to_packaging_v2.py` script)
|
||||
- `path` is now always loaded as `$path`, no funky `$path_url`-but-it-is-saved-as-`path` anymore (this migration should be automatically handled by the core and the `convert_app_to_packaging_v2.py` script)
|
||||
- `mysqldbpwd` and `psqlpwd` or whatever are now always saved as `db_pwd` (cf the `database` resource) (this migration should be automatically handled by the core and the `convert_app_to_packaging_v2.py` script)
|
||||
- ports settings are now always named either `$port` or `$port_foo_bar` instead of `$foo_bar_port` (cf the `port` resource) (this migration should be automatically handled by the core and the `convert_app_to_packaging_v2.py` script)
|
||||
- the install dir is to be set to `/var/www/$app` by default for web apps (or can be changed to `/opt/????` for non-webapps). Note that YunoHost will **automatically move** the old install dir to the new `install_dir` during the corresponding upgrade.
|
||||
|
|
@ -7,7 +7,7 @@ routes:
|
|||
default: '/packaging_apps_helpers'
|
||||
---
|
||||
|
||||
Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/doc/generate_helper_doc.py) on 01/06/2023 (YunoHost version 11.1.2)
|
||||
Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/doc/generate_helper_doc.py) on 24/02/2023 (YunoHost version 11.1.11.2)
|
||||
|
||||
|
||||
## APPS
|
||||
|
|
@ -25,7 +25,7 @@ Requires YunoHost version *.*.* or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apps#L9)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apps#L9)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ Requires YunoHost version *.*.* or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apps#L65)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apps#L65)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L53)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L53)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -86,7 +86,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L75)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L75)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -100,7 +100,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L107)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L107)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -117,7 +117,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L117)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L117)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -134,7 +134,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L128)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L128)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -151,7 +151,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L138)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L138)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -168,7 +168,7 @@ Requires YunoHost version 2.7.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L148)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L148)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -190,7 +190,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L225)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L225)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -207,7 +207,7 @@ Requires YunoHost version 3.8.1 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L335)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L338)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -223,7 +223,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L354)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L357)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -243,7 +243,7 @@ Requires YunoHost version 3.8.1 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/apt#L382)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/apt#L385)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -316,7 +316,7 @@ Requires YunoHost version 3.5.0 or higher for the argument `--not_mandatory`
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L64)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L64)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -330,7 +330,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L179)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L179)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -375,7 +375,7 @@ Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L238)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L238)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -394,7 +394,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L306)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L306)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -416,7 +416,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L350)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L350)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -435,7 +435,7 @@ Requires YunoHost version 3.3.1 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L381)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L381)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -458,7 +458,7 @@ Requires YunoHost version 2.7.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L416)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L416)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -481,7 +481,7 @@ Requires YunoHost version 2.7.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/backup#L464)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/backup#L464)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -558,7 +558,7 @@ Requires YunoHost version 4.1.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/fail2ban#L64)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/fail2ban#L64)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -572,7 +572,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/fail2ban#L119)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/fail2ban#L119)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -600,7 +600,7 @@ Requires YunoHost version 3.8.1 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/hardware#L13)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/hardware#L13)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -623,7 +623,7 @@ Requires YunoHost version 3.8.1 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/hardware#L75)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/hardware#L75)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -644,7 +644,7 @@ Requires YunoHost version 2.4.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L10)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L10)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -661,7 +661,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L30)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L30)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -678,7 +678,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L56)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L56)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -695,7 +695,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L73)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L73)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -714,7 +714,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L92)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L92)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -733,7 +733,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L113)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L113)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -752,7 +752,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L134)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L134)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -771,7 +771,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L155)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L155)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -790,7 +790,7 @@ Requires YunoHost version 3.2.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L176)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L176)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -810,7 +810,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L237)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L237)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -825,7 +825,7 @@ Requires YunoHost version 3.6.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logging#L325)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logging#L325)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -854,7 +854,7 @@ Requires YunoHost version 3.2.0 or higher for the argument `--specific_user`
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logrotate#L18)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logrotate#L18)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -868,7 +868,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/logrotate#L109)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/logrotate#L109)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -885,7 +885,7 @@ Requires YunoHost version 4.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/multimedia#L11)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/multimedia#L11)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -905,7 +905,7 @@ Requires YunoHost version 4.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/multimedia#L64)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/multimedia#L64)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -922,7 +922,7 @@ Requires YunoHost version 4.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/multimedia#L93)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/multimedia#L93)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -955,7 +955,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/mysql#L15)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/mysql#L15)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -973,7 +973,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/mysql#L36)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/mysql#L36)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -991,7 +991,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/mysql#L60)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/mysql#L60)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1012,7 +1012,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/mysql#L128)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/mysql#L128)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1031,7 +1031,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/mysql#L160)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/mysql#L160)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1053,7 +1053,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/mysql#L198)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/mysql#L198)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1071,7 +1071,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/mysql#L224)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/mysql#L224)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1095,7 +1095,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/network#L12)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/network#L12)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1116,7 +1116,7 @@ Requires YunoHost version 3.8.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/network#L36)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/network#L36)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1137,7 +1137,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/network#L99)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/network#L99)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1158,7 +1158,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/network#L119)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/network#L119)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1186,7 +1186,7 @@ Requires YunoHost version 4.1.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/nginx#L19)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/nginx#L19)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1200,7 +1200,21 @@ Requires YunoHost version 2.7.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/nginx#L41)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/nginx#L41)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
#### ynh_change_url_nginx_config
|
||||
[details summary="<i>Move / regen the nginx config in a change url context</i>" class="helper-card-subtitle text-muted"]
|
||||
|
||||
**Usage**: `ynh_change_url_nginx_config`
|
||||
|
||||
**Details**:<br/>
|
||||
Requires YunoHost version 11.1.9 or higher.
|
||||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/nginx#L52)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1254,7 +1268,7 @@ Requires YunoHost version 2.7.12 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/nodejs#L74)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/nodejs#L74)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1278,7 +1292,7 @@ Requires YunoHost version 2.7.12 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/nodejs#L114)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/nodejs#L114)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1296,7 +1310,7 @@ Requires YunoHost version 2.7.12 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/nodejs#L191)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/nodejs#L191)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1369,7 +1383,7 @@ Requires YunoHost version 3.7.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L66)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L66)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1388,7 +1402,7 @@ Requires YunoHost version 3.7.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L152)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L152)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1406,7 +1420,7 @@ Requires YunoHost version 3.7.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L169)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L169)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1429,7 +1443,7 @@ Requires YunoHost version 3.7.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L192)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L192)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1452,7 +1466,7 @@ Requires YunoHost version 3.7.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L260)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L260)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1473,7 +1487,7 @@ Requires YunoHost version 3.7.1 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L329)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L329)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1488,7 +1502,7 @@ Requires YunoHost version 4.1.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L359)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L359)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1499,7 +1513,7 @@ Requires YunoHost version 4.1.2 or higher.
|
|||
|
||||
**Example**: `if ynh_legacy_permissions_exists then ynh_legacy_permissions_delete_all # You can recreate the required permissions here with ynh_permission_create fi Requires YunoHost version 4.1.2 or higher.`
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/permission#L379)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/permission#L379)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1557,7 +1571,7 @@ Requires YunoHost version 4.1.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/php#L59)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/php#L59)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1571,7 +1585,7 @@ Requires YunoHost version 2.7.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/php#L250)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/php#L257)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1590,18 +1604,18 @@ Requires YunoHost version 4.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/php#L483)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/php#L490)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
#### ynh_install_composer
|
||||
[details summary="<i>Install and initialize Composer in the given directory</i>" class="helper-card-subtitle text-muted"]
|
||||
|
||||
**Usage**: `ynh_install_composer [--phpversion=phpversion] [--workdir=$final_path] [--install_args="--optimize-autoloader"] [--composerversion=composerversion]`
|
||||
**Usage**: `ynh_install_composer [--phpversion=phpversion] [--workdir=$install_dir] [--install_args="--optimize-autoloader"] [--composerversion=composerversion]`
|
||||
|
||||
**Arguments**:
|
||||
- `-v`, `--phpversion`: PHP version to use with composer
|
||||
- `-w`, `--workdir`: The directory from where the command will be executed. Default $final_path.
|
||||
- `-w`, `--workdir`: The directory from where the command will be executed. Default $install_dir.
|
||||
- `-a`, `--install_args`: Additional arguments provided to the composer install. Argument --no-dev already include
|
||||
- `-c`, `--composerversion`: Composer version to install
|
||||
|
||||
|
|
@ -1610,7 +1624,7 @@ Requires YunoHost version 4.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/php#L509)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/php#L522)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1643,7 +1657,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L18)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L18)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1661,7 +1675,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L39)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L39)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1679,7 +1693,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L64)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L64)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1700,7 +1714,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L135)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L135)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1718,7 +1732,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L168)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L168)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1736,7 +1750,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L190)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L190)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1758,7 +1772,7 @@ Requires YunoHost version 2.7.13 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L234)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L234)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1776,7 +1790,7 @@ Requires YunoHost version 2.7.13 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/postgresql#L265)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/postgresql#L265)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1797,7 +1811,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/setting#L10)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/setting#L10)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1816,7 +1830,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/setting#L36)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/setting#L36)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1834,7 +1848,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/setting#L62)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/setting#L62)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1854,7 +1868,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/setting#L123)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/setting#L123)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1875,7 +1889,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/setting#L145)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/setting#L145)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1900,7 +1914,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/string#L13)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/string#L13)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1922,7 +1936,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/string#L40)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/string#L40)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1944,7 +1958,7 @@ Requires YunoHost version 2.7.7 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/string#L71)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/string#L71)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1967,7 +1981,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/string#L103)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/string#L103)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -1993,7 +2007,7 @@ Requires YunoHost version 4.1.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/systemd#L15)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/systemd#L15)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2010,7 +2024,7 @@ Requires YunoHost version 2.7.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/systemd#L38)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/systemd#L38)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2032,7 +2046,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/systemd#L67)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/systemd#L67)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2056,7 +2070,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L12)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L12)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2078,7 +2092,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L33)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L33)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2096,7 +2110,7 @@ Requires YunoHost version 2.4.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L53)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L53)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2115,7 +2129,7 @@ Requires YunoHost version 2.2.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L64)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L64)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2134,7 +2148,7 @@ Requires YunoHost version 3.5.0.2 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L82)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L82)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2163,7 +2177,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L111)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L111)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2180,7 +2194,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L153)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L153)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2194,7 +2208,7 @@ Requires YunoHost version 4.1.7 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/user#L179)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/user#L179)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2215,7 +2229,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L58)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L58)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2267,7 +2281,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L111)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L111)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2293,7 +2307,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L285)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L285)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2330,7 +2344,7 @@ that should be defined before calling this helper :
|
|||
__NAMETOCHANGE__ by $app
|
||||
__USER__ by $app
|
||||
__FINALPATH__ by $final_path
|
||||
__PHPVERSION__ by $YNH_PHP_VERSION
|
||||
__PHPVERSION__ by $YNH_PHP_VERSION (packaging v1 only, packaging v2 uses phpversion setting implicitly set by apt resource)
|
||||
__YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH
|
||||
```
|
||||
And any dynamic variables that should be defined before calling this helper like:
|
||||
|
|
@ -2351,7 +2365,7 @@ Requires YunoHost version 4.1.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L369)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L369)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2395,7 +2409,7 @@ Requires YunoHost version 4.3 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L522)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L523)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2414,7 +2428,7 @@ Requires YunoHost version 4.3 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L599)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L600)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2430,7 +2444,7 @@ Requires YunoHost version 2.7.12 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L711)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L715)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2447,7 +2461,7 @@ Requires YunoHost version 2.6.4 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L742)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L746)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2467,7 +2481,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L776)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L780)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2492,7 +2506,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L819)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L823)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2515,7 +2529,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L848)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L852)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2538,7 +2552,7 @@ Requires YunoHost version 3.5.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L873)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L877)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -2570,7 +2584,7 @@ Requires YunoHost version 3.8.0 or higher.
|
|||
|
||||
|
||||
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/cddfafaa553f6671f70ac440eca691ddbec67dc8/helpers/utils#L903)
|
||||
[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/helpers/utils#L907)
|
||||
[/details]
|
||||
----------------
|
||||
|
||||
|
|
@ -0,0 +1,234 @@
|
|||
---
|
||||
title: App resources
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_resources'
|
||||
---
|
||||
|
||||
Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/5d1778211596d11600690d938df36a7a14527f27/doc/generate_resource_doc.py) on 24/02/2023 (YunoHost version ('11.1.11.2',))
|
||||
|
||||
|
||||
----------------
|
||||
|
||||
## Apt
|
||||
|
||||
Create a virtual package in apt, depending on the list of specified packages that the app needs. The virtual packages is called `$app-ynh-deps` (with `_` being replaced by `-` in the app name, see `ynh_install_app_dependencies`)
|
||||
|
||||
##### Example:
|
||||
```toml
|
||||
[resources.apt]
|
||||
packages = "nyancat, lolcat, sl"
|
||||
|
||||
# (this part is optional and corresponds to the legacy ynh_install_extra_app_dependencies helper)
|
||||
extras.yarn.repo = "deb https://dl.yarnpkg.com/debian/ stable main"
|
||||
extras.yarn.key = "https://dl.yarnpkg.com/debian/pubkey.gpg"
|
||||
extras.yarn.packages = "yarn"
|
||||
```
|
||||
|
||||
##### Properties:
|
||||
- `packages`: Comma-separated list of packages to be installed via `apt`
|
||||
- `packages_from_raw_bash`: A multi-line bash snippet (using triple quotes as open/close) which should echo additional packages to be installed. Meant to be used for packages to be conditionally installed depending on architecture, debian version, install questions, or other logic.
|
||||
- `extras`: A dict of (repo, key, packages) corresponding to "extra" repositories to fetch dependencies from
|
||||
|
||||
##### Provision/Update:
|
||||
- The code literally calls the bash helpers `ynh_install_app_dependencies` and `ynh_install_extra_app_dependencies`, similar to what happens in v1.
|
||||
- Note that when `packages` contains some phpX.Y-foobar dependencies, this will automagically define a `phpversion` setting equal to `X.Y` which can therefore be used in app scripts ($phpversion) or templates (`__PHPVERSION__`)
|
||||
|
||||
##### Deprovision:
|
||||
- The code literally calls the bash helper `ynh_remove_app_dependencies`
|
||||
|
||||
----------------
|
||||
|
||||
## Data Dir
|
||||
|
||||
Creates a directory to be used by the app as the data store directory, typically where the app multimedia or large assets added by users are located. The corresponding path is stored in the settings as `data_dir`. This resource behaves very similarly to install_dir.
|
||||
|
||||
##### Example:
|
||||
```toml
|
||||
[resources.data_dir]
|
||||
# (empty - defaults are usually okay)
|
||||
```
|
||||
|
||||
##### Properties:
|
||||
- `dir`: (default: `/home/yunohost.app/__APP__`) The full path of the data dir
|
||||
- `owner`: (default: `__APP__:rwx`) The owner (and owner permissions) for the data dir
|
||||
- `group`: (default: `__APP__:rx`) The group (and group permissions) for the data dir
|
||||
|
||||
##### Provision/Update:
|
||||
- if the dir path changed and a folder exists at the old location, the folder will be `mv`'ed to the new location
|
||||
- otherwise, creates the directory if it doesn't exists yet
|
||||
- (re-)apply permissions (only on the folder itself, not recursively)
|
||||
- save the value of `dir` as `data_dir` in the app's settings, which can be then used by the app scripts (`$data_dir`) and conf templates (`__DATA_DIR__`)
|
||||
|
||||
##### Deprovision:
|
||||
- (only if the purge option is chosen by the user) recursively deletes the directory if it exists
|
||||
- also delete the corresponding setting
|
||||
|
||||
##### Legacy management:
|
||||
- In the past, the setting may have been called `datadir`. The code will automatically rename it as `data_dir`.
|
||||
- As explained in the 'Provision/Update' section, the folder will also be moved if the location changed
|
||||
|
||||
----------------
|
||||
|
||||
## Database
|
||||
|
||||
Initialize a database, either using MySQL or Postgresql. Relevant DB infos are stored in settings `$db_name`, `$db_user` and `$db_pwd`.
|
||||
|
||||
NB: only one DB can be handled in such a way (is there really an app that would need two completely different DB ?...)
|
||||
|
||||
NB2: no automagic migration will happen in an suddenly change `type` from `mysql` to `postgresql` or viceversa in its life
|
||||
|
||||
##### Example:
|
||||
```toml
|
||||
[resources.database]
|
||||
type = "mysql" # or : "postgresql". Only these two values are supported
|
||||
```
|
||||
|
||||
##### Properties:
|
||||
- `type`: The database type, either `mysql` or `postgresql`
|
||||
|
||||
##### Provision/Update:
|
||||
- (Re)set the `$db_name` and `$db_user` settings with the sanitized app name (replacing `-` and `.` with `_`)
|
||||
- If `$db_pwd` doesn't already exists, pick a random database password and store it in that setting
|
||||
- If the database doesn't exists yet, create the SQL user and DB using `ynh_mysql_create_db` or `ynh_psql_create_db`.
|
||||
|
||||
##### Deprovision:
|
||||
- Drop the DB using `ynh_mysql_remove_db` or `ynh_psql_remove_db`
|
||||
- Deletes the `db_name`, `db_user` and `db_pwd` settings
|
||||
|
||||
##### Legacy management:
|
||||
- In the past, the sql passwords may have been named `mysqlpwd` or `psqlpwd`, in which case it will automatically be renamed as `db_pwd`
|
||||
|
||||
----------------
|
||||
|
||||
## Install Dir
|
||||
|
||||
Creates a directory to be used by the app as the installation directory, typically where the app sources and assets are located. The corresponding path is stored in the settings as `install_dir`
|
||||
|
||||
##### Example:
|
||||
```toml
|
||||
[resources.install_dir]
|
||||
# (empty - defaults are usually okay)
|
||||
```
|
||||
|
||||
##### Properties:
|
||||
- `dir`: (default: `/var/www/__APP__`) The full path of the install dir
|
||||
- `owner`: (default: `__APP__:rwx`) The owner (and owner permissions) for the install dir
|
||||
- `group`: (default: `__APP__:rx`) The group (and group permissions) for the install dir
|
||||
|
||||
##### Provision/Update:
|
||||
- during install, the folder will be deleted if it already exists (FIXME: is this what we want?)
|
||||
- if the dir path changed and a folder exists at the old location, the folder will be `mv`'ed to the new location
|
||||
- otherwise, creates the directory if it doesn't exists yet
|
||||
- (re-)apply permissions (only on the folder itself, not recursively)
|
||||
- save the value of `dir` as `install_dir` in the app's settings, which can be then used by the app scripts (`$install_dir`) and conf templates (`__INSTALL_DIR__`)
|
||||
|
||||
##### Deprovision:
|
||||
- recursively deletes the directory if it exists
|
||||
|
||||
##### Legacy management:
|
||||
- In the past, the setting was called `final_path`. The code will automatically rename it as `install_dir`.
|
||||
- As explained in the 'Provision/Update' section, the folder will also be moved if the location changed
|
||||
|
||||
----------------
|
||||
|
||||
## Permissions
|
||||
|
||||
Configure the SSO permissions/tiles. Typically, webapps are expected to have a 'main' permission mapped to '/', meaning that a tile pointing to the `$domain/$path` will be available in the SSO for users allowed to access that app.
|
||||
|
||||
Additional permissions can be created, typically to have a specific tile and/or access rules for the admin part of a webapp.
|
||||
|
||||
The list of allowed user/groups may be initialized using the content of the `init_{perm}_permission` question from the manifest, hence `init_main_permission` replaces the `is_public` question and shall contain a group name (typically, `all_users` or `visitors`).
|
||||
|
||||
##### Example:
|
||||
```toml
|
||||
[resources.permissions]
|
||||
main.url = "/"
|
||||
# (these two previous lines should be enough in the majority of cases)
|
||||
|
||||
admin.url = "/admin"
|
||||
admin.show_tile = false
|
||||
admin.allowed = "admins" # Assuming the "admins" group exists (cf future developments ;))
|
||||
```
|
||||
|
||||
##### Properties (for each perm name):
|
||||
- `url`: The relative URI corresponding to this permission. Typically `/` or `/something`. This property may be omitted for non-web permissions.
|
||||
- `show_tile`: (default: `true` if `url` is defined) Wether or not a tile should be displayed for that permission in the user portal
|
||||
- `allowed`: (default: nobody) The group initially allowed to access this perm, if `init_{perm}_permission` is not defined in the manifest questions. Note that the admin may tweak who is allowed/unallowed on that permission later on, this is only meant to **initialize** the permission.
|
||||
- `auth_header`: (default: `true`) Define for the URL of this permission, if SSOwat pass the authentication header to the application. Default is true
|
||||
- `protected`: (default: `false`) Define if this permission is protected. If it is protected the administrator won't be able to add or remove the visitors group of this permission. Defaults to 'false'.
|
||||
- `additional_urls`: (default: none) List of additional URL for which access will be allowed/forbidden
|
||||
|
||||
##### Provision/Update:
|
||||
- Delete any permissions that may exist and be related to this app yet is not declared anymore
|
||||
- Loop over the declared permissions and create them if needed or update them with the new values
|
||||
|
||||
##### Deprovision:
|
||||
- Delete all permission related to this app
|
||||
|
||||
##### Legacy management:
|
||||
- Legacy `is_public` setting will be deleted if it exists
|
||||
|
||||
----------------
|
||||
|
||||
## Ports
|
||||
|
||||
Book port(s) to be used by the app, typically to be used to the internal reverse-proxy between nginx and the app process.
|
||||
|
||||
Note that because multiple ports can be booked, each properties is prefixed by the name of the port. `main` is a special name and will correspond to the setting `$port`, whereas for example `xmpp_client` will correspond to the setting `$port_xmpp_client`.
|
||||
|
||||
##### Example:
|
||||
```toml
|
||||
[resources.ports]
|
||||
# (empty should be fine for most apps... though you can customize stuff if absolutely needed)
|
||||
|
||||
|
||||
main.default = 12345 # if you really want to specify a prefered value .. but shouldnt matter in the majority of cases
|
||||
|
||||
xmpp_client.default = 5222 # if you need another port, pick a name for it (here, "xmpp_client")
|
||||
xmpp_client.exposed = "TCP" # here, we're telling that the port needs to be publicly exposed on TCP on the firewall
|
||||
```
|
||||
|
||||
##### Properties (for every port name):
|
||||
- `default`: The prefered value for the port. If this port is already being used by another process right now, or is booked in another app's setting, the code will increment the value until it finds a free port and store that value as the setting. If no value is specified, a random value between 10000 and 60000 is used.
|
||||
- `exposed`: (default: `false`) Wether this port should be opened on the firewall and be publicly reachable. This should be kept to `false` for the majority of apps than only need a port for internal reverse-proxying! Possible values: `false`, `true`(=`Both`), `Both`, `TCP`, `UDP`. This will result in the port being opened on the firewall, and the diagnosis checking that a program answers on that port.
|
||||
- `fixed`: (default: `false`) Tells that the app absolutely needs the specific value provided in `default`, typically because it's needed for a specific protocol
|
||||
|
||||
##### Provision/Update (for every port name):
|
||||
- If not already booked, look for a free port, starting with the `default` value (or a random value between 10000 and 60000 if no `default` set)
|
||||
- If `exposed` is not `false`, open the port in the firewall accordingly - otherwise make sure it's closed.
|
||||
- The value of the port is stored in the `$port` setting for the `main` port, or `$port_NAME` for other `NAME`s
|
||||
|
||||
##### Deprovision:
|
||||
- Close the ports on the firewall if relevant
|
||||
- Deletes all the port settings
|
||||
|
||||
##### Legacy management:
|
||||
- In the past, some settings may have been named `NAME_port` instead of `port_NAME`, in which case the code will automatically rename the old setting.
|
||||
|
||||
----------------
|
||||
|
||||
## System User
|
||||
|
||||
Provision a system user to be used by the app. The username is exactly equal to the app id
|
||||
|
||||
##### Example:
|
||||
```toml
|
||||
[resources.system_user]
|
||||
# (empty - defaults are usually okay)
|
||||
```
|
||||
|
||||
##### Properties:
|
||||
- `allow_ssh`: (default: False) Adds the user to the ssh.app group, allowing SSH connection via this user
|
||||
- `allow_sftp`: (default: False) Adds the user to the sftp.app group, allowing SFTP connection via this user
|
||||
- `home`: (default: `/var/www/__APP__`) Defines the home property for this user. NB: unfortunately you can't simply use `__INSTALL_DIR__` or `__DATA_DIR__` for now
|
||||
|
||||
##### Provision/Update:
|
||||
- will create the system user if it doesn't exists yet
|
||||
- will add/remove the ssh/sftp.app groups
|
||||
|
||||
##### Deprovision:
|
||||
- deletes the user and group
|
||||
|
||||
115
pages/06.contribute/10.packaging_apps/packaging_apps_intro.md
Normal file
115
pages/06.contribute/10.packaging_apps/packaging_apps_intro.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
title: Introduction to packaging
|
||||
template: docs
|
||||
taxonomy:
|
||||
category: docs
|
||||
routes:
|
||||
default: '/packaging_apps_intro'
|
||||
aliases:
|
||||
- '/packaging_apps'
|
||||
---
|
||||
|
||||
This documentation is here to provide all the basic concepts and vocabulary needed to understand app packaging.
|
||||
|
||||
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 standardized bash functions, aka "helpers". This pretty much marked **the beginning of the "v1" packaging era**.
|
||||
|
||||
Various tools were 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 turns out that it is even more important to stick to the common set of practices (even though arbitrary and not elegant) to ease the maintenance of all apps by any member of the packaging community accross all repos!
|
||||
|
||||
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 and added to YunoHost 11.1 in early 2023](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](https://github.com/YunoHost/issues/issues/2136) 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. We encourage you to have a look at those code repository to get familiar witch app repository structures:
|
||||
- the [`helloworld_ynh`](https://github.com/YunoHost-Apps/helloworld_ynh) app
|
||||
- the [`example_ynh`](https://github.com/YunoHost/example_ynh) app which illustrates all common features and recommended formatting
|
||||
- your favourite "real-life" app in the [YunoHost-Apps organization](https://github.com/orgs/YunoHost-Apps/repositories))
|
||||
|
||||
Among the file contained in a package, the most important ones are:
|
||||
|
||||
- the **app manifest** `manifest.toml` <small>(or `.json` in the past)</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`): changing where the app is installed in terms of web access 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.
|
||||
|
|
@ -108,6 +108,6 @@ Il contient essentiellement :
|
|||
- Pour une correction de bug : `fix-REDMINETICKET-description-correctif`
|
||||
- `ISSUENUMBER` est optionnel et correspond au numéro du ticket sur le bug tracker
|
||||
|
||||
- Une fois prêt, ouvrez une Pull Request (PR) sur Github. De préférence, inclure `[fix]` ou `[enh]` au début du titre de la PR.
|
||||
- Une fois prêt, ouvrez une Pull Request (PR) sur GitHub. De préférence, inclure `[fix]` ou `[enh]` au début du titre de la PR.
|
||||
|
||||
- Après relecture, test et validation par les autres contributeurs, votre branche sera mergée dans `unstable` !
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue