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

```bash
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 :

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

## Aperçu et édition en local

```bash
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

```bash
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

```json
{ "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` :
  ```json
  { "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

```bash
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 :

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

### Configurer `.env`

```bash
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 :

```dotenv
# 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 :

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