Come installare OTRS su Debian 12 passo dopo passo

OTRS su Debian 12: scelta dello stack e prerequisiti

OTRS non si installa bene “a pacchetti e basta” su Debian 12: serve mettere in ordine dipendenze Perl, database, web server e permessi, poi fare una configurazione coerente con la versione che stai usando. Prima decisione pratica: se vuoi un’installazione stabile, usa un account di servizio dedicato, MariaDB/MySQL locale o remoto affidabile, e Apache come web server. Nella maggior parte dei casi è la combinazione più lineare su Debian.

Assumo che tu voglia una installazione classica su una macchina Debian 12 recente, con accesso root o sudo, hostname già definito e DNS funzionante. Se il server è esposto in produzione, tratta il setup come change controllato: backup, finestra di intervento e rollback chiaro.

Cosa serve prima di iniziare

• Debian 12 aggiornato.
• Accesso sudo o root.
• Database MariaDB/MySQL.
• Apache 2 con mod_perl e mod_ssl se usi HTTPS.
• Dominio o FQDN già risolto verso il server.

Verifica veloce dello stato base:

cat /etc/debian_version
hostname -f
apt update
apt -y upgrade

Se `hostname -f` non restituisce un FQDN corretto, sistemalo prima: OTRS e il web server si appoggiano spesso a nome host, URL e mail di notifica coerenti.

Pacchetti di sistema e dipendenze Perl

Su Debian 12 il punto critico è la compatibilità delle librerie Perl richieste da OTRS. La versione esatta di OTRS cambia il set di dipendenze, quindi qui conviene lavorare per verifica e non per supposizione. Se stai installando una release recente supportata dal vendor, il flusso è: installi i pacchetti base, poi aggiusti le dipendenze mancanti in base al controllo preinstallazione.

Installa i componenti base:

apt update
apt -y install apache2 mariadb-server mariadb-client \
  libapache2-mod-perl2 perl perl-modules \
  libdbi-perl libdbd-mysql-perl libxml-libxml-perl \
  libyaml-libyaml-perl libgd-perl libcrypt-ssleay-perl \
  libjson-xs-perl libdatetime-perl libtimedate-perl \
  libnet-dns-perl libmail-imapclient-perl \
  libsoap-lite-perl libtext-csv-xs-perl \
  libapache-dbi-perl libarchive-zip-perl \
  libdigest-sha-perl libfile-checktree-perl

Nota pratica: non tutti questi moduli sono sempre necessari per ogni build di OTRS, ma coprono gran parte degli scenari comuni. Se un modulo non è disponibile nel repository Debian, non forzare workaround ciechi: verifica prima la documentazione della tua release OTRS e l’output del controllo dipendenze.

Controllo rapido dei moduli Perl:

perl -MDBI -MDBD::mysql -MXML::LibXML -e 'print "OK\n"'

Se questo comando fallisce, hai già un problema di base sulle dipendenze e conviene risolverlo prima di proseguire con OTRS.

Creazione dell’utente di servizio e directory applicative

Evita di far girare OTRS come root. Crea un utente dedicato e prepara una struttura file chiara. Questo riduce il rischio operativo e semplifica permessi e manutenzione.

adduser --system --group --home /opt/otrs --shell /bin/bash otrs
mkdir -p /opt/otrs
chown -R otrs:otrs /opt/otrs

Se stai installando da sorgente o da archivio ufficiale, estrai i file in `/opt/otrs` o nella directory prevista dalla release. Dopo l’estrazione, verifica che i file siano di proprietà corretta:

ls -ld /opt/otrs
find /opt/otrs -maxdepth 2 -type d | head

Se l’installazione prevede una directory web separata per gli statici, annotala subito: spesso gli errori nascono da path sbagliati tra document root e directory applicativa.

Database MariaDB: creazione schema e utente

OTRS usa bene un database dedicato. Non condividere schema con altre applicazioni se puoi evitarlo. Crea database, utente e privilegi minimi necessari.

mysql -u root -p

Dentro MariaDB:

CREATE DATABASE otrs CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'otrs'@'localhost' IDENTIFIED BY 'PASSWORD_FORTE';
GRANT ALL PRIVILEGES ON otrs.* TO 'otrs'@'localhost';
FLUSH PRIVILEGES;

Se il database è remoto, sostituisci `localhost` con l’host corretto e limita l’accesso da IP specifici. Dopo la creazione, verifica la connessione:

mysql -u otrs -p -h localhost otrs -e 'SHOW TABLES;'

Se questo comando restituisce errore di accesso, non andare avanti: prima sistema credenziali, bind address, firewall o policy di rete.

Apache: virtual host, moduli e HTTPS

Apache resta la scelta più lineare per OTRS su Debian 12. Abilita i moduli necessari e prepara un virtual host pulito. Almeno: `perl`, `headers`, `rewrite`, `ssl` se usi TLS.

a2enmod perl headers rewrite ssl cgi
systemctl restart apache2
apache2ctl -M | egrep 'perl|headers|rewrite|ssl|cgi'

Il virtual host deve puntare alla parte pubblica dell’applicazione secondo la struttura della tua release. In molte installazioni OTRS si espone tramite una directory tipo `/opt/otrs/var/httpd/htdocs` o equivalente. Controlla la documentazione della versione che stai installando, perché il path cambia tra release e packaging.

Esempio di vhost da adattare:

<VirtualHost *:80>
    ServerName otrs.example.com
    DocumentRoot /opt/otrs/var/httpd/htdocs
    <Directory /opt/otrs/var/httpd/htdocs>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Se usi HTTPS, configura il certificato e forza il redirect da HTTP a HTTPS. Verifica che il certificato sia valido e che il nome comune o SAN corrisponda al dominio del portale OTRS.

