# Déployer sur o2switch (API et application web)

Valable pour `myvolleyball-api` et `myvolleyball-app` : les deux dépôts se déploient de la même façon, par **releases** et un lien
`current` basculé en une fois. La CI est GitHub Actions ; la livraison passe par SSH (rsync) vers l'hébergement mutualisé cPanel.

| | dev | prod |
|---|---|---|
| Branche | `develop` | `main` |
| Web | `dapp9714.myvolleyball.org` | `app.myvolleyball.org` |
| API | `dapi1457.myvolleyball.org` | `papi1457.myvolleyball.org` |
| Dossier serveur (web) | `/home/<compte>/dapp9714` | `/home/<compte>/app` |
| Dossier serveur (API) | `/home/<compte>/dapi1457` | `/home/<compte>/papi1457` |
| Environnement GitHub | `dev` | `prod` (avec validation obligatoire) |

Arborescence d'un environnement après le premier déploiement :

```
<dossier>/
  releases/<date>-<sha>/…   les dernières releases (5 gardées)
  current -> releases/…     LE lien que lit le serveur web
  shared/                   (API seulement) .env.local, jwt/, storage/media/, log/ : survit aux releases
```

## 0. À vérifier avant tout (trois inconnues de l'hébergement)

1. **PHP 8.4 en ligne de commande.** Le `php` par défaut de cPanel est souvent plus ancien que celui du site. Chercher le bon
   binaire : `ls /opt/cpanel/ | grep ea-php` puis `/opt/cpanel/ea-php84/root/usr/bin/php -v`. Ce chemin devient `PHP_BIN`.
2. **Version de MySQL.** Le schéma exige **MySQL 8** (`utf8mb4_0900_ai_ci`, InnoDB). Si cPanel > MySQL® Databases / phpMyAdmin
   annonce **MariaDB**, les migrations échoueront : en parler au support o2switch avant d'aller plus loin.
3. **SSH depuis GitHub.** Certaines offres limitent l'accès SSH à une liste d'adresses IP : GitHub Actions n'a pas d'IP fixe. Demander
   au support « SSH ouvert sans restriction d'IP sur mon compte » ; sinon, déployer **à la main** avec le même script (§6).

## 1. cPanel : domaines, PHP, bases

