Come installare Zammad su Debian 12 passo dopo passo

Installare Zammad su Debian 12: scelta dello stack e prerequisiti

Zammad su Debian 12 si installa in modo più pulito usando il pacchetto ufficiale e la sua dipendenza su Elasticsearch/OpenSearch, Ruby, PostgreSQL e un web server reverse proxy. Se l’obiettivo è mettere in produzione un helpdesk stabile, la priorità non è “far partire l’interfaccia”, ma verificare prima risorse, repository, servizio di ricerca e collegamento al database.

Prima di iniziare, considera il dimensionamento minimo realistico: per un’istanza piccola servono almeno 4 GB di RAM, meglio 8 GB se il nodo ospita anche altri servizi. Lo storage deve avere spazio libero sufficiente per database, allegati e indici di ricerca. Su Debian 12, la base operativa è systemd e un’installazione pulita senza residui di Elasticsearch precedenti.

Assunzione operativa: server Debian 12 aggiornato, accesso root o sudo, DNS già risolto per il nome pubblico del servizio, e possibilità di aprire HTTP/HTTPS verso l’istanza.

Verifiche iniziali sul sistema

Controlla subito versione, memoria, spazio disco e stato della rete. Questi punti evitano installazioni interrotte a metà o un servizio che parte ma resta instabile.

cat /etc/debian_version
free -h
df -h
ip a

Se il disco è quasi pieno, fermati e libera spazio prima di procedere. Se la RAM è sotto il minimo, Zammad e il motore di ricerca possono andare in OOM o degradare molto in fase di indicizzazione.

Conviene anche aggiornare il sistema prima dell’installazione:

apt update
apt -y upgrade

Se il kernel o librerie di base vengono aggiornati, prevedi un riavvio controllato prima del setup applicativo.

Aggiungere il repository Zammad su Debian 12

Il metodo corretto è usare il repository ufficiale del progetto, così ricevi pacchetti coerenti e aggiornamenti gestibili. Prima installa i prerequisiti per il repository HTTPS e la firma dei pacchetti.

apt install -y curl gnupg apt-transport-https ca-certificates

Importa la chiave e configura il repository. I dettagli esatti possono cambiare nel tempo, quindi verifica sempre la pagina ufficiale del repository Zammad per l’URL corrente. Se il repository dovesse cambiare, il sintomo tipico è un errore 404 o firma non valida durante apt update.

curl -fsSL https://packages.zammad.org/key.asc | gpg --dearmor -o /usr/share/keyrings/zammad.gpg
echo "deb [signed-by=/usr/share/keyrings/zammad.gpg] https://packages.zammad.org/stable/debian/12/ /" > /etc/apt/sources.list.d/zammad.list
apt update

Se apt update fallisce, la verifica minima è:

• risoluzione DNS del repository con getent hosts packages.zammad.org
• connettività HTTPS con curl -I https://packages.zammad.org
• presenza della chiave in /usr/share/keyrings/zammad.gpg

Installare Zammad e le dipendenze principali

Installa il pacchetto Zammad dal repository appena configurato. Il pacchetto si porta dietro i componenti necessari o li collega al database e al motore di ricerca già presenti nel sistema, a seconda della modalità scelta dal maintainer del pacchetto.

apt install -y zammad

Durante l’installazione, il sistema può chiedere conferme o predisporre servizi. Al termine, verifica che i servizi principali siano stati creati e che non ci siano errori evidenti nel log di installazione:

systemctl status zammad
journalctl -u zammad -n 50 --no-pager

Se il servizio non parte, le cause più probabili sono: motore di ricerca non raggiungibile, database non configurato, o risorse insufficienti. In questo caso non forzare subito riavvii ripetuti: prima identifica il layer bloccante.

Configurare PostgreSQL per Zammad

Zammad usa PostgreSQL come database applicativo. Su Debian 12 puoi usare il PostgreSQL del sistema o quello incluso nei pacchetti supportati dal progetto, ma la scelta va mantenuta coerente con la documentazione della versione installata. Se il pacchetto non ha già creato il database, devi predisporlo manualmente.

