# French-Influence — installation complète sur o2switch

Ce paquet contient l’application de production déjà compilée pour **Node.js 22**, un adaptateur **MariaDB**, un stockage de documents privé, l’envoi d’emails par **SMTP**, le processeur de tâches planifiées et les outils de diagnostic/sauvegarde.

Il ne contient aucun compte, affilié, offre, conversion ou paiement fictif. Le premier compte Super Admin est créé par l’assistant `/setup`.

> Version du guide : 12 août 2026. Les intitulés cPanel peuvent légèrement varier selon le thème ou l’offre o2switch.

## 1. Architecture livrée

- `app.cjs` : point d’entrée Passenger compatible cPanel.
- `server.js` : point d’entrée Node autonome pour les diagnostics.
- `dist/` : application French-Influence compilée.
- `runtime-env.mjs` : connexion MariaDB, fichiers privés et SMTP.
- `cron.js` : maintenance, file d’emails/webhooks et expirations.
- `scripts/generate-secrets.js` : création sécurisée du fichier `.env`.
- `scripts/check-install.js` : test complet MariaDB, migrations et stockage.
- `scripts/test-smtp.js` : test d’envoi d’un email.
- `scripts/backup.js` : sauvegarde MariaDB, fichiers privés et environnement.
- `var/private/` : documents KYC et justificatifs, hors accès public.
- `var/backups/` : sauvegardes locales complémentaires.
- `var/logs/` : journaux cron.

## 2. Ce qu’il faut préparer

Vous devez disposer de :

1. un hébergement o2switch avec accès cPanel ;
2. un nom de domaine pointant vers o2switch ;
3. une adresse email transactionnelle, par exemple `notifications@votre-domaine.fr` ;
4. un client SSH, ou le Terminal cPanel ;
5. l’archive `French-Influence-o2switch.zip`.

L’application exige Node.js **22.13 ou supérieur**. Sélectionnez Node.js 22 dans cPanel.

## 3. Choisir les URLs

Configuration recommandée pour la première mise en ligne :

```text
APP_URL=https://votre-domaine.fr
TRACKING_DOMAIN=https://votre-domaine.fr
```

Les liens de tracking auront alors la forme :

```text
https://votre-domaine.fr/go/TOKEN
```

Un sous-domaine dédié, comme `go.votre-domaine.fr`, pourra être ajouté plus tard. Il devra pointer vers **la même application Passenger** ; changer uniquement `TRACKING_DOMAIN` ne suffit pas à configurer le routage du sous-domaine.

## 4. Faire pointer le domaine et activer HTTPS

1. Dans cPanel, ouvrez **Domaines configurés** et ajoutez le domaine si nécessaire.
2. Si le domaine est géré ailleurs, faites-le pointer vers l’hébergement o2switch.
3. Attendez la propagation DNS.
4. Ouvrez **Let’s Encrypt SSL** dans cPanel.
5. Générez un certificat pour le domaine utilisé par French-Influence.
6. Vérifiez que `https://votre-domaine.fr` répond avant de poursuivre.

Ne déployez jamais temporairement la plateforme en HTTP : les sessions, l’administration et les postbacks doivent fonctionner en HTTPS dès l’installation.

Documentation o2switch :

- Domaine : https://faq.o2switch.fr/cpanel/domaines/configuration-domaine/
- Sous-domaine : https://faq.o2switch.fr/cpanel/domaines/configuration-sous-domaine/
- Let’s Encrypt : https://faq.o2switch.fr/cpanel/securite/lets-encrypt-ssl-gratuit/

## 5. Créer la base MariaDB

Dans cPanel, ouvrez **Bases de données MySQL** puis :

1. créez une base dédiée, par exemple `frenchinfluence` ;
2. créez un utilisateur dédié, avec un mot de passe long et unique ;
3. associez cet utilisateur à cette base ;
4. accordez-lui **tous les privilèges sur cette base uniquement** ;
5. notez les noms complets préfixés par votre identifiant cPanel.

Exemple :

```text
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=moncompte_frenchinfluence
DB_USER=moncompte_frenchinfluence
DB_PASSWORD=mot-de-passe-unique
```

N’utilisez pas l’utilisateur d’une autre application et ne réutilisez pas le mot de passe cPanel.

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

## 6. Extraire le paquet hors de `public_html`

Le code, le fichier `.env` et les documents KYC ne doivent jamais se trouver dans un répertoire directement public.

