# Installation complète de FreshPlanner sur o2switch

Cette installation utilise deux sous-domaines et deux applications Node.js distinctes :

- `planner.stack3d.fr` : interface, API et accès à la base MySQL ;
- `mailplanner.stack3d.fr` : passerelle SMTP privée, appelée par l’interface.

La séparation évite d’exposer le mot de passe SMTP dans le navigateur. Le même hébergement o2switch peut faire fonctionner les deux applications.

## 1. Préparer les deux sous-domaines

Dans cPanel, ouvrez **Sous-domaines** et créez `planner` puis `mailplanner` sous `stack3d.fr`. Laissez cPanel proposer deux document roots distincts. Si le DNS de `stack3d.fr` n’est pas géré par o2switch, ajoutez chez votre fournisseur DNS deux enregistrements A pointant vers l’adresse IP de l’hébergement.

Attendez que les deux noms répondent, puis ouvrez **Status SSL/TLS**. Les deux lignes doivent avoir un certificat valide. Lancez AutoSSL si cPanel le propose. Ne continuez pas avec un avertissement de certificat : l’interface refusera volontairement une passerelle mail non HTTPS.

Références officielles :

- https://faq.o2switch.fr/cpanel/domaines/configuration-sous-domaine/
- https://faq.o2switch.fr/cpanel/securite/status-certificat-ssl/

## 2. Créer la base MySQL

Dans **Bases de données MySQL** :

1. créez une base, par exemple `freshplan` ;
2. créez un utilisateur MySQL avec un mot de passe long ;
3. associez cet utilisateur à la base et cochez **Tous les privilèges** ;
4. notez les noms complets affichés par cPanel, par exemple `compte_freshplan` et `compte_freshusr`.

Dans **phpMyAdmin** :

1. cliquez sur la base fraîchement créée dans la colonne de gauche ;
2. ouvrez l’onglet **Importer** ;
3. choisissez `database/schema.sql`, présent dans le ZIP de l’interface ;
4. lancez l’import. Les tables `employees`, `vacations`, `shifts`, `settings` et `daily_staffing_rules` doivent apparaître.

L’hôte MySQL o2switch est `localhost`.

Références officielles :

- https://faq.o2switch.fr/cpanel/bases-de-donnees/mysql/
- https://faq.o2switch.fr/cpanel/bases-de-donnees/phpmyadmin/

## 3. Créer l’adresse d’envoi

Dans **Comptes de messagerie**, créez par exemple `planning@stack3d.fr` et conservez son mot de passe. Retrouvez dans le message « Bienvenue chez o2switch » le nom du serveur sous la forme `xxxx.o2switch.net`.

Les paramètres utilisés seront : serveur SMTP `xxxx.o2switch.net`, port `465`, SSL/TLS activé, identifiant égal à l’adresse e-mail complète.

Référence officielle : https://faq.o2switch.fr/guides/emails/client/configurer-outlook/

## 4. Générer les secrets

Dans un terminal, générez deux valeurs différentes :

```bash
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
```

- première valeur : `MAIL_GATEWAY_TOKEN`, identique dans les deux applications ;
- seconde valeur : `APP_PASSWORD`, mot de passe d’accès à l’interface.

Ne publiez jamais ces valeurs et ne les ajoutez pas à un dépôt Git.

## 5. Installer la passerelle mail

1. Dans le gestionnaire de fichiers cPanel, créez à la racine du compte un dossier `freshplanner-mail`. Il doit être hors du document root de `mailplanner.stack3d.fr`.
2. Téléversez `FreshPlanner-mail-o2switch.zip` dans ce dossier et extrayez-le. `server.mjs` et `package.json` doivent se trouver directement dans `freshplanner-mail`, pas dans un sous-dossier supplémentaire.
3. Ouvrez **Setup Node.js App**, puis **Create Application**.
4. Choisissez Node.js **22** ou **24**, mode **Production**.
5. Définissez **Application root** sur `freshplanner-mail`.
6. Définissez **Application URL** sur `mailplanner.stack3d.fr`, sans chemin supplémentaire.
7. Définissez **Application startup file** sur `server.mjs`.
8. Créez l’application, puis ajoutez ces variables :

```text
SMTP_HOST=xxxx.o2switch.net
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=planning@stack3d.fr
SMTP_PASS=mot-de-passe-de-la-boite
SMTP_FROM=FreshPlanner <planning@stack3d.fr>
MAIL_GATEWAY_TOKEN=secret-genere-a-etape-4
```

