# Recherche — Setup local (Colima + Docker) & besoin d'un tunnel

> Contexte : tester le POC **en local** (Zammad sur Colima + Docker, macOS Apple Silicon),
> mailboxes hébergées **à distance sur o2switch**, sur un domaine libre.
> Question centrale : **faut-il un tunnel ?**

## Réponse courte : NON, pas de tunnel pour le POC local

Parce que Zammad **récupère les emails en sortant** (polling IMAP), il n'a besoin d'aucune
connexion entrante. Tout le trafic part **de Zammad vers o2switch**.

| Flux | Sens | Tunnel requis ? |
|---|---|---|
| Réception emails (IMAP `:993` SSL) | Zammad **→** o2switch (outbound) | ❌ non |
| Envoi emails (SMTP `:465` SSL) | Zammad **→** o2switch (outbound) | ❌ non |
| Accès UI Zammad (toi, en local) | navigateur → `localhost:8080` | ❌ non |
| Futur hook IA (webhook Zammad → service) | Zammad **→** `host.docker.internal` (service local) | ❌ non |

**Un tunnel (`scenarios/add-cloudflare-tunnel.yml`) ne devient utile que si** : tu veux
exposer l'UI Zammad sur Internet (agents distants), ou pour la prod. Pas pour tester en local.

## Comment Zammad reçoit les mails (le point clé)

- Inbound = **IMAP ou POP3 en polling** ; Zammad se connecte au serveur de mail et va
  chercher les messages (IMAP recommandé : choix du dossier, messages conservés).
- Outbound = **SMTP** (ou MTA local) ; chaque groupe Zammad décide de l'adresse d'envoi.
- À la config du canal, Zammad envoie un **email de test** et attend qu'il arrive dans le
  dossier → il faut donc IMAP (in) **et** SMTP (out) fonctionnels (les deux sont outbound).

→ Conséquence : les mailboxes restent **sur o2switch**, Zammad les **interroge**. Le domaine
libre sert uniquement aux **adresses email** (MX → o2switch), il ne pointe **pas** vers le
Zammad local.

## Réglages o2switch (à mettre dans Zammad → Channels → Email)

- **IMAP entrant** : serveur `xxxx.o2switch.net`, port **993**, SSL/TLS.
- **SMTP sortant** : serveur `xxxx.o2switch.net`, port **465**, SSL/TLS (alt. 587).
- Utilisateur = l'adresse email complète ; mot de passe = celui de la boîte.
- Le nom exact du serveur (`xxxx.o2switch.net`) est dans le mail de bienvenue o2switch / cPanel.
- SPF/DKIM du domaine sont gérés par o2switch (envoi via la boîte → From = adresse o2switch).

## Stack locale — état & recommandations (Apple Silicon, 24 Go RAM)

- ✅ **Images arm64 natives** : `ghcr.io/zammad/zammad:latest` est multi-arch (amd64 + arm64),
  Elasticsearch `9.4.2` aussi. Pas d'émulation Rosetta.
- ✅ **Colima** installé et lancé (0.10.3), `host.docker.internal` résout (192.168.5.2) →
  bon pour un éventuel futur service IA externe (porte de sortie ADR 0003 — cf. ADR 0002).
- ⚠️ **RAM Colima** : actuellement **6 GiB**. Minimum Zammad = 4 Go mais **Elasticsearch est
  gourmand**. Recommandé pour confort POC : **8 GiB** (l'hôte a 24 Go) :
  ```bash
  colima stop && colima start --cpu 4 --memory 8 --disk 60
  ```
  Option pour borner ES sans pousser la RAM : `ELASTICSEARCH_JAVA_OPTS=-Xms1g -Xmx1g` dans `.env`.
- **`ZAMMAD_FQDN`** = `localhost` pour le local (UI sur `http://localhost:8080`).

## Bring-up local (résumé)

```bash
# 0. (option) plus de RAM pour la VM
colima stop && colima start --cpu 4 --memory 8 --disk 60

# 1. config
cd infra/zammad
cp .env.dist .env          # ZAMMAD_FQDN=localhost ; (option) ELASTICSEARCH_JAVA_OPTS=-Xms1g -Xmx1g

# 2. démarrage
docker compose up -d
docker compose ps          # attendre que zammad-init soit terminé / services healthy

# 3. UI → http://localhost:8080  → créer l'admin
# 4. Channels → Email → ajouter la boîte o2switch (IMAP 993 SSL / SMTP 465 SSL)
# 5. Vérifier l'arrivée du mail de test, puis tester le routage (triggers)
```

## Seed des comptes Email via la console Rails (CLI)

Console Rails dans le conteneur : `docker compose exec -u zammad zammad-railsserver bin/rails r "<code>"`.

Script idempotent : `config/routing/seed_email_channels.rb` (crée/màj 1 compte par boîte,
relie au groupe, configure l'adresse d'envoi, teste l'IMAP). **Aucun mot de passe dans le
fichier** : lus depuis l'ENV (`MAILPW` partagé, ou `PW_QUOTE`/`PW_SALES`/… par boîte).

À lancer dans **ton terminal** (fish) — `read -s` exige un terminal interactif :

```fish
cd ~/Github/Advmfr-Email/infra/zammad
read -s -P "Mot de passe boîtes vivacoda: " MAILPW
set -gx MAILPW $MAILPW
docker compose cp ../../config/routing/seed_email_channels.rb zammad-railsserver:/tmp/seed.rb
docker compose exec -e MAILPW -u zammad zammad-railsserver bin/rails r /tmp/seed.rb
set -e MAILPW   # efface la variable
```

⚠️ Mots de passe à symboles (`$ ^ ! [`…) : ne les saisir QU'au prompt `read` (fish n'y
parse rien). Ne jamais les mettre directement sur une ligne de commande / `set VAR <pw>`.

Mots de passe différents par boîte : remplacer la ligne `read` par autant de `read -s -P "..." PW_QUOTE`
(etc.) et ajouter les `-e PW_QUOTE -e PW_SALES …` à la commande `docker compose exec`.

Gabarit de connexion (prouvé fonctionnel, auto-détecté par l'UI) : IMAP `vivacoda.com:993` ssl ;
SMTP `vivacoda.com:465` start_tls+ssl, domain `vivacoda.com`.

> Note : le canal **Email Notification** système utilise `bastien@vivacoda.com` (`mail.vivacoda.com`).
> Si ce mot de passe est aussi changé, le mettre à jour dans Channels › Email › Settings.

## Ce qui reste hors-scope de cette note

- Mécanisme du hook Claude → tranché : `docs/adr/0002-hook-claude.md`.
- Critères de routage exacts (adresse, mots-clés, langue) → à définir avec les triggers Zammad.