1. **Domaines > Créer un sous-domaine** (quatre fois), en fixant la **racine du document** :

   | Sous-domaine | Racine du document |
   |---|---|
   | `dapi1457.myvolleyball.org` | `dapi1457/current/app/public` |
   | `papi1457.myvolleyball.org` | `papi1457/current/app/public` |
   | `dapp9714.myvolleyball.org` | `dapp9714/current` |
   | `app.myvolleyball.org` | `app/current` |

   (`current` n'existe pas encore : cPanel crée un dossier vide, le premier déploiement le remplace par le lien.)
2. **SSL/TLS Status** : lancer AutoSSL pour les quatre sous-domaines (certificat Let's Encrypt gratuit).
3. **MultiPHP Manager** : mettre `dapi1457` et `papi1457` en **PHP 8.4**. **Sélecteur de version PHP** (ou MultiPHP INI Editor) :
   extensions `intl`, `pdo_mysql`, `gd`, `sodium`, `fileinfo`, `opcache`, `mbstring`, `ctype`, `iconv` ; `upload_max_filesize` ≥ `100M` et
   `post_max_size` ≥ `110M` (vidéos de la communauté).
4. **MySQL® Databases** : créer **deux bases** et **deux utilisateurs** (jamais le même mot de passe), chacun avec tous les privilèges
   sur sa base seulement : une pour dev, une pour prod. Noter les noms complets (préfixés par le compte : `compte_myvb_dev`).
5. **Comptes e-mail** : créer `no-reply@myvolleyball.org`, puis ouvrir « Paramètres de configuration » de la boîte : serveur SMTP, port
   (465 SSL). Ces valeurs vont dans `MAILER_DSN`. Vérifier SPF et DKIM (« Email Deliverability »).

## 2. Clé SSH de déploiement

Sur ta machine (pas de phrase secrète : la CI ne peut pas la taper) :

```bash
ssh-keygen -t ed25519 -f ~/.ssh/myvb_deploy -C "deploy-myvolleyball" -N ""
cat ~/.ssh/myvb_deploy.pub          # la clé PUBLIQUE, à copier
```

1. cPanel > **Accès SSH** (SSH Access) > **Gérer les clés SSH** > **Importer une clé** : nom `myvb_deploy`, coller la clé publique
   (laisser la clé privée vide), Importer.
2. Retour à la liste, clé `myvb_deploy` > **Gérer** > **Authorize** (sans cette étape le serveur ignore la clé).
3. Tester : `ssh -i ~/.ssh/myvb_deploy <compte>@<serveur>` (le nom du serveur est donné dans cPanel, colonne de droite).
4. Empreinte du serveur, pour le secret `SSH_KNOWN_HOSTS` : `ssh-keyscan -p 22 <serveur>` (le serveur est authentifié ainsi, la CI
   refuse tout autre hôte).

La clé **privée** (`~/.ssh/myvb_deploy`) ne va qu'aux secrets GitHub ; ne jamais la committer.

## 3. GitHub : environnements, secrets, protections

Dans **chaque dépôt** (`myvolleyball-api` et `myvolleyball-app`) : Settings > Environments > créer `dev` et `prod`.

| Où | Nom | Valeur |
|---|---|---|
| Secret | `SSH_PRIVATE_KEY` | contenu de `~/.ssh/myvb_deploy` |
| Secret | `SSH_KNOWN_HOSTS` | sortie de `ssh-keyscan` |
| Variable | `DEPLOY_HOST` | le nom du serveur o2switch |
| Variable | `DEPLOY_USER` | le compte cPanel |
| Variable | `DEPLOY_PATH` | dossier de l'environnement : voir le tableau du haut (`/home/<compte>/dapi1457`…) |
| Variable | `PHP_BIN` | (API) `/opt/cpanel/ea-php84/root/usr/bin/php` |

Sur l'environnement **prod** : « Required reviewers » = toi. Un push sur `main` attend alors ton accord avant de livrer.
Settings > Branches : protéger `main` et `develop` (pull request obligatoire, statut `ci` vert obligatoire).

## 4. Première installation de l'API (une fois par environnement)

Sur ta machine, dans le dépôt `myvolleyball-api` (remplacer `<serveur>` et `<compte>`) :

```bash
# 1. arborescence, clés JWT, secrets, modèle de configuration
ssh -i ~/.ssh/myvb_deploy <compte>@<serveur> 'bash -s' -- dev /home/<compte>/dapi1457 < scripts/deploy/server-init.sh
ssh -i ~/.ssh/myvb_deploy <compte>@<serveur> 'bash -s' -- prod /home/<compte>/papi1457 < scripts/deploy/server-init.sh
```

2. Éditer sur le serveur `…/shared/.env.local` (cPanel > Gestionnaire de fichiers, ou `nano`) : remplacer `DATABASE_URL`
   (base et utilisateur de l'environnement, mot de passe encodé en URL, `serverVersion` = version réelle) et `MAILER_DSN`.
3. **Sauvegarder hors du serveur** `PII_KEY`, `JWT_PASSPHRASE` et le dossier `shared/jwt` (gestionnaire de mots de passe) : sans
   `PII_KEY`, les données personnelles chiffrées sont perdues pour toujours.
4. Déployer : `git push origin develop` (dev), puis fusionner `develop` dans `main` (prod). Suivre l'onglet **Actions**.
5. Sur le serveur, dans `…/current/app` (avec `PHP_BIN`) :
   ```bash
   <PHP_BIN> bin/console app:platform-admin:create --env=prod              # premier administrateur (mot de passe demandé à l'invite)
   <PHP_BIN> bin/console mailer:test toi@exemple.fr --from=no-reply@myvolleyball.org --env=prod
   ```
6. **cPanel > Tâches Cron** (chemin du `current`, jamais d'une release) :
   ```cron
   15 3 * * *    cd /home/<compte>/papi1457/current/app && <PHP_BIN> bin/console app:tokens:purge --env=prod
   30 3 * * *    cd /home/<compte>/papi1457/current/app && <PHP_BIN> bin/console app:deletions:purge --env=prod
   */10 * * * *  cd /home/<compte>/papi1457/current/app && <PHP_BIN> bin/console app:notifications:mail --env=prod
   ```
   (et les mêmes pour `dapi1457` si l'environnement dev doit les faire tourner.)
7. Contrôle : `https://dapi1457.myvolleyball.org/api/public/meta` répond en JSON ; la documentation `/api` est celle d'API Platform.
8. **Fichier de plateforme** (annonces, maintenance, fonctionnalités fermées, versions des apps) : copier
   `current/app/config/platform.yaml` vers `shared/platform.yaml` (le dossier `shared`, qui survit aux releases), puis ajouter dans
   `shared/.env.local` : `PLATFORM_CONFIG_FILE=/home/<compte>/papi1457/shared/platform.yaml`. Chaque modification se fait **dans ce
   fichier, par SSH ou le gestionnaire de fichiers cPanel, sans déploiement**, et se vérifie aussitôt :
   ```bash
   <PHP_BIN> bin/console app:platform:check --env=prod
   ```
   Un fichier refusé n'est pas appliqué : l'API journalise une erreur `critical` et utilise celui du dépôt (communauté fermée).
   Exemples : annonce d'incident (`announcements`, `level: warning`, texte `en` + `fr`), maintenance (`maintenance.enabled: true`,
   `staffRole: ROLE_ADMIN` pour garder la main), ouverture de la communauté (`features.community.state: enabled`, ou `unlockAt` /
   `unlockAtUsers`), nouvelle version de l'app (`clients.android.latest` + `updateUrl`).

## 5. Première installation de l'application web

Rien à préparer sur le serveur : le premier push sur `develop` / `main` crée les dossiers (`releases/`, `current`). Vérifier
ensuite `https://dapp9714.myvolleyball.org` : la connexion appelle `https://dapi1457.myvolleyball.org/api` (adresse fixée à la
compilation : `apps/web/.env.dev`, `apps/web/.env.prod`).

## 6. Au quotidien

- **Livrer en dev** : fusionner une pull request dans `develop`. **En prod** : pull request `develop` → `main`, puis valider
  le déploiement dans l'onglet Actions (environnement `prod`).
- **À la main** (SSH bloqué depuis GitHub, ou urgence) : depuis ta machine, `cd app && composer install --no-dev
  --optimize-autoloader --no-scripts`, puis `DEPLOY_HOST=… DEPLOY_USER=… DEPLOY_PATH=… PHP_BIN=… SSH_IDENTITY=~/.ssh/myvb_deploy
  scripts/deploy/deploy.sh`. **Remettre ensuite les dépendances de dev** : `composer install`.
- **Revenir en arrière** : `ssh … 'cd /home/<compte>/papi1457 && ls releases && ln -sfn releases/<ancienne> current'`. Les migrations ne
  se défont pas seules : une release qui change le schéma se corrige en avant (nouvelle migration).
- **Journaux** : `…/shared/log/prod-AAAA-MM-JJ.log` (API), cPanel > Erreurs (Apache).

## 7. Si ça ne marche pas

| Symptôme | Cause probable |
|---|---|
| `Permission denied (publickey)` | clé importée mais pas **Authorize**, ou clé privée mal copiée dans le secret |
| `Host key verification failed` | `SSH_KNOWN_HOSTS` absent ou d'un autre serveur |
| Connexion refusée / délai dépassé | restriction d'IP SSH (§0.3) |
| `app:deploy:check` en erreur | message précis dans le journal : base par défaut, `CORS_ALLOW_ORIGIN`, `FRONTEND_URL` en http… ; la bascule n'a pas eu lieu, rien n'est cassé |
| 401 « JWT Token not found » | le `.htaccess` d'API n'a pas été lu (`AllowOverride`) : voir `scripts/deploy/api.htaccess` |
| 500 sur toute l'API | version de PHP du sous-domaine ≠ 8.4 (MultiPHP Manager), ou `DATABASE_URL` fausse |
| La page web se recharge en 404 | `.htaccess` du web absent de `current/` |
| Photos du fil cassées sur le web | web compilé sans `VITE_API_BASE_URL` (voir `apps/web/.env.*`) |
