folio/consignes.md

# Consignes — Folio

## Architecture

**Folio** est un moteur de blog PHP.

### Dépôts et rôles

| Répertoire local | Rôle | Remote Gitea |
|-----------------|------|-------------|
| `~/Projects/folio/` | Copie du moteur Folio, branche `dev`. **Tout le développement se fait ici.** | `git.abonnel.fr/cedricAbonnel/folio` |
| `~/Projects/varlog/` | Workspace du site varlog (scripts, config). | — |
| `~/Projects/varlog-data/` | Articles de varlog.a5l.fr. Sync bidirectionnelle. | `cedricAbonnel/varlog` |
| `~/Projects/fr.abonnel.www/` | Workspace du site abonnel.fr (scripts, config). | — |
| `~/Projects/fr.abonnel.www-data/` | Articles de www.abonnel.fr. Sync bidirectionnelle. | `cedricAbonnel/abonnel-www` |

### Environnements

| Site | Rôle | Mise à jour moteur | Articles |
|------|------|--------------------|---------|
| varlog.a5l.fr | Test | rsync depuis `~/Projects/folio/` | `varlog-data/` ↔ `varlog:/srv/data/folio` |
| www.abonnel.fr | Production | Auto (UpdateChecker vérifie `version.txt` sur Gitea) | `fr.abonnel.www-data/` ↔ `abonnel-wiki:/srv/data/folio` |

### Articles (`DATA_PATH`)

Les articles ne sont **jamais** dans le dépôt folio. Ils vivent dans un répertoire séparé, configurable via `DATA_PATH` dans le `.env` de chaque instance.

- Serveur varlog : `DATA_PATH=/srv/data/folio`
- Serveur abonnel.fr : `DATA_PATH=/srv/data/folio`
- En local pour tester : pointer `DATA_PATH` vers `~/Projects/varlog-data/`

La sync des articles se fait via git (pas rsync) avec les scripts `pull-data.sh` et `push-data.sh`.

---

## Workflow moteur

1. Travailler sur `dev` dans `~/Projects/folio/`
2. Tester sur varlog.a5l.fr :
   ```bash
   ~/Projects/varlog/scripts/sync.sh
   # puis vérifier sur http://varlog.acegrp.lan (ou varlog.a5l.fr)
   ```
3. Quand `dev` est stable :
   - Bumper `public/version.txt` (semver)
   - Ajouter une entrée dans `CHANGELOG.md`
   - Ouvrir une **PR `dev` → `main`** sur Gitea
4. Merger la PR → abonnel.fr se met à jour automatiquement.

**Règle absolue : jamais de commit direct sur `main`.**

---

## Mise à jour du moteur (varlog)

Le poste local n'a pas de base de données. Tout ce qui touche à la DB ou au contenu s'exécute **sur le serveur varlog** via SSH — les scripts locaux ne font qu'ouvrir une connexion SSH et lancer le PHP distant.

**Cycle de développement :**
1. Modifier le code dans `~/Projects/folio/` (local)
2. Déployer et tester :

```bash
# Rsync moteur (folio → varlog) + sync articles bidirectionnel
~/Projects/varlog/scripts/sync.sh
# puis tester sur http://varlog.acegrp.lan
```

3. Si des migrations de schéma BDD sont nécessaires :
```bash
~/Projects/varlog/scripts/db-migrate.sh      # exécute le PHP sur varlog via SSH
```

4. Si des migrations de contenu sont nécessaires :
```bash
~/Projects/varlog/scripts/content-migrate.sh # exécute le PHP sur varlog via SSH
```

**Déploiement complet en une commande (lint + rsync + DB + contenu + commit serveur) :**
```bash
~/Projects/varlog/scripts/deploy.sh "message de commit"
```

Chemin serveur : `varlog:/var/www/lan.acegrp.varlog/`

---

## Mise à jour manuelle du moteur (abonnel.fr)

À utiliser uniquement si l'UpdateChecker échoue :

```bash
# Sauvegarde du .env
cp /var/www/lan.acegrp.abonnel-www/.env /tmp/.env.bak

# Clone fresh (en root car /var/www appartient à root)
sudo rm -rf /var/www/lan.acegrp.abonnel-www
sudo git clone --depth=1 https://git.abonnel.fr/cedricAbonnel/folio.git /var/www/lan.acegrp.abonnel-www

# Permissions : www-data propriétaire (PHP-FPM tourne en www-data)
sudo chown -R www-data:www-data /var/www/lan.acegrp.abonnel-www
sudo chmod -R g+rwX,o= /var/www/lan.acegrp.abonnel-www

# Restauration du .env
sudo cp /tmp/.env.bak /var/www/lan.acegrp.abonnel-www/.env
sudo chown www-data:www-data /var/www/lan.acegrp.abonnel-www/.env

# Dépendances et migrations (en tant que www-data car le répertoire lui appartient)
cd /var/www/lan.acegrp.abonnel-www
sudo -u www-data composer install --no-dev --optimize-autoloader
sudo -u www-data php database/migrate.php

# Répertoire de sessions
sudo mkdir -p /var/www/lan.acegrp.abonnel-www/.sessions
sudo chown www-data:www-data /var/www/lan.acegrp.abonnel-www/.sessions
sudo chmod 700 /var/www/lan.acegrp.abonnel-www/.sessions

# Autoriser git à opérer sur ce dépôt (multi-utilisateurs)
sudo git config --system --add safe.directory /var/www/lan.acegrp.abonnel-www
```





---

## Règles à respecter

- Ne **jamais** écraser le `.env` serveur (ni scp, ni réécriture). Indiquer les variables à l'utilisateur pour qu'il les saisisse lui-même.
- Ne **jamais** versionner `data/`, `.env`, ou `vendor/` dans le dépôt folio.
- Toujours bumper la version **et** mettre à jour le changelog dans le même commit que la PR.
- Dans les pools PHP-FPM, toujours utiliser `user = www-data` / `group = www-data`. `cedrix` est un admin ordinaire, pas un compte de service.
- **CSP** : le header `Content-Security-Policy` est défini dans la config Apache (`varlog/server/apache/lan.acegrp.varlog.conf`), pas dans PHP. La directive `script-src 'self'` interdit les scripts inline — ne jamais écrire de `<script>` inline dans les templates ; toujours utiliser des fichiers `.js` externes dans `public/assets/js/`. Les erreurs CSP mentionnant `content.js` viennent d'extensions navigateur bloquées par le CSP (comportement normal, pas un bug Folio). Concernant les formulaires HTML : les `<form>` imbriqués sont invalides — un bouton submit dans un form imbriqué soumet le form parent. Utiliser l'attribut HTML5 `form="id-du-form"` pour associer un bouton à un form situé hors du form englobant.