9. Utilisez **Run NPM Install** / la détection de `package.json`. À défaut, copiez la commande `source ...` affichée par cPanel dans une session SSH, placez-vous dans le dossier et lancez `npm install`.
10. Cliquez sur **Restart**.
11. Ouvrez `https://mailplanner.stack3d.fr/health`. La réponse doit indiquer `ok: true`.

Voir les journaux Passenger si la page ne répond pas. Une page « Route introuvable » sur une autre adresse signifie généralement que l’URL testée ne correspond pas à l’**Application URL** de cette application.

## 6. Installer l’interface

1. Dans le gestionnaire de fichiers cPanel, créez à la racine du compte un dossier `freshplanner-interface`, hors du document root de `planner.stack3d.fr`.
2. Téléversez `FreshPlanner-interface-o2switch.zip` dans ce dossier et extrayez-le. `server.mjs`, `package.json`, `app` et `database` doivent être directement dans `freshplanner-interface`.
3. Dans **Setup Node.js App**, créez une seconde application.
4. Choisissez Node.js **22** ou **24**, mode **Production**.
5. Définissez **Application root** sur `freshplanner-interface`.
6. Définissez **Application URL** sur `planner.stack3d.fr`, sans chemin supplémentaire.
7. Définissez **Application startup file** sur `server.mjs`.
8. Ajoutez les variables suivantes en remplaçant les exemples :

```text
APP_USER=admin
APP_PASSWORD=second-secret-genere-a-etape-4
DB_HOST=localhost
DB_PORT=3306
DB_NAME=compte_freshplan
DB_USER=compte_freshusr
DB_PASSWORD=mot-de-passe-mysql
MAIL_GATEWAY_URL=https://mailplanner.stack3d.fr
MAIL_GATEWAY_TOKEN=secret-genere-a-etape-4
```

9. Installez les dépendances. Pour la construction, utilisez de préférence une connexion SSH classique : copiez d’abord la commande `source ...` affichée par cPanel, puis exécutez dans le dossier de l’application :

```bash
npm install
npm run build
```

10. Revenez dans **Setup Node.js App** et cliquez sur **Restart**.
11. Vérifiez `https://planner.stack3d.fr/health`, puis ouvrez `https://planner.stack3d.fr`. Le navigateur demandera `APP_USER` et `APP_PASSWORD`.

La documentation o2switch recommande de garder l’Application root séparé du document root public. Elle explique aussi que Passenger lance l’application : ne démarrez pas durablement `node server.mjs` à la main.

Référence officielle : https://faq.o2switch.fr/cpanel/logiciels/hebergement-nodejs-multi-version/

## 7. Test fonctionnel

Dans FreshPlanner :

1. modifiez la ville du magasin ;
2. ajoutez un employé avec son e-mail ;
3. ajoutez un congé ;
4. changez de semaine, modifiez un créneau puis revenez sur cette semaine ;
5. exportez le CSV ;
6. cliquez sur **Envoyer par e-mail** et utilisez une adresse dont vous pouvez vérifier la réception.

Les données doivent rester présentes après un redémarrage de l’application. Si l’envoi échoue, vérifiez en priorité que les deux `MAIL_GATEWAY_TOKEN` sont strictement identiques.

## 8. Sauvegardes et mises à jour

- Sauvegardez régulièrement la base via **phpMyAdmin > Exporter**.
- Pour une mise à jour de l’interface : remplacez les fichiers, exécutez `npm install` puis `npm run build`, et redémarrez l’application.
- Pour une mise à jour de la passerelle : remplacez les fichiers, exécutez `npm install`, puis redémarrez.
- Ne remplacez pas les variables d’environnement lors d’une mise à jour.

## Dépannage rapide

- **Page 503 / application indisponible** : consultez le journal Passenger et vérifiez que le fichier de démarrage est exactement `server.mjs`.
- **Configuration manquante** : une variable obligatoire est absente ; son nom apparaît dans le journal.
- **Base de données indisponible** : vérifiez les noms MySQL préfixés, le mot de passe, les privilèges et `DB_HOST=localhost`.
- **Route introuvable** : vérifiez le sous-domaine attaché à la bonne application Node et testez `/health`.
- **Accès refusé par la passerelle** : les tokens diffèrent.
- **Échec SMTP** : vérifiez le nœud `xxxx.o2switch.net`, le port 465, SSL, l’adresse complète et le mot de passe de la boîte.
- **Certificat non fiable** : corrigez d’abord le certificat dans **Status SSL/TLS** ; ne remplacez pas l’URL HTTPS par HTTP.
- **Erreur pendant `npm install` ou `npm run build` dans le Terminal cPanel** : recommencez via un client SSH, qui dispose de moins de restrictions de ressources selon la documentation o2switch.