Yunohost_homePage/README.md

Yunohost_homePage

Page d'accueil YunoHost personnalisée : applications épinglées en haut de page, groupes repliables/réordonnables, applications sans groupe, bouton Administration à côté de Déconnexion, et détection automatique du logo de chaque application (favicon ou logo officiel YunoHost).

Ce dépôt contient le code générique, réutilisable par n'importe qui a une instance YunoHost — toutes les informations spécifiques à un serveur (domaine, identifiants SSH, mot de passe) vivent uniquement dans un fichier .env local, jamais commité. src/config.json (tes apps/groupes) est lui aussi local et ignoré par git — voir plus bas comment le renseigner.

Structure du projet

src/       sources de la page (index.html, style.css, app.js)
           et de l'éditeur visuel (editor.html/css/js)
           + config.json (tes données, ignoré par git — voir ci-dessous)
           + config.example.json (exemple versionné, point de départ)
scripts/   scripts d'outillage (preview, export, sync, déploiement)
output/    généré par "make export" — c'est ce dossier qui est envoyé
           sur le serveur YunoHost (ignoré par git)
Makefile   regroupe toutes les commandes ci-dessous
.env       tes identifiants/domaine (créé par "make config", jamais commité)

Démarrage rapide

make help     # liste toutes les commandes
make config   # crée .env et src/config.json (depuis les .example) si absents

Édite ensuite :

• .env avec les infos de ton instance YunoHost (voir les commentaires dans .env.example),
• src/config.json avec tes propres applications et groupes — soit à la main (voir la section dédiée plus bas), soit via l'éditeur visuel une fois le serveur lancé, soit en copiant un fichier existant si tu en as déjà un ailleurs (ex. un dépôt séparé où tu gardes tes configs personnelles).

Puis :

make serve    # lance l'apercu + l'editeur en local

Aperçu et édition en local

make serve

(Ctrl+C arrête le serveur.) Un port différent : make serve PORT=8080.

Ça ouvre deux onglets :

• http://localhost:8000/editor.html — éditeur : glisser-déposer les applications entre groupes, vers/depuis "Sans groupe" ou vers/depuis "Épinglées" (tout en haut, en dehors de tout groupe), réordonner les groupes (poignée ⠿), les renommer (clic sur le nom), cocher "replié par défaut", ajouter (+) ou supprimer (✕) une application ou un groupe.
  • Le bouton Enregistrer écrit dans src/config.json.
  • Le bouton Exporter enregistre puis copie les fichiers déployables (index.html, style.css, app.js, config.json) dans output/ — c'est ce dossier, pas src/, qui est envoyé sur le serveur.
• http://localhost:8000/ — aperçu de la page finale (celle de src/), avec rechargement automatique dès qu'un fichier change.

Cette partie ne nécessite aucune information sur ton serveur : tout est local.

Récupérer automatiquement les apps installées sur YunoHost

make sync

Se connecte en SSH (SYNC_SSH_USER@SYNC_SSH_HOST défini dans .env), récupère la vraie liste des apps installées sur PORTAL_DOMAIN avec leur nom/URL/logo officiels, et ajoute dans ungrouped uniquement celles qui manquent encore (comparaison par URL). N'écrase jamais une app déjà classée dans un groupe ou épinglée.

⚠️ Nécessite un accès root (ou un compte avec sudo, mot de passe requis à chaque appel) sur le serveur : le fichier lu (/etc/yunohost/portal/<domaine>.json) n'est lisible par aucun compte moins privilégié, y compris le compte applicatif utilisé pour le déploiement.

Gérer les applications à la main (optionnel)

Tout se configure aussi directement dans src/config.json (voir src/config.example.json pour un point de départ), si tu préfères éditer le fichier toi-même plutôt que d'utiliser l'éditeur visuel.

Ajouter une application

{ "id": "monapp", "name": "Mon App", "url": "/monapp/", "color": "#2196f3", "initials": "MA" }

