# Déploiement Socialex — 100% via GitHub Actions

Tout (premier setup + déploiements suivants) se fait via **GitHub Actions**.
Tu ne tapes des commandes sur le VPS que pour le tout premier accès SSH (pour
autoriser GitHub à se connecter ensuite). Après ça, tu pilotes depuis l'interface
GitHub.

> **Architecture cible**
> - Apache2 reverse proxy `socialex.pro:443` → `127.0.0.1:3001`
> - Container `socialex-app` (Next.js standalone) écoute sur 3001
> - Container `socialex-postgres` (Postgres 16) sur réseau Docker interne (non exposé)
> - Volume Docker `socialex_pgdata` (persistance DB)
> - Bind mount `/var/www/html/socialex/uploads` (documents clients)
> - SMTP : mail.nexus-games.com (config dans `.env.production`, généré par GitHub Actions)

---

## 0. Vue d'ensemble — qui fait quoi

| Étape                       | Où       | Quand          |
|-----------------------------|----------|----------------|
| Générer la clé SSH dédiée   | Local    | Une fois       |
| Autoriser la clé sur le VPS | VPS (SSH manuel) | Une fois |
| Configurer les secrets GitHub | GitHub | Une fois       |
| Lancer "Bootstrap VPS"      | GitHub Actions | Une fois |
| Push sur `main`             | Local    | À chaque modif |
| Déploiement auto            | GitHub Actions | À chaque push |

**Total côté VPS : un seul `cat >> ~/.ssh/authorized_keys` et c'est fini.**
Tout le reste se fait depuis ton poste et l'UI GitHub.

---

## 1. Préparation (une fois)

### 1.1 Génère une clé SSH dédiée à GitHub Actions

Sur **ton poste** (pas le VPS) :

```bash
ssh-keygen -t ed25519 -f ~/.ssh/socialex_deploy -C "github-actions-socialex" -N ""
```

Cela crée :
- `~/.ssh/socialex_deploy` (privée, à mettre dans GitHub Secret `VPS_SSH_KEY`)
- `~/.ssh/socialex_deploy.pub` (publique, à mettre sur le VPS)

### 1.2 Autorise la clé publique sur le VPS

```bash
# Affiche la clé publique
cat ~/.ssh/socialex_deploy.pub
```

Connecte-toi au VPS avec ton mot de passe ou ta clé personnelle :

```bash
ssh root@188.40.186.181

# Sur le VPS :
mkdir -p ~/.ssh
echo "<colle ici le contenu de socialex_deploy.pub>" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
exit
```

Vérifie depuis ton poste :

```bash
ssh -i ~/.ssh/socialex_deploy root@188.40.186.181 "echo OK"
# Doit afficher OK sans demander de mot de passe.
```

### 1.3 Génère les secrets cryptographiques

Sur **ton poste** :

```bash
# Postgres password (mémorise-le, tu vas le coller dans GitHub Secret)
openssl rand -base64 24

# Better Auth secret (mémorise-le pareil)
openssl rand -base64 32
```

### 1.4 Ajoute les secrets dans GitHub

Va sur **https://github.com/Zeikoo/socialex/settings/secrets/actions** et ajoute :

| Nom                    | Valeur                                                                 |
|------------------------|------------------------------------------------------------------------|
| `VPS_HOST`             | `188.40.186.181`                                                       |
| `VPS_USER`             | `root`                                                                 |
| `VPS_SSH_KEY`          | Contenu **complet** de `~/.ssh/socialex_deploy` (avec BEGIN/END)       |
| `POSTGRES_PASSWORD`    | Le mot de passe Postgres généré en 1.3                                |
| `BETTER_AUTH_SECRET`   | Le secret Better Auth généré en 1.3                                   |
| `SMTP_PASS`            | Le mot de passe SMTP de `contact@socialex.pro`                         |
| `SEED_ADMIN_EMAIL`     | `admin@socialex.pro` (ou autre)                                        |
| `SEED_ADMIN_PASSWORD`  | Un mot de passe fort de ton choix (à changer après 1ère connexion)    |

**Important** : les secrets sont chiffrés. GitHub ne les affiche jamais après création — note-les ailleurs si besoin.

---

## 2. Premier déploiement : workflow "Bootstrap VPS"

Sur **https://github.com/Zeikoo/socialex/actions**, dans la liste de gauche :