Verifica innanzitutto che PostgreSQL sia attivo:

systemctl status postgresql

Se il servizio è inattivo, correggi prima quello. Poi accedi a PostgreSQL e crea utente e database dedicati, usando password robuste e non riutilizzate altrove.

sudo -u postgres psql

Dentro la console SQL:

CREATE USER zammad WITH PASSWORD 'PASSWORD_FORTE';
CREATE DATABASE zammad OWNER zammad ENCODING 'UTF8';
\q

Non lasciare password in chiaro nei file di configurazione più del necessario. Se devi inserirla in un file, proteggi permessi e ownership. Dopo la creazione, puoi testare il login:

psql -h 127.0.0.1 -U zammad -d zammad -W

Se il test fallisce, controlla autenticazione, socket o listen address di PostgreSQL. L’errore più utile è nel log di PostgreSQL, tipicamente sotto /var/log/postgresql/ o nel journal di systemd.

Configurare il motore di ricerca

La ricerca è fondamentale per Zammad: ticket, allegati indicizzati e velocità generale dipendono da questo livello. Sulle installazioni recenti, il progetto si appoggia a Elasticsearch o a una variante compatibile supportata. Qui il punto non è il nome del pacchetto, ma avere un motore di ricerca avviato, raggiungibile e con memoria adeguata.

Verifica il servizio disponibile:

systemctl status elasticsearch

Oppure, se la tua installazione usa un componente diverso supportato dalla release, controlla il servizio corrispondente. Il criterio operativo è lo stesso: deve rispondere su localhost e non andare in crash per pressione di memoria.

Un controllo rapido dell’API locale, se esposta:

curl -s http://127.0.0.1:9200/

Atteso: risposta JSON con nome, versione e stato del nodo. Se non risponde, verifica prima RAM e log del servizio. Un errore tipico è il blocco per vm.max_map_count insufficiente o heap troppo alta rispetto alla memoria disponibile.

Su Debian 12, un prerequisito frequente è:

sysctl vm.max_map_count

Se il valore è troppo basso, va portato al livello richiesto dal motore di ricerca, poi reso persistente in /etc/sysctl.d/. Cambia solo se il pacchetto e la documentazione della tua versione lo richiedono.

Avviare e inizializzare Zammad

Dopo database e motore di ricerca, inizializza l’applicazione. In molte installazioni Zammad espone comandi di setup per creare schema e dati iniziali. La procedura corretta dipende dalla versione del pacchetto, quindi il riferimento pratico è la documentazione installata o la help del comando.

Controlla i comandi disponibili:

zammad run rake -T | head

Se il pacchetto espone un setup interattivo, usalo. In alternativa, l’inizializzazione può passare da rake task dedicati per database e indice. Il principio è non saltare il passaggio di bootstrap, altrimenti l’interfaccia web si apre ma l’app non è pronta a servire ticket e utenti.

Una volta completata l’inizializzazione, verifica i servizi:

systemctl status zammad
ss -ltnp | grep -E '(:80|:443|:3000|:3001|:3002|:3003)'

Il dettaglio delle porte dipende dal reverse proxy e dai componenti interni. Se il servizio è in ascolto solo su localhost, è normale; l’esposizione pubblica deve avvenire tramite Nginx o Apache.

Configurare Nginx come reverse proxy

La soluzione più comune è Nginx davanti a Zammad. In questo schema Nginx termina TLS e inoltra le richieste al backend. È la scelta più semplice da mantenere e riduce errori di esposizione diretta dell’applicazione.

Installa Nginx se non è già presente:

apt install -y nginx

Poi crea o attiva il vhost secondo la configurazione fornita dalla documentazione del pacchetto Zammad. Se il pacchetto include snippet già pronti, usali: riduci il rischio di errori su header, websocket e upload.

Verifica la sintassi prima del reload:

nginx -t

Se il test è OK, ricarica:

systemctl reload nginx

Controlla che il sito risponda in HTTP e poi in HTTPS. Se usi Certbot o certificati manuali, l’ordine corretto è: DNS puntato, vhost attivo, certificato valido, redirect HTTP→HTTPS, solo dopo eventuale hardening aggiuntivo.

