Installare SuiteCRM su Debian 12 passo dopo passo

SuiteCRM su Debian 12: scelta dello stack

Per Debian 12 la combinazione più lineare è Nginx + PHP-FPM + MariaDB. Funziona bene in produzione, è semplice da mantenere e riduce gli attriti tipici dell’installazione web manuale. SuiteCRM è una web app PHP che richiede attenzione su versione PHP, estensioni, permessi file, memoria e timeout. Se questi punti sono corretti, l’installazione procede senza sorprese.

Qui sotto trovi una procedura completa, pensata per un server pulito. Il risultato atteso è un’istanza SuiteCRM raggiungibile via HTTPS, con database dedicato, cache base attiva e permessi coerenti per gli aggiornamenti futuri.

Prerequisiti operativi

Prima di iniziare verifica di avere:

• un server Debian 12 aggiornato;
• accesso root o sudo;
• un nome DNS già puntato al server, ad esempio crm.example.com;
• almeno 2 GB di RAM, meglio 4 GB se il carico non è minimale;
• spazio disco libero sufficiente per webroot, log e backup.

SuiteCRM richiede PHP compatibile con la versione che intendi installare. Per una installazione recente conviene usare una release supportata dal progetto e verificare sul sito ufficiale i requisiti aggiornati prima del deploy. Se il pacchetto SuiteCRM scelto impone una versione PHP specifica, adegua i repository o il runtime di conseguenza.

Aggiornamento base del sistema

Parti con un aggiornamento pulito del sistema e degli indici dei pacchetti.

sudo apt update
sudo apt -y upgrade
sudo reboot

Dopo il reboot, rientra e verifica lo stato generale.

uname -a
systemctl --failed

Obiettivo: nessun servizio in failed e kernel aggiornato. Se ci sono errori a questo stadio, correggili prima di installare lo stack applicativo.

Installazione di Nginx, MariaDB e PHP-FPM

Installa il web server, il database e i moduli PHP più comuni per SuiteCRM. L’elenco preciso delle estensioni può variare in base alla versione, ma questa base copre la maggior parte dei casi.

sudo apt install -y nginx mariadb-server mariadb-client \
php-fpm php-cli php-mysql php-xml php-curl php-gd php-imap php-mbstring \
php-zip php-intl php-bcmath php-soap php-opcache unzip curl wget

Controlla che i servizi siano attivi.

systemctl status nginx --no-pager
systemctl status mariadb --no-pager
systemctl status php8.2-fpm --no-pager

Se la tua versione di Debian espone una release PHP diversa, il nome del servizio può cambiare. Verifica con systemctl list-units | grep fpm.

Hardening iniziale di MariaDB

Prima di creare il database applicativo, esegui la configurazione di sicurezza di base.

sudo mysql_secure_installation

Imposta una password per l’utente root del database solo se il tuo modello operativo la prevede; in molti ambienti Debian moderni l’accesso amministrativo locale usa autenticazione socket. In ogni caso, disabilita accessi anonimi e database di test se non servono.

Verifica poi che il server risponda localmente.

sudo mariadb -e "SELECT VERSION();"

Atteso: una riga con la versione del motore. Se questo comando fallisce, fermati e controlla i log di MariaDB in /var/log/mysql/ o via journalctl -u mariadb.

Creazione del database e dell’utente dedicato

Crea un database separato per SuiteCRM e un utente con privilegi limitati solo su quel database.

sudo mariadb

CREATE DATABASE suitecrm CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'suitecrmuser'@'localhost' IDENTIFIED BY 'SCEGLI_PASSWORD_FORTE';
GRANT ALL PRIVILEGES ON suitecrm.* TO 'suitecrmuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Usa utf8mb4 per evitare problemi con emoji, caratteri speciali e dati multilingua. Non riutilizzare account condivisi: se in futuro devi ruotare credenziali o fare audit, un utente dedicato semplifica tutto.

