Documentazione

Installazione

Questa pagina accompagna dal file scaricato al servizio in funzione. Poi si continua con Primi passi.

Calcoli circa mezz’ora, se database e DNS sono già pronti.

Prima di iniziare

Il database deve essere attivo prima che il servizio parta. Lo script di installazione non lo crea di proposito — non sa se Lei gestisce un’istanza propria, e non si azzarda a toccare i Suoi dati.

1. Controllare il pacchetto

Per ogni pacchetto, sulla pagina di download è indicato un checksum. Lo ricalcoli, prima di estrarre qualsiasi cosa:

shasum -a 256 annexgroup-<versione>-<piattaforma>.tar.gz

Se non coincide con quello indicato, interrompa e scarichi di nuovo. Poi estragga:

tar xzf annexgroup-<versione>-<piattaforma>.tar.gz
cd annexgroup-<versione>-<piattaforma>

Nel pacchetto ci sono: il programma come un unico file, una configurazione di esempio, la definizione del servizio e uno script che sa fare entrambe le cose — installare e, con --uninstall, rimuovere di nuovo.

2. Installare

Linux:

sudo ./install-linux.sh

macOS:

sudo ./install-macos.sh

È richiesto macOS 14 o più recente. Su un sistema più vecchio, il programma di installazione si ferma prima di scrivere qualsiasi cosa e ne indica la causa: «AnnexGroup richiede macOS 14 o più recente; questo Mac ha macOS …». L’installazione è verificata su Apple Silicon; il pacchetto Intel è compilato, notarizzato e ha funzionato sotto Rosetta, ma non è ancora stato misurato su un Mac Intel con macOS 14.

Lo script crea l’utente del servizio, le directory e il servizio di sistema e non avvia il servizio di proposito. Si conclude con i passaggi che seguono ora — gli stessi di questa pagina.

Dove scrive:

Una config.yaml già esistente non viene sovrascritta.

3. Creare il database

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

utf8mb4 non è una raccomandazione, ma un prerequisito: senza di esso vanno in errore lettere accentate, emoji e molti nomi degli allegati.

4. Adattare la configurazione

Nella config.yaml servono due indicazioni, tutto il resto ha valori predefiniti sensati:

domain: suo-dominio.it
database_dsn: "annexgroup:<password>@tcp(127.0.0.1:3306)/annexgroup?parseTime=true&loc=UTC"

Dietro un proxy (nginx e simili): lo inserisca sotto trusted_proxies, altrimenti blocco di accesso, lista nera e log trattano sempre le richieste come provenienti da lui:

trusted_proxies:
  - 192.168.1.5      # l'indirizzo dell'nginx che inoltra a questo server
  - 10.0.0.0/24      # oppure una rete da cui provengono solo proxy

5. Avviare il servizio

Linux:

sudo systemctl enable --now annexgroup
systemctl status annexgroup

macOS:

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

6. Le porte — sotto macOS il punto in cui si inceppa

Sotto Linux il servizio ascolta sulle porte consuete: 25, 143, 993, 443 e 587.

Sotto macOS no. Il servizio gira come _annexgroup e per questo non può occupare porte sotto la 1024. Ascolta su porte alte, e il router mappa quelle pubbliche su di esse:

Senza questa mappatura non riceve posta dall’esterno — il server in sé funziona comunque e non segnala alcun errore. Questa è la causa più comune di «tutto verde, ma non arriva nulla».

6a. Il certificato — altrimenti due porte non partono

Tra «avviare il servizio» e l’assistente c’è un punto che il server non risolve da solo. Le porte con TLS immediato — 465 (invio) e 993 (IMAP) — senza certificato non partono. Una porta che i programmi di posta ritengono cifrata non può esserlo solo a volte.

Tre modi, e ne serve esattamente uno:

Con un certificato autofirmato ogni programma di posta segnala un avviso, e la configurazione con il solo indirizzo non funziona: i percorsi autoconfig. e autodiscover. devono comparire nello stesso certificato, altrimenti il programma interrompe la connessione prima di leggere le informazioni.

7. Aprire l’assistente di configurazione

https://<suo-host>/setup          (Linux)
https://<suo-host>:8443/setup     (macOS)

Lì crea il primo dominio, il primo amministratore e una password di root separata. I primi 14 giorni girano con la piena funzionalità senza licenza.

Come si prosegue — record DNS, recapitabilità, configurazione con il solo indirizzo — è descritto in Primi passi.

Se qualcosa non funziona

I log si trovano in /var/log/annexgroup (Linux) rispettivamente /usr/local/var/log/annexgroup (macOS).

Disinstallazione

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

Vengono rimossi solo il programma e il servizio. Configurazione, dati, log, il database e l’utente del servizio restano di proposito — uno script di disinstallazione che cancella le caselle di posta è un errore, non una funzione.