1. Ouvrez le **Gestionnaire de fichiers** cPanel.
2. Placez l’archive dans votre dossier personnel, pas dans `public_html`.
3. Extrayez-la.
4. Vous devez obtenir un dossier similaire à :

```text
/home/VOTRE_LOGIN/french-influence
```

Le contenu attendu à sa racine comprend `app.cjs`, `server.js`, `package.json`, `dist/`, `scripts/` et ce guide.

Permissions conseillées en SSH :

```bash
cd /home/VOTRE_LOGIN/french-influence
mkdir -p var/private var/backups var/logs
chmod 700 var var/private var/backups var/logs
```

## 7. Créer l’application Node.js dans cPanel

Dans **Setup Node.js App** :

1. cliquez sur **Create Application** ;
2. sélectionnez **Node.js 22** ;
3. choisissez le mode **Production** ;
4. indiquez comme *Application root* : `french-influence` ;
5. choisissez votre domaine comme *Application URL* ;
6. indiquez `app.cjs` comme *Application startup file* ;
7. définissez un fichier de log hors du répertoire public, par exemple `/home/VOTRE_LOGIN/french-influence/var/logs/passenger.log` ;
8. créez l’application.

Passenger relie automatiquement le domaine à l’application et gère son redémarrage. Ne lancez pas manuellement un serveur permanent sur le port 3000.

Documentation officielle : https://faq.o2switch.fr/cpanel/logiciels/hebergement-nodejs-multi-version/

## 8. Installer les dépendances

Dans la page de l’application Node, copiez la commande `source .../nodevenv/.../22/bin/activate` fournie par cPanel.

En SSH ou dans le Terminal cPanel :

```bash
source /home/VOTRE_LOGIN/nodevenv/french-influence/22/bin/activate
cd /home/VOTRE_LOGIN/french-influence
npm ci --omit=dev
```

Si cPanel propose un bouton **Run NPM Install**, vous pouvez l’utiliser à la place, mais `npm ci --omit=dev` reste préférable lorsqu’un `package-lock.json` est fourni.

Vérifiez ensuite :

```bash
node --version
npm --version
```

La version Node affichée doit être 22.13 ou supérieure.

## 9. Générer les secrets et configurer `.env`

Toujours dans le dossier de l’application :

```bash
node scripts/generate-secrets.js
chmod 600 .env
```

Le script crée trois secrets indépendants :

- `APP_ENCRYPTION_KEY` pour chiffrer les données sensibles ;
- `IP_HASH_SALT` pour pseudonymiser les adresses IP ;
- `SETUP_TOKEN` pour protéger l’installation initiale.

Éditez ensuite `.env` avec le Gestionnaire de fichiers ou un éditeur SSH. Remplacez obligatoirement :

- `APP_URL` ;
- `TRACKING_DOMAIN` ;
- `DB_DATABASE` ;
- `DB_USER` ;
- `DB_PASSWORD` ;
- les paramètres SMTP.

Règles importantes :

- URLs en `https://`, sans slash final ;
- `DB_HOST=localhost` chez o2switch ;
- aucun guillemet n’est requis dans `.env` ;
- ne transmettez jamais ce fichier par email ou ticket non chiffré ;
- ne modifiez plus `APP_ENCRYPTION_KEY` après l’enregistrement de secrets ou moyens de paiement.

## 10. Configurer l’email SMTP

Créez d’abord une adresse dans **cPanel > Comptes de messagerie**, par exemple `notifications@votre-domaine.fr`.

Configuration o2switch habituelle :

```text
SMTP_HOST=nom-du-serveur.o2switch.net
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=notifications@votre-domaine.fr
SMTP_PASSWORD=mot-de-passe-de-la-boite
MAIL_FROM=French-Influence <notifications@votre-domaine.fr>
MAIL_REPLY_TO=support@votre-domaine.fr
```

Le nom exact du serveur figure dans l’email **Bienvenue chez o2switch** et dans le détail de l’hébergement. L’authentification SMTP est obligatoire.

Testez l’envoi :

```bash
node scripts/test-smtp.js votre-adresse-de-test@domaine.fr
```

Documentation : https://faq.o2switch.fr/cpanel/emails/adresse-email/

## 11. Vérifier et initialiser l’installation

Lancez :

```bash
node scripts/check-install.js
```

Le résultat attendu est :

```text
MariaDB: OK
Migrations: OK
Stockage privé: OK
Assistant initial: à exécuter
```