Download di SuiteCRM

Scarica l’archivio della release desiderata dal canale ufficiale del progetto. Se hai un URL preciso della release, usalo; in alternativa scarica dal repository o dalla pagina download ufficiale.

cd /tmp
wget -O suitecrm.zip "URL_UFFICIALE_DA_SOSTITUIRE"

Verifica l’integrità se il progetto pubblica checksum o firme. Questo è importante in produzione: non installare archivi non verificati.

Estrai il pacchetto in una directory temporanea e poi spostalo nel path definitivo.

unzip suitecrm.zip
sudo mkdir -p /var/www/suitecrm
sudo rsync -a --delete ./SuiteCRM/ /var/www/suitecrm/

Se il nome della cartella estratta cambia in base alla release, adatta il comando rsync. L’obiettivo è avere il codice applicativo sotto /var/www/suitecrm.

Permessi e ownership corretti

Nginx e PHP-FPM devono poter leggere i file e scrivere nelle directory richieste dall’applicazione. Il principio è semplice: ownership coerente, privilegi minimi, niente chmod larghi a caso.

sudo chown -R www-data:www-data /var/www/suitecrm
sudo find /var/www/suitecrm -type d -exec chmod 755 {} \;
sudo find /var/www/suitecrm -type f -exec chmod 644 {} \;

Alcune directory, come cache, custom, modules, upload o altre indicate dal setup di SuiteCRM, potrebbero richiedere scrittura. Se il wizard di installazione segnala permessi mancanti, correggi solo quelle directory e non tutto il tree indiscriminatamente.

Configurazione di PHP per SuiteCRM

SuiteCRM è sensibile a limiti di memoria, upload e timeout. Modifica il file di configurazione PHP-FPM o il file php.ini del ramo in uso. Su Debian 12 il percorso tipico è simile a /etc/php/8.2/fpm/php.ini, ma verifica la versione installata.

Imposta almeno questi parametri, adattandoli al tuo contesto:

memory_limit = 512M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
max_input_time = 300
date.timezone = Europe/Rome

Per performance e stabilità, controlla anche OPcache. In genere è già presente, ma vale la pena assicurarsi che sia attivo.

php -i | grep -i opcache

Se serve, abilita il modulo e riavvia PHP-FPM.

sudo phpenmod opcache
sudo systemctl restart php8.2-fpm

Atteso: nessun errore in systemctl status php8.2-fpm e valori coerenti con la configurazione.

Configurazione di Nginx per il virtual host

Crea un server block dedicato per il dominio di SuiteCRM. Il file tipico può essere /etc/nginx/sites-available/suitecrm.conf.

server {
    listen 80;
    server_name crm.example.com;
    root /var/www/suitecrm;
    index index.php index.html;

    client_max_body_size 64M;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        access_log off;
        log_not_found off;
    }

    location ~ /(\.ht|config|cache|custom|data|logs|vendor) {
        deny all;
    }
}

Abilita il sito e ricarica Nginx.

sudo ln -s /etc/nginx/sites-available/suitecrm.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

La validazione con nginx -t è obbligatoria: se fallisce, non fare reload. Correggi prima la sintassi.

Prima verifica HTTP locale

Prima di lanciare il wizard web, verifica che il server risponda almeno in HTTP.

curl -I http://crm.example.com

Atteso: HTTP/1.1 200 oppure un redirect pianificato verso HTTPS. Se ottieni 4xx o 5xx, la causa è quasi sempre nel virtual host, nei permessi o nel socket PHP-FPM.

Se stai lavorando in locale prima del DNS definitivo, puoi testare anche con l’IP e l’header Host.

curl -I -H 'Host: crm.example.com' http://127.0.0.1

Abilitazione HTTPS con Let’s Encrypt

In produzione non lasciare l’istanza in chiaro. La via più semplice è Certbot con plugin Nginx.

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

Durante il wizard scegli il redirect da HTTP a HTTPS. Al termine verifica il rinnovo automatico.