Abilitare HTTPS con Let’s Encrypt

Per un’installazione esposta su Internet, HTTPS non è opzionale. La via più semplice è usare Let’s Encrypt con Certbot, sempre che il nome DNS punti già al server e la porta 80 sia raggiungibile dall’esterno per la validazione.

apt install -y certbot python3-certbot-nginx

Richiedi il certificato per il nome del servizio:

certbot --nginx -d helpdesk.example.com

Atteso: certificato emesso, vhost aggiornato, redirect configurato. Se la challenge fallisce, verifica firewall, DNS e presenza di un altro servizio già in ascolto su 80. Per il rinnovo automatico, controlla il timer:

systemctl status certbot.timer

Il controllo finale è semplice: apri il sito e verifica che il browser mostri certificato valido e catena corretta. Se usi proxy/CDN davanti, controlla anche che il certificato origin sia coerente con la modalità di terminazione TLS scelta.

Primo accesso e configurazione iniziale dell’applicazione

Apri l’URL pubblico di Zammad e completa il wizard iniziale. In genere si impostano: account amministratore, nome dell’istanza, lingua, fuso orario, eventuali canali email e branding base.

Le verifiche minime da fare subito dopo il primo accesso sono:

• login admin riuscito
• creazione ticket test
• invio notifica email in uscita
• ricezione email in ingresso, se il canale è già configurato

Se la UI si carica ma i ticket non vengono creati o la ricerca non restituisce risultati, il problema è quasi sempre nel layer database o nel motore di ricerca, non nel web server.

Configurare email in ingresso e in uscita

Per un helpdesk reale, la parte mail è centrale. Devi configurare SMTP in uscita e almeno un canale in ingresso, tipicamente IMAP o fetch da mailbox dedicata. Usa un indirizzo tecnico dedicato, non una casella personale.

Prima verifica connettività verso il relay SMTP:

nc -vz smtp.example.com 587

Poi testa l’autenticazione e la consegna da interfaccia Zammad o dai relativi task di configurazione. Se il provider richiede TLS opportunistico o TLS obbligatorio, allinea i parametri esattamente con il suo profilo.

Per il canale in ingresso, controlla che l’account abbia permessi di lettura e, se necessario, di spostamento dei messaggi elaborati. Il sintomo tipico di un errore qui è che i messaggi arrivano alla mailbox ma non diventano ticket.

Hardening minimo e manutenzione

Una volta funzionante, applica le misure base: accesso amministrativo limitato, backup regolari, aggiornamenti pianificati, log monitorati e spazio disco controllato. Zammad produce dati applicativi e indici che crescono con gli allegati e con la cronologia dei ticket.

Controlli minimi da schedulare:

• df -h per evitare saturazione disco
• journalctl -u zammad -p warning..alert per errori applicativi
• stato PostgreSQL e del motore di ricerca
• backup di database e directory dati secondo la tua policy

Se esponi l’istanza su Internet, valuta anche rate limiting sul proxy, protezione login, MFA se disponibile e restrizione degli indirizzi amministrativi. Non esporre direttamente i servizi interni del motore di ricerca o del database.

Verifica finale della installazione

A installazione conclusa, la sequenza di verifica utile è questa:

systemctl is-active zammad nginx postgresql
curl -I https://helpdesk.example.com
journalctl -u zammad -n 100 --no-pager

Atteso: servizi attivi, risposta HTTP 200 o redirect corretto, nessun errore ripetuto nel journal. Se compare una pagina bianca, un 502 o un timeout, isola il layer: DNS, reverse proxy, app, database o ricerca.

Se tutto è stabile, documenta almeno: versione Zammad installata, configurazione DB, percorso del reverse proxy, certificato TLS, endpoint di backup e credenziali amministrative custodite nel vault. Questo riduce molto il tempo di recupero in caso di incidente futuro.

Assunzione: procedura eseguita su Debian 12 pulito, con accesso sudo, DNS già configurato e stack Zammad installato da repository ufficiale; se il repository o la versione cambiano, va riallineato il comando di installazione al changelog ufficiale.