Documentation

Installation

Cette page vous mène du fichier téléchargé au service en fonction. Ensuite, continuez avec Premiers pas.

Prévoyez une demi-heure, si la base de données et les DNS sont déjà en place.

Avant de commencer

La base de données doit tourner avant que le service ne démarre. Le script d'installation ne la crée pas volontairement — il ne sait pas si vous exploitez votre propre instance, et il ne touche pas à vos données.

1. Vérifier le paquet

Chaque paquet dispose d'une somme de contrôle sur la page de téléchargement. Recalculez-la avant de décompresser quoi que ce soit :

shasum -a 256 annexgroup-<version>-<plateforme>.tar.gz

Si elle ne correspond pas à celle indiquée, interrompez et téléchargez à nouveau. Puis décompressez :

tar xzf annexgroup-<version>-<plateforme>.tar.gz
cd annexgroup-<version>-<plateforme>

Le paquet contient : le programme sous forme d'un seul fichier, un exemple de configuration, la définition du service et un script qui fait les deux — installer et, avec --uninstall, désinstaller.

2. Installer

Linux :

sudo ./install-linux.sh

macOS :

sudo ./install-macos.sh

macOS 14 ou plus récent est requis. Sur un système plus ancien, l’installateur s’arrête avant d’écrire quoi que ce soit et en nomme la cause : « AnnexGroup nécessite macOS 14 ou plus récent ; ce Mac a macOS … ». L’installation est vérifiée sur Apple Silicon ; le paquet Intel est compilé, notarisé et a fonctionné sous Rosetta, mais n’a pas encore été mesuré sur un Mac Intel avec macOS 14.

Le script crée l'utilisateur de service, les répertoires et le service système et ne démarre volontairement pas encore le service. Il se termine par les étapes qui suivent maintenant — les mêmes que celles-ci.

Où il écrit :

Une config.yaml déjà présente n'est pas écrasée.

3. Créer la base de données

mariadb -e "CREATE DATABASE annexgroup CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mariadb -e "CREATE USER 'annexgroup'@'localhost' IDENTIFIED BY '<mot de passe>';"
mariadb -e "GRANT ALL ON annexgroup.* TO 'annexgroup'@'localhost';"

utf8mb4 n'est pas une recommandation, mais une condition : sans lui, les accents, les emoji et de nombreux noms de pièces jointes échouent.

4. Adapter la configuration

Dans la config.yaml, deux indications sont nécessaires, tout le reste a des valeurs par défaut utilisables :

domain: votre-domaine.fr
database_dsn: "annexgroup:<mot de passe>@tcp(127.0.0.1:3306)/annexgroup?parseTime=true&loc=UTC"

Derrière un proxy (nginx et similaires) : inscrivez-le sous trusted_proxies, sinon le blocage de connexion, la liste noire et la journalisation tiennent toujours les requêtes pour venant de lui :

trusted_proxies:
  - 192.168.1.5      # l'adresse du nginx qui transmet à ce serveur
  - 10.0.0.0/24      # ou un réseau duquel ne viennent que des proxies

5. Démarrer le service

Linux :

sudo systemctl enable --now annexgroup
systemctl status annexgroup

macOS :

sudo launchctl bootstrap system /Library/LaunchDaemons/biz.ma-kom.annexgroup.plist

6. Les ports — sous macOS, le point où cela bloque

Sous Linux, le service écoute sur les ports habituels : 25, 143, 993, 443 et 587.

Pas sous macOS. Le service tourne sous _annexgroup et n'a donc pas le droit d'occuper de ports inférieurs à 1024. Il écoute sur des ports élevés, et le routeur mappe les ports publics dessus :

Sans cette correspondance, aucun courrier extérieur ne vous atteint — le serveur lui-même tourne quand même et ne signale aucune erreur. C'est la cause la plus fréquente du « tout est vert, mais rien n'arrive ».

6a. Le certificat — sinon deux ports ne démarrent pas

Entre « démarrer le service » et l'assistant se trouve un point que le serveur ne résout pas tout seul. Les ports à TLS immédiat — 465 (soumission) et 993 (IMAP) — ne démarrent pas sans certificat. Un port que les logiciels de courrier tiennent pour chiffré ne doit pas l'être seulement parfois.

Trois voies, et il n'en faut qu'une :

Avec un certificat auto-signé, chaque logiciel de courriel avertit, et la configuration avec la seule adresse ne fonctionne pas : les voies d'information autoconfig. et autodiscover. doivent figurer dans le même certificat, sinon le logiciel interrompt la connexion avant de lire les indications.

7. Ouvrir l'assistant de configuration

https://<votre-hôte>/setup          (Linux)
https://<votre-hôte>:8443/setup     (macOS)

Vous y créez le premier domaine, le premier administrateur et un mot de passe root distinct. Les 14 premiers jours s'écoulent avec toutes les fonctions, sans licence.

La suite — entrées DNS, délivrabilité, la configuration avec la seule adresse — figure dans Premiers pas.

Si quelque chose ne tourne pas

Les journaux se trouvent sous /var/log/annexgroup (Linux) respectivement /usr/local/var/log/annexgroup (macOS).

Désinstallation

sudo ./install-linux.sh --uninstall     # ou install-macos.sh

Seuls le programme et le service sont supprimés. La configuration, les données, les journaux, la base de données et l'utilisateur de service restent volontairement en place — un script de désinstallation qui supprime des boîtes courriel est une erreur, pas une fonctionnalité.