sudo certbot renew --dry-run

Atteso: successo del dry-run e certificato correttamente agganciato al virtual host. Se il dominio non è ancora propagato, risolvi prima il DNS.

Installazione web di SuiteCRM

Apri https://crm.example.com nel browser. Il wizard di installazione dovrebbe chiedere i dati del database, i dettagli dell’admin e alcuni parametri di base.

Compila con attenzione:

• database name: suitecrm
• database user: suitecrmuser
• database password: quella scelta in precedenza
• host database: localhost
• admin username: non banale, meglio non admin
• admin password: forte e unica

Se il wizard segnala incompatibilità PHP, torna alla sezione delle estensioni e verifica i moduli mancanti con php -m. Se segnala problemi di scrittura, correggi ownership e permessi solo nelle directory richieste.

Verifiche post-installazione

Dopo il completamento, esegui questi controlli minimi:

curl -I https://crm.example.com
systemctl status nginx --no-pager
systemctl status php8.2-fpm --no-pager
systemctl status mariadb --no-pager

Atteso: risposta HTTPS valida, servizi attivi, nessun loop di errori nei log. Poi entra nel pannello e verifica che il login funzioni, che il cruscotto si apra e che la creazione di un record di test non generi errori.

Controlla anche i log applicativi. In molte installazioni li trovi sotto la directory dell’app, ad esempio in /var/www/suitecrm/logs, oppure nei log di sistema per PHP-FPM e Nginx.

sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u php8.2-fpm -n 100 --no-pager

Hardening minimo consigliato

Una volta online, applica alcune misure base:

• disabilita l’accesso diretto alle directory sensibili via Nginx;
• mantieni aggiornati Debian, PHP e SuiteCRM;
• usa backup giornalieri del database e dei file di configurazione;
• limita l’esposizione SSH con chiavi e, se possibile, IP allowlist;
• monitora spazio disco, RAM e errori PHP.

Se il server ospita anche altri siti, isola il virtual host e usa un pool PHP-FPM dedicato per evitare interferenze tra applicazioni. È una buona pratica quando l’istanza cresce o quando la piattaforma diventa critica.

Backup e rollback

Prima di ogni modifica importante conserva una copia dei file di configurazione e del database. Per il rollback minimo ti servono:

• backup di /etc/nginx/sites-available/suitecrm.conf;
• dump SQL del database suitecrm;
• copia della directory applicativa o almeno di config.php e custom/.

Un esempio di dump coerente:

mysqldump -u root -p suitecrm > suitecrm.sql

Se qualcosa si rompe dopo un cambio, ripristina prima il virtual host e i permessi, poi il database. Evita di fare modifiche multiple senza un punto di ritorno chiaro.

Assunzione: stai installando una release recente di SuiteCRM su Debian 12 con Nginx, PHP-FPM e MariaDB; se la versione del CRM richiede un runtime diverso, adegua prima i requisiti e poi ripeti la procedura.

Problemi frequenti e sintomi rapidi

Se vedi una pagina bianca, i colpevoli più probabili sono PHP-FPM fermo, errori fatali nel codice o memoria insufficiente. Se ottieni 502, controlla socket PHP, permessi e pool FPM. Se il wizard non vede il database, verifica credenziali, host e ascolto locale di MariaDB. Se l’upload fallisce, alza client_max_body_size e i limiti PHP coerenti.

Per una verifica veloce del layer applicativo, il comando più utile resta curl -I sul dominio e la lettura immediata di error.log di Nginx insieme al log di PHP-FPM. In meno di cinque minuti in genere capisci se il problema è DNS, web server, PHP o database.

Con questa base hai un’installazione pulita, manutenibile e già abbastanza robusta per un uso reale. Il passo successivo, se l’istanza diventa importante, è integrare backup off-site, monitoraggio e una policy di aggiornamento regolare per Debian, PHP e SuiteCRM.