Cette commande :

- vérifie les secrets et les URLs ;
- vérifie la connexion MariaDB ;
- crée les tables et indexes ;
- initialise uniquement les rôles et permissions système ;
- teste en écriture et lecture le stockage privé ;
- ne crée aucune donnée métier fictive.

En cas d’erreur, ne poursuivez pas vers `/setup` avant de l’avoir corrigée.

## 12. Démarrer ou redémarrer Passenger

Retournez dans **Setup Node.js App**, ouvrez French-Influence puis cliquez sur **Restart**.

Consultez ensuite :

```text
https://votre-domaine.fr/
https://votre-domaine.fr/api/setup
```

La seconde URL doit retourner un JSON indiquant que l’installation est requise et que le token est configuré.

## 13. Créer le premier Super Admin

Ouvrez :

```text
https://votre-domaine.fr/setup
```

Renseignez :

- nom de la plateforme ;
- prénom et nom du responsable ;
- email du Super Admin ;
- mot de passe d’au moins 12 caractères avec majuscule, minuscule et chiffre ;
- fuseau horaire ;
- devise principale ;
- la valeur exacte de `SETUP_TOKEN` contenue dans `.env`.

L’assistant crée un unique Super Admin et les réglages fondamentaux. Il refuse toute nouvelle installation dès qu’un utilisateur existe.

Après réussite :

1. videz la valeur `SETUP_TOKEN=` dans `.env` ;
2. redémarrez l’application dans cPanel ;
3. reconnectez-vous ;
4. ouvrez **Admin > Paramètres** et activez la double authentification ;
5. conservez les codes de récupération hors ligne.

## 14. Configurer les tâches planifiées

French-Influence utilise une file persistante MariaDB pour les emails, webhooks sortants, expirations et opérations de maintenance. Le cron ne calcule pas les clics ou commissions critiques : ces écritures sont persistées pendant la requête.

Dans **cPanel > Tâches cron**, ajoutez une exécution toutes les cinq minutes :

```bash
source /home/VOTRE_LOGIN/nodevenv/french-influence/22/bin/activate && cd /home/VOTRE_LOGIN/french-influence && node cron.js >> var/logs/cron.log 2>&1
```

Fréquence :

```text
*/5 * * * *
```

Ajoutez également une sauvegarde quotidienne, par exemple à 03:20 :

```bash
source /home/VOTRE_LOGIN/nodevenv/french-influence/22/bin/activate && cd /home/VOTRE_LOGIN/french-influence && node scripts/backup.js >> var/logs/backup.log 2>&1
```

Fréquence :

```text
20 3 * * *
```

Documentation cron : https://faq.o2switch.fr/cpanel/outils-avances/tache-planifiee-cron/

## 15. Vérifications de santé

Une fois connecté comme Super Admin, ouvrez :

```text
https://votre-domaine.fr/api/health
```

Les contrôles doivent indiquer :

- `database: ok` ;
- `private_storage: ok` ;
- `mail: ok` ;
- `encryption: ok` ;
- domaine de tracking configuré.

Vérifiez aussi :

```bash
tail -n 100 var/logs/passenger.log
tail -n 100 var/logs/cron.log
tail -n 100 var/logs/backup.log
```

## 16. Premier paramétrage métier

Respectez cet ordre afin de conserver toutes les relations et la traçabilité :

1. **Admin > Providers** : créez le vrai programme/réseau amont.
2. **Admin > Marques** : créez une vraie marque rattachée au provider.
3. **Admin > Campaigns** : ajoutez l’identifiant externe réel.
4. **Admin > Promos** : ajoutez les promotions réelles, si nécessaires.
5. **Admin > Offres** : renseignez landing, template de tracking, devise, GEO, restrictions et fallback.
6. **Admin > Postbacks** : créez la configuration, les mappings, le secret HMAC et l’allowlist IP si le provider les supporte.
7. Copiez l’URL générée `/api/postback/TOKEN` dans le programme amont.
8. **Admin > Deals** : créez le deal par défaut ou le deal propre à l’affilié avec date d’effet.
9. Invitez ou approuvez l’affilié.
10. Accordez l’accès à l’offre.
11. L’affilié crée son lien depuis **Liens & Créatifs**.
12. Testez un clic réel puis un postback marqué comme test.

Ne créez pas un deal rétroactif et ne remplacez jamais des identifiants externes réels par des valeurs inventées.

