1 15/10/2026 11 min

Stack corretto per Flarum su Ubuntu: PHP, Composer, web server e database

Flarum non è il classico CMS che “si copia nella root e parte”. Su Ubuntu 24.04, 22.04 e 20.04 conviene trattarlo come applicazione PHP moderna: codice gestito da Composer, web root puntata sulla cartella public, PHP-FPM per l’esecuzione e un database MySQL/MariaDB solido alle spalle. Se salti uno di questi punti, il problema non è quasi mai Flarum: è quasi sempre la piattaforma sotto.

La scelta più pulita, in produzione, è Nginx + PHP-FPM + MariaDB. Apache funziona, ma richiede più attenzione sui rewrite e spesso finisce configurato in modo meno prevedibile. Se l’obiettivo è installare Flarum una volta e poi mantenerlo con pochi attriti, Nginx resta la strada più lineare.

Questa guida assume un server Ubuntu recente, accesso sudo, un dominio già puntato al server e la possibilità di aprire temporaneamente il sito in HTTP/HTTPS durante il setup. Dove serve, indico sia i comandi sia il punto preciso da verificare nel caso qualcosa non torni.

Prerequisiti minimi e scelta delle versioni

Per Flarum conta più la compatibilità del runtime che la distribuzione in sé. Su Ubuntu 24.04 il PHP di sistema tende a essere più recente; su 22.04 e 20.04 può essere necessario installare una versione PHP adeguata dai repository ufficiali o da un PPA affidabile. Il punto pratico è questo: Flarum richiede una versione PHP supportata dalla release che stai installando. Se il comando di Composer segnala vincoli su estensioni o versione, non forzare: allinea prima PHP e moduli.

I prerequisiti tipici sono questi: Nginx, PHP-FPM, estensioni PHP per database, stringhe multibyte, XML, ZIP, cURL, GD o ImageMagick se richiesto dai plugin, Composer e un database MariaDB o MySQL. In pratica, la parte delicata non è installare i pacchetti, ma assicurarsi che il pool PHP-FPM sia attivo e che Nginx punti alla directory corretta.

Aggiornamento base del sistema e installazione dei pacchetti

Parti da un sistema aggiornato. Questo riduce il rischio di conflitti sulle librerie e ti porta in uno stato ripetibile prima di installare l’applicazione.

Su Ubuntu 24.04, 22.04 o 20.04:

sudo apt update
sudo apt upgrade -y
sudo apt install -y nginx mariadb-server unzip curl git

Per PHP, installa il metapacchetto del FPM e le estensioni necessarie. Il nome esatto del pacchetto varia con la versione di PHP disponibile sul sistema; per questo è utile verificare prima quale versione stai installando.

php -v
sudo apt install -y php-fpm php-cli php-mysql php-xml php-mbstring php-curl php-zip php-gd php-intl php-opcache

Se il comando precedente non trova una versione adeguata o installa una release troppo vecchia, il problema va risolto prima di procedere. Il controllo rapido è semplice:

php -v
php -m | egrep 'mbstring|curl|xml|zip|intl|mysqli|pdo_mysql'

Il secondo comando deve mostrare i moduli richiesti. Se manca qualcosa, aggiungilo subito; Composer può fallire più avanti con messaggi poco utili se lasci il sistema in uno stato incompleto.

Database MariaDB: utente dedicato, permessi minimi e charset corretto

Flarum va installato con un database dedicato e un utente separato. Non usare l’account root del database nell’applicazione: è inutile e peggiora la superficie d’attacco. La configurazione minima corretta è un database dedicato, un utente con permessi solo su quel database e charset UTF-8 coerente.

sudo mysql
CREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarumuser'@'localhost' IDENTIFIED BY 'PASSWORD_FORTE_DA_RUOTARE';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarumuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

La password in chiaro va considerata solo come valore temporaneo da inserire durante il setup: appena l’installazione è finita, documentala fuori dal body dell’applicazione e ruotala se finisce in script, ticket o note operative non protette. Il punto da verificare subito è la presenza del database e la possibilità di collegarsi con l’utente dedicato.

mysql -u flarumuser -p -h localhost -e 'SHOW DATABASES;'

Se il comando restituisce il database flarum, il layer database è pronto. Se fallisce, il problema è nei privilegi o nella password, non in Flarum.

Composer e directory dell’applicazione

Flarum si installa tramite Composer, quindi Composer deve essere presente e funzionante. Su Ubuntu spesso è meglio usare il pacchetto del sistema solo se è aggiornato; in caso contrario, installa Composer dal binario ufficiale verificandone l’integrità. Qui non serve improvvisare: se Composer non è affidabile, l’installazione lo sarà ancora meno.

