Come installare Zammad su Ubuntu 22.04

Installare Zammad su Ubuntu 22.04

Zammad è un helpdesk open source pensato per ticketing, email piping, knowledge base e automazioni. Su Ubuntu 22.04 l’approccio più lineare è usare i pacchetti ufficiali, così riduci il rischio di dipendenze incoerenti e hai un percorso di upgrade più pulito.

Questa guida parte da un server Ubuntu 22.04 aggiornato, con accesso root o sudo, e porta all’installazione funzionante con PostgreSQL, Redis, Elasticsearch e Nginx come reverse proxy.

Se stai facendo questa installazione in produzione, considera l’impatto su DNS, certificati TLS, posta in ingresso e risorse disco/RAM. Zammad non è solo una web app: dipende in modo stretto dal motore di ricerca e dalla coda interna, quindi conviene verificare i prerequisiti prima di procedere.

Prerequisiti e decisioni architetturali

Per un’installazione standard servono:

• Ubuntu 22.04 aggiornato
• Accesso amministrativo via sudo
• Almeno 4 GB di RAM, meglio 8 GB se prevedi più utenti o allegati consistenti
• Spazio disco sufficiente per database, log e allegati
• Un nome DNS dedicato, ad esempio helpdesk.example.com

Zammad usa Elasticsearch per la ricerca. Se la ricerca è lenta o non funziona, l’esperienza utente degrada subito. Anche Redis e PostgreSQL sono componenti critici: il primo gestisce code e cache, il secondo i dati applicativi.

Per questa guida assumiamo un’installazione monolitica sullo stesso host. È la scelta più semplice per partire. In ambienti più grandi puoi separare PostgreSQL, Redis e Elasticsearch su nodi distinti, ma lì entrano in gioco latenza di rete, tuning e hardening aggiuntivo.

Aggiornare il sistema e preparare il server

Parti sempre da un sistema pulito e aggiornato. Questo riduce la probabilità di conflitti con librerie vecchie o kernel non allineati.

sudo apt update
sudo apt -y upgrade
sudo apt -y install curl gnupg ca-certificates apt-transport-https lsb-release

Dopo l’aggiornamento, verifica la release:

lsb_release -a

Atteso: Ubuntu 22.04.x. Se non è così, fermati e riallinea il sistema prima di proseguire.

Se usi firewall locale, apri solo ciò che serve. In fase di installazione spesso bastano SSH, HTTP e HTTPS. Se l’installazione è dietro un reverse proxy, non esporre direttamente i servizi applicativi.

Installare PostgreSQL

Zammad richiede PostgreSQL come database principale. Su Ubuntu 22.04 il pacchetto della distribuzione è sufficiente nella maggior parte dei casi.

sudo apt -y install postgresql postgresql-contrib

Verifica che il servizio sia attivo:

systemctl status postgresql --no-pager

Atteso: stato active (running). Se non lo è, controlla i log con:

journalctl -u postgresql -n 50 --no-pager

Crea utente e database dedicati. Non usare il superuser postgres per l’applicazione.

sudo -u postgres psql

CREATE USER zammad WITH PASSWORD 'password_forte';
CREATE DATABASE zammad OWNER zammad ENCODING 'UTF8';

q

Usa una password robusta e non lasciarla in chiaro nei file condivisi. Se devi documentarla, redigila o archiviala in un secret manager.

Se vuoi fare un controllo rapido della connessione, prova:

psql -h localhost -U zammad -d zammad -c 'SELECT version();'

Atteso: output della versione PostgreSQL senza errori di autenticazione.

Installare Redis

Redis serve a Zammad per code, cache e componenti interni. Senza Redis il servizio può avviarsi male o degradare in modo evidente.

sudo apt -y install redis-server

Controlla che sia attivo:

systemctl status redis-server --no-pager

Atteso: active (running). Verifica anche la risposta del ping:

redis-cli ping

Atteso: PONG.

In installazioni standard non serve esporre Redis sulla rete. Lascia il binding locale e non aprire porte inutili nel firewall. Questo riduce la superficie d’attacco.

Installare Elasticsearch

La ricerca in Zammad dipende da Elasticsearch. È la parte che più spesso viene sottovalutata: se è assente o non compatibile, l’interfaccia può funzionare a metà, ma la ricerca e gli indici no.

Per Ubuntu 22.04 conviene seguire la versione supportata da Zammad nella documentazione ufficiale del rilascio che stai installando. Le versioni compatibili cambiano nel tempo, quindi non fissarti su un numero preso da vecchie guide. Se la tua release Zammad richiede una versione specifica, usa quella.

Tipicamente il flusso è:

1. importare la chiave del repository Elasticsearch
2. aggiungere il repository corretto
3. installare il pacchetto
4. impostare i parametri kernel richiesti

Un esempio generico del controllo dello stato è:

systemctl status elasticsearch --no-pager

Atteso: active (running). Se il servizio non parte, i log da guardare sono:

journalctl -u elasticsearch -n 100 --no-pager

Per Elasticsearch spesso il collo di bottiglia è la memoria virtuale e il limite vm.max_map_count. Se il servizio fallisce all’avvio, controlla questo parametro:

sysctl vm.max_map_count

Atteso: valore adeguato alla release richiesta, spesso almeno 262144. Se serve impostarlo:

echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-elasticsearch.conf
sudo sysctl --system

Questa è una modifica reversibile: rimuovi il file di configurazione e ricarica sysctl se devi tornare indietro.

Aggiungere il repository ufficiale di Zammad

Il modo più pulito è usare il repository ufficiale del progetto. In questo modo installi pacchetti integrati e mantenuti per la distribuzione supportata.

Prima di aggiungere un repository, verifica sempre la pagina ufficiale della release che stai usando. I nomi del repository e la chiave GPG possono cambiare. Se copi un comando vecchio, rischi errore di firma o pacchetto non trovato.

Il pattern corretto è:

1. importare la chiave GPG del repository
2. aggiungere la source list
3. aggiornare l’indice APT

Dopo l’aggiunta, controlla che APT veda il pacchetto:

apt-cache policy zammad

Atteso: origine del pacchetto sul repository Zammad, non solo sui repository Ubuntu standard.

Installare Zammad

A questo punto puoi installare il pacchetto principale. In genere il metapacchetto porta con sé le dipendenze necessarie o comunque prepara l’ambiente applicativo.

sudo apt update
sudo apt -y install zammad

Al termine verifica i servizi installati:

systemctl list-units --type=service | grep -i zammad

In una installazione tipica troverai componenti come web socket, scheduler, processi di background e web server integrati o app service. I nomi esatti dipendono dalla versione, quindi non fissarti sul servizio singolo: quello che conta è che l’installazione abbia registrato i suoi unit file e che non ci siano errori in avvio.

Se il pacchetto non si installa, le cause più comuni sono repository errato, dipendenze non soddisfatte o versione non compatibile con la release Ubuntu. In quel caso il primo controllo è:

apt-cache policy zammad
apt -o Debug::pkgProblemResolver=yes install zammad

Così vedi subito da dove APT sta tentando di prendere il pacchetto e dove si inceppa la risoluzione.

Configurare Zammad con l’assistente iniziale

Dopo l’installazione, apri il browser sul nome host configurato, ad esempio https://helpdesk.example.com. Se il proxy non è ancora configurato, potresti dover passare per HTTP locale o per il servizio esposto dal pacchetto, ma in produzione è preferibile arrivare subito al dominio finale.

Al primo accesso Zammad mostra normalmente la procedura iniziale di configurazione. Qui imposti:

• nome dell’istanza
• fuso orario
• account amministratore iniziale
• parametri email
• integrazioni base

Compila con attenzione il profilo amministrativo. L’errore tipico è usare una mailbox personale non presidiata o non documentata. Meglio un indirizzo funzionale, con accesso controllato e rotazione sicura delle credenziali.

Se l’interfaccia web non risponde, controlla la catena minima:

curl -I http://127.0.0.1
curl -I https://helpdesk.example.com

Atteso: una risposta HTTP valida, non timeout e non reset. Se hai un reverse proxy, controlla che il backend sia raggiungibile e che i log del proxy non riportino 502 o 504.

Configurare Nginx come reverse proxy

In molti casi il pacchetto Zammad include il necessario per servire la web app, ma un reverse proxy Nginx resta una scelta comune per TLS, redirect e gestione delle connessioni. Se lo usi, tienilo semplice.

Obiettivi minimi:

• forzare HTTPS
• passare header corretti
• mantenere il WebSocket se richiesto dalla versione
• evitare buffering aggressivo se l’app lo sconsiglia

Un controllo base della configurazione è:

nginx -t

Atteso: syntax is ok e test is successful. Poi ricarica:

sudo systemctl reload nginx

Se la pagina va in errore dopo la modifica del proxy, i punti da verificare sono i log di Nginx e il backend Zammad. Tipicamente:

journalctl -u nginx -n 50 --no-pager
journalctl -u zammad -n 50 --no-pager

Se usi certificati Let’s Encrypt, integra il rinnovo automatico e verifica che il certificato servito corrisponda al nome DNS pubblico. Un mismatch TLS si traduce in errori lato browser o in warning che gli utenti spesso interpretano come “sito non funziona”.

Configurare TLS

Per un helpdesk esposto agli utenti, TLS non è opzionale. Serve sia per la sicurezza sia per evitare problemi con cookie, login e integrazioni email/webhook.

Con Certbot il flusso classico è:

sudo apt -y install certbot python3-certbot-nginx
sudo certbot --nginx -d helpdesk.example.com

Controlla il rinnovo:

systemctl list-timers | grep certbot

Atteso: timer attivo o meccanismo equivalente. Verifica anche il certificato dal lato client:

openssl s_client -connect helpdesk.example.com:443 -servername helpdesk.example.com

Atteso: catena corretta e nome host coerente. Se il certificato è sbagliato, la causa può essere DNS, virtual host errato o proxy davanti a Nginx che termina TLS altrove.

Configurare la posta in ingresso e in uscita

Uno dei punti chiave di Zammad è la gestione della posta. Senza email il ticketing perde gran parte del suo valore.

Per l’invio, configura SMTP con un account dedicato. Per la ricezione, usa IMAP o un meccanismo di fetch supportato dal tuo provider. Se hai un dominio aziendale, cura anche SPF, DKIM e DMARC, altrimenti rischi consegna scarsa o finita in spam.

Controlli utili:

• la mailbox risponde con autenticazione corretta
• l’ora del server è sincronizzata con NTP
• i record DNS del dominio mail sono coerenti

Se le notifiche non partono, guarda i log applicativi e del mail relay. Il problema spesso non è Zammad ma il relay SMTP che rifiuta mittente, TLS o autenticazione.

Verifiche post-installazione

Dopo l’installazione fai una validazione minima, prima di dare il sistema agli utenti.

1. Apri il sito e fai login con l’account admin iniziale.
2. Crea un ticket di prova.
3. Verifica ricerca e aggiornamento stato ticket.
4. Invia una mail di test verso l’helpdesk e controlla la creazione automatica del ticket.
5. Controlla che allegati piccoli e medi vengano caricati correttamente.

Dal lato sistema, controlla i servizi e le risorse:

systemctl --failed
df -h
free -h
top

Atteso: nessun servizio fallito, disco con margine sufficiente, memoria non saturata, assenza di swap thrashing. Se il nodo è stretto di RAM, Elasticsearch è il primo candidato a soffrire.

Tuning minimo per stabilità

Su installazioni piccole puoi partire con i default, ma ci sono alcuni punti da tenere d’occhio:

• memoria per Elasticsearch
• spazio su disco per allegati e indici
• rotazione log
• backup del database

Per il backup PostgreSQL puoi usare un dump periodico. Esempio base:

sudo -u postgres pg_dump zammad | gzip > /backup/zammad-$(date +%F).sql.gz

Conserva il backup fuori dal server se il sistema è critico. Un backup locale non ti protegge da guasto disco, ransomware o errore umano.

Se vuoi monitorare l’andamento nel tempo, tieni almeno queste metriche:

• stato dei servizi systemd
• latenza pagina iniziale
• errori HTTP 5xx
• uso RAM e swap
• dimensione indici Elasticsearch

Problemi comuni e come isolarli

Se Zammad non parte o mostra pagina bianca, non andare subito a modificare configurazioni a caso. Segui il layer corretto:

1. DNS: il nome risolve al server giusto?
2. Edge: proxy o CDN rispondono?
3. Origin: Nginx o il servizio applicativo sono up?
4. App: il backend Zammad è sano?
5. DB: PostgreSQL è raggiungibile?
6. Storage: disco pieno o permessi sbagliati?

Comandi rapidi utili:

curl -I https://helpdesk.example.com
systemctl status nginx postgresql redis-server elasticsearch --no-pager
journalctl -u zammad -n 100 --no-pager
df -h

Se trovi 502 Bad Gateway, il problema è spesso nel backend o nel proxy upstream. Se trovi 500, guarda i log applicativi e il database. Se la pagina resta in loading infinito, sospetta Elasticsearch, Redis o una coda interna bloccata.

Upgrade e manutenzione

Una volta in produzione, l’aspetto più importante è mantenere il sistema aggiornato senza rompere la compatibilità tra componenti. Prima di aggiornare Zammad, leggi sempre le note di rilascio e verifica la versione richiesta di Elasticsearch, PostgreSQL e Redis.

Prima di un upgrade serio:

1. backup del database
2. backup configurazioni Nginx e file applicativi personalizzati
3. snapshot della VM se disponibile
4. finestra di manutenzione

Durante il cambio, osserva i log in tempo reale:

journalctl -f

Se qualcosa va storto, il rollback minimo è tornare ai pacchetti precedenti e ripristinare database e configurazioni salvate. Non aggiornare mai senza sapere come tornare indietro.

Conclusione operativa

Installare Zammad su Ubuntu 22.04 non è difficile, ma va trattato come una piccola piattaforma: database, ricerca, cache, proxy, TLS e posta devono funzionare insieme. Il punto critico non è tanto l’installazione del pacchetto, quanto il controllo della catena completa e la preparazione di backup e rollback.

Se vuoi, il passo successivo sensato è documentare una variante più vicina al tuo scenario: installazione con Docker, reverse proxy dietro Cloudflare, oppure configurazione completa di posta in ingresso e uscita con dominio aziendale.

Assunzione: i comandi e i path indicati sono riferiti a un’installazione standard su Ubuntu 22.04 con repository ufficiali e nome host dedicato.