apache2ctl configtest
systemctl reload apache2
curl -I http://otrs.example.com
curl -Ik https://otrs.example.com

Atteso: risposta 200, 301 o 302 coerente con il redirect previsto, senza errori di TLS.

Installazione di OTRS e verifica dipendenze

A questo punto copia o estrai i file di OTRS nella directory finale e passa alla verifica preinstallazione. Se la tua release include uno script di controllo, usalo prima di tentare setup e avvio.

cd /opt/otrs
perl bin/otrs.CheckModules.pl

Questo comando è il primo filtro serio: ti dice quali moduli Perl mancano o non sono nella versione attesa. Risolvi i moduli mancanti con i pacchetti Debian quando possibile. Se un modulo non è nel repo, fermati e verifica se la release OTRS è compatibile con Debian 12 senza workaround manuali.

Se il package include uno script di installazione o configurazione iniziale, eseguilo seguendo la documentazione della tua versione. In molte installazioni ci sono passaggi come:

• configurazione del database;
• impostazione hostname e URL base;
• creazione account amministratore;
• inizializzazione tabelle.

Se il setup è web-based, apri l’URL del portale e completa il wizard. Se è CLI-based, esegui il comando previsto dalla release e conserva l’output completo: è il punto dove emergono errori di schema o permessi.

Permessi, cron e servizi di supporto

OTRS dipende spesso da job schedulati per posta, coda ticket, notifiche e manutenzione. Se il cron non è attivo, l’installazione sembra funzionare ma poi si degrada. Verifica subito che i job richiesti siano presenti e che il servizio cron sia attivo.

systemctl status cron
crontab -u otrs -l

In molte installazioni trovi script di manutenzione in `bin/` o `var/cron/`. Il nome esatto dipende dalla release, quindi non inventarlo: controlla l’albero file della tua installazione. Un controllo utile è questo:

find /opt/otrs -maxdepth 2 -type f | egrep 'cron|daemon|Maint|otrs'

Per i permessi, verifica che l’utente del web server possa leggere i file necessari e scrivere dove serve, ma senza concedere scrittura indiscriminata. Un controllo rapido:

namei -l /opt/otrs
sudo -u www-data test -r /opt/otrs/Kernel/Config.pm && echo OK

Se il web server gira con un utente diverso da `www-data`, sostituiscilo con quello reale. L’obiettivo è semplice: il processo Apache deve leggere l’applicazione e scrivere solo nelle directory previste.

Configurazione mail in uscita e test funzionale

OTRS senza mail affidabile è un impianto zoppo. Subito dopo il setup verifica l’SMTP in uscita. Puoi usare un relay interno o un servizio esterno, ma la configurazione deve essere coerente con TLS, autenticazione e policy antispam.

Controlla i parametri mail nella configurazione di OTRS e testa una notifica verso un indirizzo valido. Se il tuo ambiente lo consente, fai un test SMTP a livello di sistema per distinguere errori applicativi da problemi di rete o credenziali.

openssl s_client -starttls smtp -connect mail.example.com:587

Se il relay risponde correttamente ma OTRS non invia, il problema è quasi sempre nella configurazione dell’applicazione, nei permessi delle code o nelle credenziali salvate nel backend.

Controlli finali: log, accesso web e salute del servizio

Prima di dichiarare conclusa l’installazione, fai un giro di verifica su log e servizio web. I log ti dicono subito se sei davanti a un errore Perl, DB, permessi o template.

journalctl -u apache2 -n 100 --no-pager
ls -lah /var/log/apache2/
find /opt/otrs -maxdepth 3 -type f | egrep 'log|error'

Dal lato funzionale, apri il portale OTRS e verifica:

• pagina di login caricata senza errori;
• creazione ticket funzionante;
• invio mail in uscita;
• accesso area admin;
• assenza di errori 5xx nei log Apache.

Se vedi pagina bianca o errore 500, il primo controllo è il log Apache e quello applicativo. Se il problema è un 500 subito dopo il login, quasi sempre sei su dipendenze Perl, configurazione DB o permessi file.

Rollback e punti di ripristino

Se il deployment è nuovo e non ancora in produzione, il rollback più pulito è fermare Apache, rimuovere la directory applicativa installata, droppare il database creato per il test e ripristinare eventuali backup precedenti.

systemctl stop apache2
mysql -u root -p -e "DROP DATABASE otrs; DROP USER 'otrs'@'localhost';"
rm -rf /opt/otrs

Se invece hai già dati utente o ticket, non fare azioni distruttive senza export e backup verificati. In quel caso il rollback corretto è ripristino del dump DB e della directory applicativa dalla snapshot precedente.

Assunzione: la release OTRS usata è compatibile con Debian 12 e con la versione di Perl/MariaDB installata; se non lo è, il blocco va risolto a monte scegliendo una release supportata o un ambiente containerizzato dedicato.

Checklist rapida di validazione

• `apache2ctl configtest` senza errori.
• `systemctl status apache2` attivo e senza restart loop.
• `perl bin/otrs.CheckModules.pl` senza moduli mancanti critici.
• Connessione DB funzionante con utente OTRS.
• Portale web raggiungibile via HTTP o HTTPS.
• Invio mail test OK.

Se uno di questi punti fallisce, non passare oltre: il problema è quasi sempre già visibile nei log o nel controllo dipendenze. La parte difficile non è installare OTRS, è fermarsi abbastanza presto quando qualcosa non torna.