composer --version

Se il comando non esiste, installalo. Se esiste ma è troppo vecchio, aggiornalo. Una volta pronto, crea la directory dell’applicazione, ad esempio sotto /var/www/flarum.

sudo mkdir -p /var/www/flarum
sudo chown -R $USER:$USER /var/www/flarum
cd /var/www/flarum

Per l’installazione iniziale, il metodo più pulito è creare il progetto Flarum con Composer. Il nome esatto del pacchetto può dipendere dalla release corrente del progetto, quindi se stai seguendo una versione specifica consulta il repository ufficiale e usa il pacchetto indicato da quella versione. Il controllo da fare dopo il comando è che la cartella contenga file come composer.json, public/ e le directory dell’applicazione.

composer create-project flarum/flarum . --stability=beta

Se preferisci una procedura manuale o Composer segnala vincoli di versione, il punto da risolvere è quasi sempre PHP o una estensione mancante. Non forzare con opzioni che aggirano i requisiti: rischi di installare un albero che parte e poi si rompe al primo aggiornamento.

Nginx: document root su public e rewrite corretti

Flarum deve essere esposto dalla cartella public. Questo è il dettaglio che più spesso viene sbagliato: se punti la root alla cartella superiore, apri più superficie del necessario e rischi problemi con i file statici e le route “pulite”.

Crea un virtual host dedicato, per esempio /etc/nginx/sites-available/flarum:

server { listen 80; server_name forum.example.com; root /var/www/flarum/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php-fpm.sock; } location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ { expires 30d; access_log off; log_not_found off; } location ~ /\. { deny all; }
}

Il socket PHP-FPM va adattato alla versione effettiva installata. Su Ubuntu può essere qualcosa come /run/php/php8.1-fpm.sock, /run/php/php8.2-fpm.sock o una versione più recente su 24.04. Verificalo prima di ricaricare Nginx:

ls -l /run/php/
systemctl status php*-fpm --no-pager

Abilita il sito e controlla la sintassi. Se Nginx non passa il test, non andare avanti: correggi subito il file di configurazione.

sudo ln -s /etc/nginx/sites-available/flarum /etc/nginx/sites-enabled/flarum
sudo nginx -t
sudo systemctl reload nginx

Se il test fallisce, il punto da guardare è il file di configurazione, non Flarum. Se il test passa ma il sito mostra errore 502, il problema è PHP-FPM o il socket sbagliato.

Permessi file: il punto dove molti setup si rompono

Flarum deve poter scrivere nelle directory di cache, log e upload, ma non deve avere permessi larghi su tutto il tree. La regola pratica è: proprietà coerente sul codice, scrittura limitata alle directory che la richiedono.

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

In alcuni casi conviene mantenere il codice di proprietà del tuo utente amministrativo e consentire a www-data solo sulle directory di runtime. È una scelta più ordinata per gli aggiornamenti, ma richiede disciplina. Se sei in dubbio, parti dalla soluzione semplice, verifica che il sito funzioni, poi raffina i permessi in un secondo passaggio.

Il controllo minimo è osservare se Flarum riesce a creare cache e scrivere log. Se trovi errori di permission denied, cerca nei log PHP-FPM e Nginx prima di toccare di nuovo i permessi in modo casuale.

Installazione web di Flarum e compilazione della configurazione

A questo punto apri il dominio nel browser. Flarum presenta il suo installer web, dove inserire i dati del database, il nome del forum, la mail amministrativa e la password iniziale dell’admin. Qui bisogna essere precisi: il database host è di solito localhost, il nome è quello creato prima, e l’utente deve avere accesso solo a quel database.

Se l’installer non appare e vedi pagina bianca, 500 o 502, non saltare alle conclusioni. Verifica nell’ordine: Nginx, PHP-FPM, estensioni PHP, connessione al database. Di solito il problema è uno di questi quattro punti, non l’applicazione in sé.

Durante l’installazione, assicurati che il nome del forum, l’URL canonico e la mail amministrativa siano corretti. Un URL impostato male qui si riflette poi su link, login e notifiche.

HTTPS con Let’s Encrypt e header essenziali

Una volta che il forum risponde correttamente in HTTP, passa a HTTPS. Su una installazione standard la strada più semplice è Certbot con il plugin Nginx. Prima però verifica che il dominio punti davvero al server e che la porta 80 sia raggiungibile, altrimenti il challenge fallisce e perdi tempo dietro a un problema di DNS o firewall.

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

Quando il certificato è attivo, controlla che il redirect verso HTTPS sia corretto e che il sito non entri in loop. Un check rapido:

curl -I http://forum.example.com
curl -I https://forum.example.com