## 17. Configurer le premier postback

Dans **Admin > Postbacks** :

1. sélectionnez le provider ;
2. choisissez GET, POST ou ANY selon sa documentation ;
3. mappez ses paramètres vers les champs normalisés ;
4. configurez `event`, `player_id`, `visit_id`, `deposit_id`, `amount`, `currency`, `campaign_id` et `promo_id` selon les données disponibles ;
5. activez HMAC et l’allowlist IP lorsque le fournisseur les propose ;
6. copiez l’URL générée ;
7. faites un test identifié comme tel ;
8. vérifiez son statut dans les logs postbacks ;
9. renvoyez exactement le même test pour vérifier la déduplication.

Les événements `test` ne doivent générer ni statistique ni commission réelle.

## 18. Workflow affilié et paiement

1. L’affilié s’inscrit ou accepte son invitation.
2. Il complète son profil et transmet les documents KYC.
3. L’administrateur valide le compte et les documents.
4. L’administrateur donne accès aux offres et attribue le deal.
5. L’affilié crée ses liens et envoie son trafic.
6. Les postbacks alimentent conversions et ledger.
7. Seules les écritures approuvées deviennent disponibles.
8. L’affilié configure un moyen de paiement.
9. Il demande son paiement si les conditions sont remplies.
10. La finance approuve, traite puis marque le paiement comme payé avec sa référence réelle.

La plateforme n’exécute aucun virement bancaire ou crypto sans API réelle configurée. Elle gère le workflow, le ledger, les références et les justificatifs.

## 19. Sauvegardes et restauration

La commande `node scripts/backup.js` sauvegarde :

- MariaDB dans `database.sql` avec une lecture transactionnelle ;
- les documents privés dans `private-storage.tar.gz` ;
- le fichier `.env` ;
- un manifeste horodaté.

Les sauvegardes sont placées dans `var/backups/` et conservées pendant `BACKUP_RETENTION_DAYS` jours.

Pour une vraie stratégie de production :

1. conservez la sauvegarde quotidienne locale ;
2. copiez régulièrement les archives vers un stockage externe chiffré ;
3. utilisez aussi JetBackup o2switch ;
4. testez une restauration sur un environnement isolé au moins tous les trimestres.

JetBackup ne remplace pas votre propre politique de sauvegarde : https://faq.o2switch.fr/cpanel/fichiers/sauvegarde-jetbackup/

Restauration manuelle contrôlée :

1. activez le mode maintenance ou stoppez l’application ;
2. sauvegardez l’état courant avant toute écriture ;
3. importez `database.sql` dans la base dédiée avec phpMyAdmin ou la commande `mysql` ;
4. restaurez `private-storage.tar.gz` uniquement dans `var/private` ;
5. restaurez `.env` avec permission `600` ;
6. exécutez `node scripts/check-install.js` ;
7. redémarrez l’application ;
8. contrôlez `/api/health`, les soldes, les derniers postbacks et les derniers paiements.

Ne restaurez jamais une base de données au-dessus d’une production active sans sauvegarde préalable.

## 20. Mise à jour de French-Influence

Avant chaque mise à jour :

```bash
cd /home/VOTRE_LOGIN/french-influence
node scripts/backup.js
```

Ensuite :

1. stoppez l’application dans cPanel ;
2. conservez `.env` et tout le dossier `var/` ;
3. extrayez la nouvelle archive dans un dossier temporaire ;
4. remplacez `dist/`, `app.cjs`, `server.js`, `cron.js`, `runtime-env.mjs`, `mysql-compat.mjs`, `scripts/`, `package.json` et `package-lock.json` ;
5. ne remplacez pas `.env` ni `var/` ;
6. relancez `npm ci --omit=dev` ;
7. lancez `node scripts/check-install.js` ;
8. redémarrez l’application ;
9. testez la connexion, un lien de tracking et le cron.

Les migrations sont idempotentes : elles créent les structures absentes sans effacer les données existantes.

## 21. Sécurité avant ouverture au public

- HTTPS actif sur toutes les URLs.
- Application située hors de `public_html`.
- `.env`, `var/private` et sauvegardes en permission `700/600`.
- Utilisateur MariaDB propre à French-Influence.
- `SETUP_TOKEN` vidé après installation.
- 2FA activée pour le Super Admin et les comptes sensibles.
- Mots de passe uniques et gestionnaire de mots de passe.
- SMTP avec TLS.
- HMAC et allowlist IP sur les postbacks lorsque disponibles.
- Aucun secret provider transmis au navigateur.
- Sauvegardes externes chiffrées et restauration testée.
- Journaux Passenger/cron contrôlés régulièrement.
- Versions Node et dépendances maintenues à jour.