1. Clique sur **"Bootstrap VPS"**
2. Bouton **"Run workflow"** → sélectionne la branche `main` → **Run workflow**
3. Le workflow se lance (~5-10 min). Il va :
   - Installer git, rsync, apache2 (s'ils manquent)
   - Activer les modules Apache (proxy, ssl, headers, etc.)
   - Créer `/var/www/html/socialex` + dossier `uploads`
   - Copier le code via rsync
   - Générer `.env.production` depuis tes GitHub Secrets
   - Installer le vhost Apache `socialex.pro` + reload Apache
   - `docker compose up -d --build` (build de l'image Next + démarrage Postgres + app)
   - Appliquer les migrations Drizzle
   - Seed l'utilisateur admin
   - Seed les templates de formulaires

À la fin :

- **https://socialex.pro** affiche la vitrine ✅
- **https://socialex.pro/login** te connecte avec `SEED_ADMIN_EMAIL` / `SEED_ADMIN_PASSWORD`
- **https://socialex.pro/socialexadmin** te donne accès au dashboard admin

### En cas d'échec

Logs dans GitHub Actions → cliquer sur le run échoué → ouvrir l'étape rouge.
Cas fréquents :

- **Permission denied (publickey)** : clé SSH mal configurée. Re-vérifie l'étape 1.2.
- **`POSTGRES_PASSWORD` non défini** : tu as oublié un secret en 1.4.
- **`SSL Certificate file does not exist`** : les certs Cloudflare ne sont pas dans `/etc/cloudflare/`. Vérifie sur le VPS :
  ```bash
  ls -l /etc/cloudflare/socialex.pro.{pem,key}
  ```

---

## 3. Cycle quotidien : déploiement automatique

Une fois le bootstrap réussi, **tu n'as plus rien à faire sur le VPS**.

```bash
# Sur ton poste
git add .
git commit -m "feat: ..."
git push origin main
```

Le workflow **"Deploy"** se lance automatiquement :

1. rsync du code vers le VPS (préserve `.env.production`, `uploads`, `pgdata`)
2. Rebuild de l'image Next.js
3. Migrations Drizzle (idempotentes)
4. Restart graceful du container app
5. Cleanup des images Docker obsolètes

Durée : 2-4 min. Pas d'interruption visible côté visiteur (Docker fait un graceful restart).

Tu peux suivre en direct dans **Actions → Deploy**.

### Re-déclencher manuellement un deploy

Sans push, dans Actions → **"Deploy"** → **Run workflow** → main.

### Mettre à jour un secret (ex: SMTP_PASS, BETTER_AUTH_SECRET)

1. Édite le secret dans GitHub Settings → Secrets
2. Lance manuellement **"Bootstrap VPS"** (qui réécrit `.env.production` depuis les secrets)

Le bootstrap est **idempotent** : il peut être relancé sans casser l'install.

---

## 4. Opérations courantes (SSH au VPS)

Tu n'as pas à le faire en routine, mais pour debug :

### Voir les logs de l'app

```bash
ssh root@188.40.186.181 \
  "docker compose -f /var/www/html/socialex/docker-compose.prod.yml logs -f app"
```

### Accéder à Postgres

```bash
ssh root@188.40.186.181 \
  "docker compose -f /var/www/html/socialex/docker-compose.prod.yml exec postgres psql -U socialex -d socialex"
```

### Sauvegarder la DB

```bash
ssh root@188.40.186.181 \
  "docker compose -f /var/www/html/socialex/docker-compose.prod.yml exec postgres pg_dump -U socialex socialex" \
  > backup-$(date +%F).sql
```

### Restaurer la DB

```bash
cat backup-2026-05-07.sql | ssh root@188.40.186.181 \
  "docker compose -f /var/www/html/socialex/docker-compose.prod.yml exec -T postgres psql -U socialex socialex"
```

### Backup uploads

```bash
ssh root@188.40.186.181 \
  "tar czf - /var/www/html/socialex/uploads" > uploads-$(date +%F).tar.gz
```

### Rollback rapide vers un commit précédent

Plus simple : revert le commit, push, le déploy reset automatiquement.

```bash
git revert HEAD
git push origin main
```

---

## 5. Coexistence avec les autres sites du VPS

| Élément              | Choix Socialex                       | Risque conflit             |
|----------------------|--------------------------------------|----------------------------|
| Port app             | `127.0.0.1:3001` (loopback only)     | Aucun (3000 = autre site)  |
| Postgres             | Dockerisé, port non exposé           | Aucun                      |
| MariaDB existante    | Pas touchée                          | Aucun                      |
| Redis existant       | Pas touché                           | Aucun                      |
| Apache vhost         | `socialex.pro` + `www.socialex.pro`  | Doit être unique           |
| Volume `pgdata`      | Nommé `socialex_pgdata`              | Préfixé pour éviter coll.  |
| Network Docker       | `socialex_internal`                  | Préfixé                    |
| Containers           | `socialex-app` / `socialex-postgres` | Préfixés                   |

---

## 6. Sécurité

- `.env.production` n'est jamais committé (cf. `.gitignore`).
- Le port `3001` est en `127.0.0.1` exclusif → pas accessible depuis Internet, seul Apache local peut y accéder.
- Le port Postgres n'est pas exposé du tout sur l'hôte.
- L'image Docker run en user `nextjs` (uid 1001), pas en root.
- Cloudflare en frontal protège contre DDoS et masque l'IP origin.
- Les secrets GitHub Actions sont chiffrés au repos et masqués dans les logs.

---

## 7. Phase 2 (à venir, signalées dans le code)

- **Magic link set-password** : aujourd'hui le client reçoit un email avec un lien `/login` générique. Il faut générer un token Better Auth et créer une page `/set-password?token=...`. **Bloquant pour activer le flow client complet** avant ouverture publique.
- **Cron backup** : automatiser pg_dump + tar uploads via cron sur le VPS.
- **Monitoring** : Healthcheck + alerting (UptimeRobot ou similaire).