Il primo comando dovrebbe restituire un redirect verso HTTPS. Il secondo deve rispondere con 200 o un altro codice coerente con l’applicazione, non con errori TLS. Se vuoi un setup più robusto, aggiungi header di sicurezza con cautela e testa prima che non impattino asset, login o embed esterni.

Verifiche finali: log, salute applicativa e sintomi tipici

Un’installazione fatta bene non si giudica dal fatto che “si apre il sito”, ma dal fatto che i componenti rispondono in modo coerente. I controlli minimi da fare subito dopo l’installazione sono questi:

1. Nginx senza errori di sintassi e con il virtual host attivo.
2. PHP-FPM in stato active (running).
3. Connessione al database funzionante dall’utente applicativo.
4. Login amministrativo possibile.
5. Creazione di una discussione di test e verifica che l’upload allegati funzioni, se previsto.

Per i log, i punti classici da controllare sono:

sudo tail -n 50 /var/log/nginx/error.log
sudo journalctl -u php*-fpm -n 50 --no-pager
sudo tail -n 50 /var/www/flarum/storage/logs/*.log

Se trovi errori 500, cerca stack trace PHP o problemi di permessi. Se trovi 502, il colpevole è quasi sempre PHP-FPM. Se il browser resta in caricamento e poi va in timeout, controlla DNS, firewall, reverse proxy o saturazione del backend prima di toccare Flarum.

Aggiornamenti e manutenzione ordinaria

Flarum va mantenuto aggiornato con un approccio ordinato: backup del database, backup della directory dell’applicazione, aggiornamento via Composer e verifica post-update. Non aggiornare mai “a mano libera” in produzione senza un minimo di rollback disponibile.

cd /var/www/flarum
composer update
php flarum cache:clear

Prima di un aggiornamento vero, salva database e file critici. Il rollback minimo deve includere almeno il dump SQL e una copia del tree applicativo. Se l’aggiornamento rompe una estensione, la prima cosa da fare è disabilitare il plugin sospetto e verificare che il forum torni operativo prima di investigare oltre.

Per il database, un dump coerente è sufficiente nella maggior parte dei casi:

mysqldump -u root -p flarum > flarum-backup.sql

Il file di backup va protetto come dato sensibile, perché contiene contenuti, utenti e metadati del forum. Non lasciarlo in una directory pubblica, non committarlo e non inviarlo in chiaro via mail.

Problemi frequenti su Ubuntu 24.04, 22.04 e 20.04

Su Ubuntu 24.04 il primo rischio è la discrepanza tra versione PHP richiesta dall’app e versione installata dal sistema. Su 22.04 e 20.04 il problema ricorrente è l’opposto: PHP troppo vecchio o moduli mancanti. In entrambi i casi, il sintomo tipico è un errore Composer o una pagina vuota con log PHP che puntano a estensioni assenti.

Un altro problema comune è il rewrite sbagliato in Nginx. Se le route di Flarum non funzionano e solo la home page risponde, controlla che try_files sia presente e che la root sia davvero /public. Se invece il certificato HTTPS è attivo ma il forum redirige all’URL sbagliato, la causa è quasi sempre una base URL errata durante l’installazione o in una configurazione proxy a monte.

Infine, attenzione agli stack con proxy/CDN davanti al server. Se usi Cloudflare o un bilanciatore, devi allineare header, IP reali e schema HTTPS, altrimenti puoi avere loop di redirect o problemi di login. In questi casi conviene verificare il comportamento con curl -I direttamente sull’origine e dal dominio pubblico, così separi il problema del backend da quello del layer esterno.

Sequenza operativa rapida, se vuoi andare dritto al punto

Se devi fare l’installazione in modo lineare, la sequenza è questa:

  1. Aggiorna Ubuntu e installa Nginx, MariaDB, PHP-FPM, Composer e le estensioni richieste.
  2. Crea il database dedicato e l’utente con privilegi minimi.
  3. Scarica Flarum con Composer nella directory finale del sito.
  4. Configura Nginx con root su public e rewrite corretti.
  5. Verifica socket PHP-FPM, permessi e log.
  6. Completa l’installer web, poi abilita HTTPS con Let’s Encrypt.
  7. Fai un test funzionale: login, nuova discussione, caricamento pagine e risposta dei log.

Se uno dei passaggi fallisce, non andare avanti per inerzia. Il setup di Flarum è abbastanza semplice quando ogni layer è corretto, ma diventa fragile se si cerca di coprire errori di base con tentativi casuali. La procedura giusta è sempre la stessa: osserva il sintomo, identifica il layer, correggi il minimo necessario e verifica subito il risultato.