docs : corrige le déploiement prod (Docker) et documente les variables d'env mail
- README : section Variables d'environnement (ENCRYPTION_KEY, LOCK_DSN) + section Déploiement passée au flow Docker (deploy.sh) - mail-cron-setup : sépare dev (make, php-lesstime-fpm) et prod (lesstime-app, docker compose exec), cron prod réel - infra/prod/.env.example : ajoute ENCRYPTION_KEY et LOCK_DSN (manquaient, requis pour la sync mail) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matthieu
@@ -3,44 +3,24 @@
|
||||
## Vue d'ensemble
|
||||
|
||||
La synchronisation IMAP est déclenchée par un cron OS toutes les 10 minutes.
|
||||
Elle appelle la commande Symfony `app:mail:sync` qui s'exécute dans le container PHP.
|
||||
Elle appelle la commande Symfony `app:mail:sync` qui s'exécute **dans le container PHP**.
|
||||
|
||||
Un Symfony Lock (`mail.sync`, TTL 10 min, store `flock` via `LOCK_DSN=flock`) empêche
|
||||
les runs de se chevaucher si une sync prend plus de 10 min.
|
||||
|
||||
> **Dev vs prod** — en dev le container s'appelle `php-lesstime-fpm` et on passe par `make`.
|
||||
> En **production** le container s'appelle `lesstime-app` (service `app` du `docker-compose.yml`
|
||||
> dans `/var/www/lesstime`), il n'y a **pas de `make`** : tout passe par `docker compose` / `docker exec`.
|
||||
|
||||
## Prérequis
|
||||
|
||||
- Container `php-lesstime-fpm` démarré (`make start`)
|
||||
- `MailConfiguration.enabled = true` (configurable depuis l'admin — Phase 7)
|
||||
- `ENCRYPTION_KEY` défini dans `infra/dev/.env.docker.local` (ou production env)
|
||||
|
||||
## Installation du cron
|
||||
|
||||
Sur la **machine hôte** (pas dans le container) :
|
||||
|
||||
```bash
|
||||
crontab -e
|
||||
```
|
||||
|
||||
Ajouter la ligne suivante (adapter le chemin) :
|
||||
|
||||
```cron
|
||||
*/10 * * * * cd /home/r-dev/malio-dev/Lesstime && make mail-sync >> /var/log/lesstime-mail-sync.log 2>&1
|
||||
```
|
||||
|
||||
Ou directement via `docker exec` (sans dépendance à `make`) :
|
||||
|
||||
```cron
|
||||
*/10 * * * * docker exec php-lesstime-fpm php bin/console app:mail:sync >> /var/log/lesstime-mail-sync.log 2>&1
|
||||
```
|
||||
|
||||
### Avec un utilisateur système dédié
|
||||
|
||||
Si le cron est configuré pour un utilisateur système spécifique (ex: `www-data` ou `deploy`) :
|
||||
|
||||
```bash
|
||||
sudo crontab -u deploy -e
|
||||
```
|
||||
- `MailConfiguration.enabled = true` (configurable depuis l'admin — onglet « Mail »)
|
||||
- `ENCRYPTION_KEY` (clé hex 32 bytes) défini dans l'environnement :
|
||||
- **dev** : `infra/dev/.env.docker.local`
|
||||
- **prod** : `/var/www/lesstime/.env`
|
||||
- Container démarré :
|
||||
- **dev** : `make start` (container `php-lesstime-fpm`)
|
||||
- **prod** : déployé via `sudo ./deploy.sh` (container `lesstime-app`)
|
||||
|
||||
## Variables d'environnement nécessaires
|
||||
|
||||
@@ -49,63 +29,100 @@ sudo crontab -u deploy -e
|
||||
| `ENCRYPTION_KEY` | Clé hex 32 bytes pour déchiffrer le password IMAP | `$(php -r "echo bin2hex(random_bytes(32));")` |
|
||||
| `LOCK_DSN` | DSN du store de verrous Symfony | `flock` (défaut, fichier local) |
|
||||
|
||||
La clé doit être la même que celle utilisée pour chiffrer le password lors de la configuration.
|
||||
La clé `ENCRYPTION_KEY` doit être **identique** à celle utilisée pour chiffrer le password
|
||||
lors de la configuration depuis l'admin. Si elle change, les credentials stockés deviennent illisibles.
|
||||
|
||||
## Checklist setup production
|
||||
---
|
||||
|
||||
1. [ ] Définir `ENCRYPTION_KEY` dans les variables d'environnement production
|
||||
2. [ ] Créer le compte mail dédié (ex: `lesstime@votre-domaine.fr`) chez OVH
|
||||
3. [ ] Accéder à `/admin` → onglet "Mail" → renseigner les credentials IMAP/SMTP
|
||||
4. [ ] Cliquer "Tester la connexion" → vérifier le succès
|
||||
5. [ ] Cocher "Activer la synchronisation" → Enregistrer
|
||||
6. [ ] Installer le cron OS (voir section "Installation du cron")
|
||||
7. [ ] Vérifier les logs après la première sync : `make logs-dev` (chercher `mail.sync`)
|
||||
## Dev
|
||||
|
||||
## Commandes utiles
|
||||
### Lancer une sync à la main
|
||||
|
||||
```bash
|
||||
# Sync complète (toutes les boîtes)
|
||||
make mail-sync
|
||||
make mail-sync # sync complète (toutes les boîtes)
|
||||
make mail-sync FOLDER=INBOX # un seul dossier (doit déjà exister en base)
|
||||
make mail-sync DRYRUN=1 # simulation (dry-run, pas d'écriture BDD)
|
||||
```
|
||||
|
||||
# Sync d'un seul dossier (le dossier doit déjà exister en base)
|
||||
make mail-sync FOLDER=INBOX
|
||||
Ou directement dans le container :
|
||||
|
||||
# Simulation (dry-run, pas d'écriture BDD)
|
||||
make mail-sync DRYRUN=1
|
||||
|
||||
# Directement dans le container
|
||||
```bash
|
||||
docker exec php-lesstime-fpm php bin/console app:mail:sync
|
||||
docker exec php-lesstime-fpm php bin/console app:mail:sync --folder=INBOX
|
||||
docker exec php-lesstime-fpm php bin/console app:mail:sync --dry-run
|
||||
```
|
||||
|
||||
## Logs
|
||||
|
||||
Les logs Symfony sont dans `var/log/dev.log` (ou `prod.log` en production).
|
||||
Suivre les logs en temps réel :
|
||||
### Logs (dev)
|
||||
|
||||
```bash
|
||||
make logs-dev
|
||||
make logs-dev # tail -f var/log/dev.log
|
||||
```
|
||||
|
||||
Les messages loggés par `MailSyncService` sont préfixés `mail.sync`.
|
||||
|
||||
---
|
||||
|
||||
## Production
|
||||
|
||||
En prod, l'app tourne dans le container `lesstime-app` déployé par `sudo ./deploy.sh`
|
||||
(dossier `/var/www/lesstime`). La commande s'exécute en tant que `www-data` (uid 33),
|
||||
comme les migrations lancées par `deploy.sh`.
|
||||
|
||||
### Lancer une sync à la main
|
||||
|
||||
Depuis `/var/www/lesstime` :
|
||||
|
||||
```bash
|
||||
sudo docker compose exec -T -u www-data app php bin/console app:mail:sync
|
||||
sudo docker compose exec -T -u www-data app php bin/console app:mail:sync --folder=INBOX
|
||||
sudo docker compose exec -T -u www-data app php bin/console app:mail:sync --dry-run
|
||||
```
|
||||
|
||||
### Installer le cron
|
||||
|
||||
Sur la **machine hôte** (pas dans le container). Comme `docker` requiert `sudo` en prod,
|
||||
installer le cron sous root :
|
||||
|
||||
```bash
|
||||
sudo crontab -e
|
||||
```
|
||||
|
||||
Ajouter :
|
||||
|
||||
```cron
|
||||
*/10 * * * * cd /var/www/lesstime && docker compose exec -T -u www-data app php bin/console app:mail:sync >> /var/log/lesstime-mail-sync.log 2>&1
|
||||
```
|
||||
|
||||
> Le crontab de root exécute déjà les commandes en root → pas de `sudo` à l'intérieur de la ligne cron.
|
||||
> La commande est **idempotente** (UIDs uniques en base) : la relancer ne duplique pas les données.
|
||||
|
||||
### Logs (prod)
|
||||
|
||||
```bash
|
||||
cd /var/www/lesstime
|
||||
docker compose logs -f --tail=100 app # logs container
|
||||
docker compose exec app cat var/log/prod.log # log Symfony (volume lesstime_logs)
|
||||
```
|
||||
|
||||
### Checklist setup production
|
||||
|
||||
1. [ ] Définir `ENCRYPTION_KEY` (hex 32 bytes) et `LOCK_DSN=flock` dans `/var/www/lesstime/.env`
|
||||
2. [ ] Créer le compte mail dédié (ex: `lesstime@votre-domaine.fr`) chez OVH
|
||||
3. [ ] Accéder à `/admin` → onglet « Mail » → renseigner les credentials IMAP/SMTP
|
||||
4. [ ] Cliquer « Tester la connexion » → vérifier le succès
|
||||
5. [ ] Cocher « Activer la synchronisation » → Enregistrer
|
||||
6. [ ] Lancer une sync manuelle pour valider (commande ci-dessus)
|
||||
7. [ ] Installer le cron OS (voir « Installer le cron »)
|
||||
8. [ ] Vérifier les logs après la première sync (`docker compose logs -f app`, chercher `mail.sync`)
|
||||
|
||||
---
|
||||
|
||||
## Sécurité
|
||||
|
||||
- Le password IMAP est **toujours stocké chiffré** (libsodium secretbox)
|
||||
- Les corps de mails, passwords et pièces jointes ne sont **jamais loggés**
|
||||
- Le lock `flock` évite les runs parallèles (fichier dans `/tmp/sf.mail.sync.<hash>.lock`)
|
||||
|
||||
## Rappels sécurité
|
||||
|
||||
- La page `/mail` et tous les endpoints `/api/mail/*` sont refusés aux `ROLE_CLIENT` exclusifs
|
||||
- Le sidebar "Messagerie" est masqué pour les utilisateurs ROLE_CLIENT sans ROLE_USER
|
||||
- Le password IMAP est chiffré via libsodium secretbox avant stockage (jamais en clair en base)
|
||||
- Les corps de mails sont sanitisés via DOMPurify avant affichage (voir `frontend/utils/sanitizeMailHtml.ts`)
|
||||
- Les pixels tracking distants sont remplacés par un placeholder
|
||||
- Aucun body mail, password ou contenu de pièce jointe n'est loggé
|
||||
|
||||
## Production
|
||||
|
||||
En production, préférer un cron système ou un job scheduler (Kubernetes CronJob, ECS Scheduled Task, etc.).
|
||||
La commande est idempotente : relancer plusieurs fois ne duplique pas les données (UIDs uniques en base).
|
||||
- Le sidebar « Messagerie » est masqué pour les utilisateurs `ROLE_CLIENT` sans `ROLE_USER`
|
||||
- Les corps de mails sont sanitisés via DOMPurify avant affichage (`frontend/utils/sanitizeMailHtml.ts`)
|
||||
- Les pixels de tracking distants sont remplacés par un placeholder
|
||||
|
||||
Reference in New Issue
Block a user