112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# Mail Integration — Configuration cron OS
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
## 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
|
|
```
|
|
|
|
## Variables d'environnement nécessaires
|
|
|
|
| Variable | Description | Exemple |
|
|
|---|---|---|
|
|
| `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.
|
|
|
|
## 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`)
|
|
|
|
## Commandes utiles
|
|
|
|
```bash
|
|
# Sync complète (toutes les boîtes)
|
|
make mail-sync
|
|
|
|
# Sync d'un seul dossier (le dossier doit déjà exister en base)
|
|
make mail-sync FOLDER=INBOX
|
|
|
|
# Simulation (dry-run, pas d'écriture BDD)
|
|
make mail-sync DRYRUN=1
|
|
|
|
# Directement dans le container
|
|
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 :
|
|
|
|
```bash
|
|
make logs-dev
|
|
```
|
|
|
|
Les messages loggés par `MailSyncService` sont préfixés `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).
|