• id : identifiant unique, sans espace.
• name : nom affiché sous la tuile.
• url : chemin réel de l'appli sur le domaine (ex. /navidrome/). C'est à partir de cette URL que la page tente de charger favicon.ico automatiquement.
• color / initials : filet de sécurité si aucun favicon ne charge (pastille colorée avec initiales).
• icon (optionnel) : force une image précise plutôt que le favicon auto-détecté, ex. "icon": "https://...".

Ajoute l'objet dans le tableau apps d'un groupe existant, dans le tableau racine pinned (épinglées en haut de page) ou dans ungrouped si elle ne doit appartenir à aucun groupe.

Supprimer une application

Supprime son objet { ... } dans le tableau où elle se trouve. Attention aux virgules JSON (pas de virgule surnuméraire).

Gérer les groupes

• Créer : ajoute un objet dans le tableau racine groups :

  { "id": "domotique", "name": "Domotique", "collapsed": false, "apps": [] }
  

• Réordonner : l'ordre des objets dans groups = l'ordre vertical affiché.
• Renommer : change le champ name.
• Replié par défaut : "collapsed": true (le choix de chaque visiteur est ensuite mémorisé dans son navigateur et prend le dessus).
• Supprimer : retire l'objet de groups — déplace d'abord ses apps ailleurs, sinon elles disparaissent avec lui.

Vérifier que le JSON reste valide

python3 -m json.tool src/config.json > /dev/null && echo "JSON valide"

Déploiement sur YunoHost

Cette page est conçue pour être servie par une app "Custom Webapp" (my_webapp) YunoHost, définie comme application par défaut du domaine pour être visible à la racine (https://tondomaine/) — voir la doc YunoHost pour installer ce type d'app si ce n'est pas déjà fait.

Le déploiement se fait toujours à partir de output/, jamais de src/ directement :

make export   # (ou le bouton Exporter de l'éditeur) : src/ -> output/
make deploy   # envoie output/ sur le serveur

Configurer .env

make config

crée .env à partir de .env.example (déjà ignoré par git, ne sera jamais commité). Toutes les infos de connexion viennent de ce fichier — sans lui, make deploy et make sync s'arrêtent avec un message expliquant quoi renseigner :

# Déploiement
REMOTE_HOST=tondomaine.exemple
REMOTE_USER=my_webapp__x
REMOTE_PORT=22
REMOTE_PATH=/www/
REMOTE_PASSWORD=le-mot-de-passe-ici

# Synchronisation des apps (make sync)
SYNC_SSH_USER=root
SYNC_SSH_HOST=tondomaine.exemple
PORTAL_DOMAIN=tondomaine.exemple

scripts/deploy.sh charge ce fichier. Si REMOTE_PASSWORD est renseigné, il utilise sshpass (installé via make install) pour se connecter sans invite interactive. Sans mot de passe dans .env, ssh demandera la saisie manuelle — utile en terminal interactif, mais ne fonctionne pas dans un contexte sans terminal (script automatisé), où ssh échoue avec une erreur ssh_askpass.

⚠️ Le compte applicatif (REMOTE_USER) d'une "Custom Webapp" YunoHost est en général un compte SFTP uniquement, chrooté dans son propre dossier (ForceCommand internal-sftp côté serveur) :

• rsync ne fonctionne pas (il a besoin d'exécuter un shell distant) — scripts/deploy.sh utilise scp.
• REMOTE_PATH est relatif à la racine du chroot de cette app (/var/www/<REMOTE_USER>), donc /www/ et pas /var/www/<REMOTE_USER>/www/.

Authentification par clé SSH (alternative)

Pour ne plus dépendre du mot de passe pour le déploiement :

ssh-keygen -t ed25519 -C "deploy-yunohost-pageaccueil"
ssh-copy-id -p "$REMOTE_PORT" "$REMOTE_USER@$REMOTE_HOST"