## 22. Diagnostic des erreurs courantes

### La page affiche une erreur 500

1. ouvrez `var/logs/passenger.log` ;
2. vérifiez que Node 22 est sélectionné ;
3. vérifiez que le fichier de démarrage est exactement `app.cjs` ;
4. relancez `npm ci --omit=dev` dans l’environnement Node cPanel ;
5. lancez `node scripts/check-install.js` ;
6. vérifiez les variables MariaDB dans `.env` ;
7. redémarrez l’application.

### `/setup` indique que le stockage est indisponible

La migration MariaDB n’a pas abouti. Vérifiez : nom de base, utilisateur, mot de passe, privilèges, `DB_HOST=localhost`, puis relancez le diagnostic.

### Les styles ou images ne chargent pas

Vérifiez que `dist/client/assets` et `dist/client/media` existent et que l’archive a été entièrement extraite.

### Les emails ne partent pas

1. contrôlez `SMTP_HOST`, `SMTP_USER`, `SMTP_PASSWORD` ;
2. utilisez le nom de serveur o2switch et le port 465 avec TLS ;
3. lancez `node scripts/test-smtp.js adresse@domaine.fr` ;
4. vérifiez SPF/DKIM dans cPanel ;
5. consultez `var/logs/cron.log` pour les emails en file.

### Les tâches restent en attente

Vérifiez que le cron s’exécute toutes les cinq minutes et que la commande commence bien par la commande `source` fournie par l’application Node cPanel.

### Un postback n’est pas attribué

Contrôlez dans cet ordre : token d’URL, statut de la configuration, HMAC, IP autorisée, mapping, `visit_id`/`click_id`, offre, campagne et logs de l’événement non attribué.

### Les liens redirigent vers la mauvaise URL

Vérifiez le template de tracking de l’offre, les macros, la landing, le fallback, le statut de l’offre et `TRACKING_DOMAIN`.

## 23. Limites raisonnables de l’hébergement mutualisé

Cette édition est pleinement opérationnelle sur o2switch avec Passenger, MariaDB et stockage local privé. Un hébergement mutualisé possède néanmoins des limites CPU, mémoire et nombre de processus.

Surveillez particulièrement :

- le volume de clics par seconde ;
- la taille des logs postbacks ;
- la durée des exports ;
- la taille des documents KYC ;
- la fréquence des tâches ;
- le nombre de connexions MariaDB.

Si le trafic de tracking devient massif ou exige une disponibilité contractualisée, migrez l’application vers une infrastructure dédiée ou managée sans modifier le modèle métier. Ne masquez jamais une saturation par une perte silencieuse de clics ou de postbacks.

## 24. Checklist finale

### Infrastructure

- [ ] Domaine pointé vers o2switch
- [ ] Certificat Let’s Encrypt actif
- [ ] Application Node 22 en mode Production
- [ ] Code hors de `public_html`
- [ ] MariaDB dédiée et utilisateur dédié
- [ ] `npm ci --omit=dev` terminé
- [ ] `.env` renseigné et permission 600
- [ ] `node scripts/check-install.js` entièrement vert
- [ ] SMTP testé
- [ ] Cron cinq minutes configuré
- [ ] Sauvegarde quotidienne configurée

### Sécurité

- [ ] Super Admin réel créé
- [ ] `SETUP_TOKEN` vidé puis application redémarrée
- [ ] 2FA du Super Admin activée
- [ ] Codes de récupération conservés hors ligne
- [ ] Sauvegarde externe chiffrée
- [ ] Aucune donnée commerciale fictive

### Métier

- [ ] Premier provider réel créé
- [ ] Marque/campaign/promo réelles configurées
- [ ] Offre et fallback vérifiés
- [ ] Postback test reçu puis dédupliqué
- [ ] Deal amont et deal affilié datés
- [ ] Affilié approuvé et accès accordé
- [ ] Lien de tracking testé
- [ ] Registration/FTD/qualification vérifiés
- [ ] Ledger et marge contrôlés
- [ ] Demande de paiement et workflow contrôlés

Lorsque toutes les cases sont validées, French-Influence est prête à recevoir des utilisateurs et des événements réels.
