Ajouter vos propres applications au catalogue YunoHost
Guide pas-à-pas pour les amateurs — tout dans le navigateur, sauf une étape
En une phrase
Ce guide vous aide à faire apparaître vos applications personnalisées dans la page “Installer une application” de votre admin YunoHost, comme les applications officielles : avec une fiche, une catégorie, et surtout un bouton vert “Mettre à jour” quand vous publiez une nouvelle version.
Avant de commencer, vous aurez besoin de :
Accès à l’interface d’administration de votre serveur YunoHost (https://mon-domaine.tld/yunohost/admin)- Un compte GitHub.com ou GitLab.com (gratuit)
- Un paquet YunoHost qui fonctionne déjà (voir l’encart ci-dessous)
- Un accès SSH à votre serveur, pour une seule étape (l’étape 7)
- 30 minutes pour la première fois
Ce guide ne vous apprend pas à créer une application YunoHost. Il suppose que vous avez déjà un paquet qui s’installe correctement avec
yunohost app install <votre-dossier>. Un paquet, ce n’est pas qu’un fichier de description : c’est unmanifest.tomlet un dossierscripts/contenantinstall,upgrade,remove,backupetrestore.Si vous partez de zéro, commencez par le modèle officiel : github.com/YunoHost/example_ynh, puis revenez ici.
Rien de ce que vous ferez ici ne touche à vos applications déjà installées. Un catalogue est une simple “vue” : l’ajouter ou le retirer ne modifie aucune installation existante. Vous pouvez tout défaire à l’étape “Retour arrière”, en bas.
Un peu de vocabulaire (30 secondes)
| Mot | Ce que ça veut dire ici |
|---|---|
| Dépôt (repository) | Un dossier hébergé sur GitHub/GitLab |
| Commit | Une sauvegarde datée de vos fichiers |
| SHA | Le numéro unique d’un commit, 40 caractères (a1b2c3d4e5...) |
| Catalogue | Un fichier apps.json qui dit à YunoHost quelles applications existent et où les trouver |
Vous allez créer deux dépôts : un pour votre application, un pour votre catalogue. Deux dépôts séparés, c’est plus simple qu’il n’y paraît — et ça vous évitera un vrai casse-tête (voir l’étape 6).
Étape 1 — Choisir le nom de votre application
Trouvez un nom simple, en minuscules, sans accents ni espaces. Exemples : mecalendrier, monblog, photos-de-famille.
Notez ce nom quelque part. On l’appellera MON-NOM dans la suite.
Étape 2 — Créer le dépôt de votre application
Connectez-vous sur github.com. Cliquez sur le + en haut à droite → New repository.
| Champ | Valeur |
|---|---|
| Repository name | MON-NOM_ynh |
| Description | Mon application YunoHost (facultatif) |
| Visibilité | Public — obligatoire |
Cliquez Create repository.
Pourquoi
_ynhà la fin ? C’est une obligation de YunoHost : il refuse purement et simplement les adresses de dépôt qui ne se terminent pas par ce suffixe.
Étape 3 — Déposer votre paquet dans ce dépôt
Envoyez le contenu de votre paquet dans ce dépôt — par glisser-déposer avec Add file → Upload files, ou en ligne de commande si vous êtes à l’aise.
manifest.tomldoit se trouver à la RACINE du dépôt, pas dans un sous-dossier. YunoHost ne sait pas aller le chercher ailleurs. Votre dépôt doit donc ressembler à ça :MON-NOM_ynh/ ├── manifest.toml ← à la racine, obligatoirement ├── scripts/ │ ├── install │ ├── upgrade │ ├── remove │ ├── backup │ └── restore └── conf/
Voici à quoi doit ressembler un manifest.toml minimal et valide (remplacez ce qui est en majuscules) :
packaging_format = 2
id = "MON-NOM"
name = "Mon Application"
description.fr = "Ma super application personnelle"
description.en = "My awesome personal app"
version = "0.1.0~ynh1"
maintainers = ["Votre Nom"]
[upstream]
license = "MIT"
website = "https://mon-domaine.tld"
[integration]
yunohost = ">= 11.0"
architectures = "all"
multi_instance = false
ldap = false
sso = false
disk = "50M"
ram.build = "50M"
ram.runtime = "50M"
[install]
[install.domain]
type = "domain"
[install.path]
type = "path"
default = "/MON-NOM"
[install.api_key]
type = "password"
help.fr = "Votre clé API (compte gratuit sur example.org)."
[resources]
[resources.system_user]
[resources.install_dir]
Trois lignes méritent votre attention :
id = "MON-NOM"— c’est le nom définitif de l’étape 1. Ne le confondez pas avecname, qui est le joli nom affiché et que vous pouvez changer quand vous voulez.packaging_format = 2— sans cette ligne, YunoHost refuse le manifest.version = "0.1.0~ynh1"— la convention YunoHost : votre version, puis~ynhet un numéro. C’est ce champ qui déclenchera le bouton de mise à jour.
[install], c’est de l’or. Chaque sous-section devient une question posée à l’installation. Une clé d’API déclarée entype = "password"est saisie par la personne qui installe et reste sur son serveur — vous n’avez donc jamais à mettre la vôtre dans le code. C’est la bonne façon de faire.
.env, mot de passe, clé privée, certificat. Le dépôt est public, tout le monde peut le lire — et l’effacer d’un commit ne l’efface pas de l’historique.
Étape 4 — Créer le dépôt de votre catalogue
Refaites exactement l’étape 2, avec un autre nom :
| Champ | Valeur |
|---|---|
| Repository name | mon-catalogue |
| Visibilité | Public — obligatoire |
Ce dépôt-là ne contiendra aucun code : juste un fichier de description. Un seul catalogue suffira pour toutes vos applications futures.
Étape 5 — Récupérer le numéro du commit (le SHA)
Retournez sur votre dépôt MON-NOM_ynh.
- Cliquez sur l’onglet Commits (ou sur l’horloge « N commits » en haut à droite de la liste des fichiers).
- Sur la ligne du commit le plus récent, repérez à droite le petit code à 7 caractères (
a1b2c3d) avec une icône de presse-papier juste à côté. - Cliquez sur cette icône — l’infobulle dit “Copy full SHA”.
Sur GitLab : ouvrez le commit, un bouton de copie identique se trouve à côté de son identifiant.
Collez-le quelque part, vous en avez besoin tout de suite.
Étape 6 — Écrire le catalogue
Allez dans votre dépôt mon-catalogue → Add file → Create new file.
Dans le champ du nom de fichier, tapez exactement :
v3/apps.json
/, GitHub crée automatiquement le sous-dossierv3. C’est normal, laissez-le faire.
Collez ce contenu, en remplaçant les majuscules et le SHA de l’étape 5 :
{
"apps": {
"MON-NOM": {
"id": "MON-NOM",
"git": {
"url": "https://github.com/VOTRE-COMPTE/MON-NOM_ynh",
"branch": "main",
"revision": "COLLEZ-ICI-LES-40-CARACTERES"
},
"lastUpdate": 1756166400,
"manifest": {
"id": "MON-NOM",
"name": "Mon Application",
"description": {
"fr": "Ma super application personnelle",
"en": "My awesome personal app"
},
"version": "0.1.0~ynh1"
},
"state": "working",
"level": 8,
"maintained": true,
"high_quality": false,
"featured": false,
"category": "productivity_and_management",
"subtags": [],
"potential_alternative_to": [],
"antifeatures": []
}
},
"categories": [],
"antifeatures": [],
"security": { "version": 1, "apps": {}, "system": {} }
}
Cliquez Commit changes.
Ce qu’il faut retenir de ces champs :
| Champ | Rôle |
|---|---|
git.url |
L’adresse du dépôt de votre application (pas du catalogue) |
git.revision |
Les 40 caractères de l’étape 5 |
manifest.version |
Doit être identique à la version du manifest.toml. C’est elle que YunoHost compare à la version installée |
state |
Laissez "working" |
level |
Laissez 8 |
security |
Recopiez la ligne telle quelle. Voir l’encart ci-dessous |
security? C’est la liste des failles de sécurité
connues de vos applications. Vide, elle veut dire « rien à signaler » — c’est
votre cas aujourd’hui, et sans doute pour longtemps. Mais il faut quand même
l’écrire : depuis YunoHost 12.1.37, un catalogue qui ne la contient pas fait
afficher à chaque rafraîchissement « Catalog ‘moncata’ is missing the security
vulnerability index ». Ce n’est qu’un avertissement, rien ne casse — mais
autant l’éviter tout de suite. Recopiez la ligne sans y toucher :version
doit valoir exactement1, etappscommesystemdoivent être présentes
même vides.
versionetstatedécident si votre application est visible. La page d’installation filtre par défaut sur “Seulement les applications d’une qualité satisfaisante” : unlevelbas ou unstateautre que"working"la fait disparaître de la liste, sans le moindre message.
Étape 7 — Déclarer le catalogue sur votre serveur
C’est la seule étape qui ne se fait pas dans le navigateur.
7a. Trouver la bonne adresse
Elle a une forme bien précise :
https://github.com/VOTRE-COMPTE/mon-catalogue/raw/main
/v3/apps.jsonà la fin. YunoHost l’ajoute tout seul. Si vous le mettez, il ira chercher.../v3/apps.json/v3/apps.json, ne trouvera rien, et — c’est le plus grave — arrêtera de mettre à jour TOUS vos catalogues, y compris l’officiel. Vos applications officielles cesseraient silencieusement de proposer leurs mises à jour.Sur GitLab, l’adresse est
https://gitlab.com/VOTRE-COMPTE/mon-catalogue/-/raw/main(avec le/-/).
Vérifiez-la avant d’aller plus loin : ouvrez dans votre navigateur l’adresse ci-dessus suivie de /v3/apps.json. Vous devez voir votre texte JSON brut, commençant par { "apps":. Si vous voyez une page GitHub avec des boutons, ou une erreur 404, ne continuez pas — corrigez d’abord (dépôt privé ? mauvaise branche ? faute de frappe ?).
7b. Se connecter au serveur
ssh votre-utilisateur@mon-domaine.tld
7c. Regarder si le fichier existe déjà
sudo cat /etc/yunohost/apps_catalog.yml
Deux cas possibles :
Cas A — « No such file or directory ». C’est le cas le plus fréquent, et c’est normal : tant qu’on n’a jamais ajouté de catalogue, YunoHost garde sa liste par défaut en mémoire sans jamais l’écrire. Créez le fichier avec les deux lignes :
sudo sh -c "printf '%s\n' '- id: default' ' url: https://app.yunohost.org/default' '- id: moncata' ' url: https://github.com/VOTRE-COMPTE/mon-catalogue/raw/main' > /etc/yunohost/apps_catalog.yml"
default. Si vous ne mettez que votre catalogue, vous supprimez le catalogue officiel : Nextcloud, Vaultwarden et toutes vos applications officielles perdent leur bouton de mise à jour. Et rien ne vous préviendra, puisque le fichier reste valide.
Cas B — le fichier s’affiche. Il existe déjà : ne l’écrasez pas, ajoutez seulement votre ligne à la fin :
sudo sh -c "printf '%s\n' '- id: moncata' ' url: https://github.com/VOTRE-COMPTE/mon-catalogue/raw/main' >> /etc/yunohost/apps_catalog.yml"
moncataest le nom court de votre catalogue. Choisissez-le simple : c’est lui qui s’affichera sur la fiche de vos applications.
7d. Relire, puis rafraîchir
sudo cat /etc/yunohost/apps_catalog.yml
sudo yunohost tools update apps
Vous devez obtenir Success! The application catalog has been updated!, sans aucune ligne commençant par Error:.
Catalog 'moncata' is missing the security vulnerability index, il manque la lignesecurityde l’étape 6. Rien n’est cassé — voir Dépannage rapide pour l’ajouter.
Corrupted JSON read from ...répété en boucle, c’est l’adresse de l’étape 7a qui est mauvaise. Passez directement à la section Retour arrière en bas, corrigez l’adresse, et recommencez. Tant que ce n’est pas réglé, aucun de vos catalogues ne se met à jour.
Étape 8 — Vérifier que tout fonctionne
Retournez dans l’admin web, page Applications → Installer une application.
Vous devez constater trois choses :
- Votre application y figure, avec son nom, sa description et le nom de votre catalogue.
- Elle est rangée dans sa catégorie — le menu “Choisissez une catégorie” la trouve.
- Sur la fiche de l’application déjà installée (page Applications), le bandeau gris “Cette application n’existe pas (plus ?) dans le catalogue” a disparu.
Les fois suivantes : publier une mise à jour
À chaque nouvelle version de votre application, dans cet ordre :
- Dans
MON-NOM_ynh, modifiez votre code, et augmentezversiondansmanifest.toml(de0.1.0~ynh1à0.1.0~ynh2, ou0.2.0~ynh1). Commit changes. - Récupérez le nouveau SHA complet (étape 5).
- Dans
mon-catalogue, modifiezv3/apps.json: mettez à jourrevision(le nouveau SHA) etmanifest.version(la nouvelle version). Commit changes. - Sur le serveur :
sudo yunohost tools update apps(ou attendez le rafraîchissement automatique). - Page Applications : le bouton vert Mettre à jour est là.
Les catégories disponibles
Les 15 catégories officielles, à recopier telles quelles dans "category" :
À écrire dans category |
Ce qui s’affiche |
|---|---|
synchronization |
Synchronisation |
publishing |
Publication |
communication |
Communication |
office |
Bureautique |
productivity_and_management |
Productivité & gestion |
small_utilities |
Petits utilitaires |
reading |
Lecture |
education |
Éducation |
multimedia |
Multimédia |
social_media |
Médias sociaux |
games |
Jeux |
dev |
Développement |
system_tools |
Outils système |
iot |
Internet des objets (IoT) |
wat |
Wat |
watest la catégorie fourre-tout officielle, pour ce qui n’entre nulle part ailleurs.
Créer votre propre catégorie (optionnel)
Pour regrouper vos applications sous un nom à vous, remplacez dans v3/apps.json la ligne "categories": [] par :
"categories": [
{
"id": "mescategorie",
"icon": "server",
"title": { "en": "My Apps", "fr": "Mes applications" },
"description": {
"en": "Self-hosted apps I maintain.",
"fr": "Applications que je maintiens."
},
"subtags": []
}
]
Puis, dans l’entrée de votre application, remplacez "category": "productivity_and_management" par "category": "mescategorie".
Wat. C’est normal : YunoHost affiche d’abord les catégories officielles, puis celles des catalogues ajoutés. Plutôt pratique, vos applications sont toujours au même endroit.
Dépannage rapide
Mon application n’apparaît pas dans le catalogue
Vérifiez dans cet ordre :
- Le dépôt
MON-NOM_ynhest Public (aucune étiquette Private à côté du nom) - Le dépôt
mon-catalogueest Public lui aussi - L’adresse
https://.../mon-catalogue/raw/main/v3/apps.jsonouverte dans un navigateur affiche du texte JSON brut, pas une page web - Dans
apps_catalog.yml, l’adresse déclarée ne contient pas/v3/apps.json -
statevaut"working"etlevelvaut8 - Vous avez bien lancé
sudo yunohost tools update appsaprès vos modifications - Le filtre “Seulement les applications d’une qualité satisfaisante” de la page d’installation ne la masque pas — essayez de le désactiver
Le bouton vert “Mettre à jour” n’apparaît jamais
Presque toujours la même cause : manifest.version dans v3/apps.json n’a pas été augmenté, ou le catalogue n’a pas été republié. Comparez la version affichée par :
sudo yunohost app info MON-NOM
avec celle de votre v3/apps.json. Si elles sont identiques, c’est normal qu’aucun bouton ne s’affiche.
Catalog 'moncata' is missing the security vulnerability index
Votre catalogue a été écrit avant YunoHost 12.1.37, ou recopié d’une version plus ancienne de ce guide : il lui manque la ligne security. Rien n’est cassé — c’est un simple avertissement, vos applications et leurs mises à jour fonctionnent normalement.
Pour le faire taire, dans votre navigateur : dépôt mon-catalogue → v3/apps.json → l’icône crayon (Edit this file). Ajoutez une virgule à la fin de la ligne "antifeatures": [], puis cette ligne juste en dessous, avant l’accolade finale :
"security": { "version": 1, "apps": {}, "system": {} }
Les trois dernières lignes du fichier doivent alors ressembler à ça :
"categories": [],
"antifeatures": [],
"security": { "version": 1, "apps": {}, "system": {} }
}
Commit changes, puis sur le serveur :
sudo yunohost tools update apps
python3 -c "import json,pathlib;p=pathlib.Path('v3/apps.json');d=json.loads(p.read_text(encoding='utf-8'));d['security']={'version':1,'apps':{},'system':{}};p.write_text(json.dumps(d,indent=2,sort_keys=True,ensure_ascii=False)+'\n',encoding='utf-8',newline='\n')"— puis commit et push.
Corrupted JSON read from ... en boucle
L’adresse de votre catalogue ne renvoie pas du JSON. Voir Retour arrière ci-dessous, puis reprenez l’étape 7a.
Toutes mes applications officielles ont perdu leur bouton de mise à jour
Vous avez probablement créé apps_catalog.yml sans la ligne - id: default. Reprenez le Cas A de l’étape 7c, qui remet les deux entrées.
Retour arrière
Un catalogue ne modifie aucune de vos installations : le retirer est totalement sans risque pour vos applications et vos données.
Si vous aviez créé le fichier uniquement pour ce catalogue :
sudo rm /etc/yunohost/apps_catalog.yml
Sinon, retirez seulement votre ligne :
sudo sed -i '/id: moncata/,+1d' /etc/yunohost/apps_catalog.yml
Puis, dans les deux cas :
sudo yunohost tools update apps
Vous revenez à l’état initial : le bandeau gris réapparaît, et la mise à jour manuelle reste toujours possible avec yunohost app upgrade MON-NOM -u <adresse>.