Installare Flarum su un VPS: guida PHP e MariaDB

Installare Flarum su un VPS con PHP e MariaDB

Installando Flarum su un VPS si ottiene un forum basato su PHP e MariaDB, senza Docker, Ruby o un job runner separato. Questo è il motivo per sceglierlo. Installare Discourse su un VPS significa usare uno stack Docker che include Ruby, PostgreSQL, Redis e un worker in background; 2 GB di RAM sono il minimo pratico prima di aggiungere backup o un servizio di posta. Discourse giustifica queste risorse in una community attiva con migliaia di post al giorno. In un forum con poche centinaia di utenti, invece, si tratta di componenti per i quali si paga ogni mese senza utilizzarli. Flarum si integra in uno stack PHP che potrebbe essere già in uso, quindi un VPS con 1 GB di RAM, nginx e MariaDB può ospitarlo insieme agli altri servizi. Se la scelta è ancora aperta, il confronto più ampio tra i software per forum self-hosted analizza anche le altre soluzioni.

Questa guida utilizza Flarum 1.x, attualmente nella serie 1.8. Ad agosto 2026 Flarum 2.0 è ancora una release candidate, quindi 1.8 è la versione da usare per un forum da cui dipendono altri utenti. In questo caso le estensioni sono più importanti della versione del core e la maggior parte degli autori delle estensioni non è ancora passata alla 2.0.

Requisiti del server per Flarum 1.8

I requisiti documentati di Flarum sono PHP 7.3 o versioni successive, MySQL 5.6+ o MariaDB 10.0.5+, e nginx o Apache con mod_rewrite. Ubuntu 24.04 include PHP 8.3 e MariaDB 10.11, quindi i pacchetti della distribuzione soddisfano entrambi i requisiti senza repository di terze parti. Le estensioni PHP richieste da Flarum sono curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer e zip. È inoltre necessario l'accesso alla shell, perché in questo caso Composer non è opzionale: ogni estensione di Flarum è un pacchetto Composer e non è possibile aggiungerne una senza eseguire Composer.

Flarum è una normale applicazione PHP. Se hai già uno stack LAMP su Ubuntu 24.04, gran parte delle operazioni delle due sezioni successive è già stata eseguita e puoi passare rapidamente alla sezione sul database.

Installare PHP e le estensioni richieste da Flarum

sudo apt update
sudo apt install -y nginx mariadb-server composer
sudo apt install -y php8.3-fpm php8.3-cli php8.3-curl php8.3-gd php8.3-mbstring php8.3-mysql php8.3-xml php8.3-zip
php -m | grep -E 'curl|dom|gd|mbstring|pdo_mysql|zip'
composer --version

I nomi dei pacchetti non corrispondono esattamente all'elenco di Flarum. L'estensione dom è inclusa in php8.3-xml, mentre fileinfo, json, openssl e tokenizer sono compilate in PHP 8.3 su Ubuntu, quindi per queste non esiste alcun pacchetto da installare. grep dovrebbe stampare sei righe e composer --version dovrebbe riportare una release 2.x. Conviene correggere subito un'estensione mancante, perché Composer rifiuta di installare Flarum senza di essa e l'errore indica il nome dell'estensione:

  Problem 1
    - flarum/core[v1.8.0, ..., v1.8.17] require ext-gd * -> it is missing from your system.
      Install or enable PHP's gd extension.

Verificare che PHP da riga di comando e il gestore dei processi FastCGI (PHP-FPM) abbiano la stessa versione. Composer viene eseguito dal binario da riga di comando, mentre il forum viene eseguito da FPM, quindi php -v e sudo php-fpm8.3 -v devono corrispondere. Le versioni possono divergere su un sistema che ha accumulato diverse versioni di PHP da un repository di terze parti; in questo caso, un'estensione installata per una versione non è visibile dall'altra.

Crea il database e un utente database dedicato

sudo mariadb-secure-installation
sudo mariadb

CREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'use-a-long-random-password';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Assegna a Flarum un utente database dedicato invece di root. Il grant copre flarum.* e nient'altro, quindi una vulnerabilità SQL injection in un'estensione che non hai scritto non può leggere gli altri database. Anche il set di caratteri è importante: utf8mb4 gestisce correttamente emoji e script non latini, mentre il precedente utf8 di MySQL usa una codifica a tre byte che tronca un post al primo carattere a quattro byte. Verifica che l'utente funzioni prima di proseguire.

mariadb -u flarum -p flarum -e 'SELECT DATABASE();'

Il comando dovrebbe stampare flarum. ERROR 1045 (28000): Access denied for user 'flarum'@'localhost' indica che la password non corrisponde oppure che l'utente è stato creato per un host diverso da localhost.

Installare Flarum su un VPS con Composer, bloccato alla versione 1.8

Per prima cosa crea un utente di sistema proprietario del codice. Eseguire Composer come root lascia file di proprietà di root in vendor/ e storage/. In seguito PHP non può scrivere nella propria cache e il forum risponde a ogni richiesta con un errore 500.

sudo useradd --system --home-dir /srv/flarum --shell /bin/bash flarum
sudo install -d -o flarum -g flarum -m 755 /srv/flarum
sudo -iu flarum

L'ultimo comando apre una shell come utente flarum, nella directory /srv/flarum. Da questo punto fino alla fine della guida, ogni comando viene eseguito con questo utente, a meno che non inizi con sudo.

composer create-project flarum/flarum:^1.8.0 .

Il vincolo ^1.8.0 blocca la versione. Accetta le versioni patch 1.8.x e rifiuta la versione 2.0, come richiesto mentre la 2.0 è una release candidate. Composer scarica lo scheletro, risolve flarum/core e le relative dipendenze e lascia public/, storage/, vendor/, composer.json e uno script da riga di comando flarum.

Su un VPS di piccole dimensioni, è in questo passaggio che possono verificarsi gli errori. Due problemi diversi producono sintomi simili. PHP Fatal error: Allowed memory size of 134217728 bytes exhausted è il valore memory_limit di PHP. Anteporre COMPOSER_MEMORY_LIMIT=-1 al comando rimuove questo limite per una sola esecuzione. Un Killed isolato su una riga propria, senza errori PHP, indica l'intervento dell'out-of-memory killer del kernel. Puoi verificarlo con dmesg | tail. In questo caso la macchina ha realmente esaurito la RAM, quindi aggiungi swap. Aumentare il limite di PHP peggiora la situazione, perché PHP richiede ancora più memoria prima che intervenga il kernel.

Perché solo /public deve essere esposta sul web

La radice del progetto contiene config.php con la password del database in chiaro, vendor/ con tutte le dipendenze e storage/ con i log e le sessioni memorizzate nella cache. Nulla di tutto questo deve essere esposto su Internet. Flarum mantiene tutto ciò che deve essere accessibile dal web in un'unica sottodirectory, public/, che contiene index.php, una cartella assets/ e poco altro. Imposta la radice del server web su /srv/flarum/public: in questo modo il resto dell'albero non è raggiungibile tramite HTTP per costruzione, senza dipendere da una regola da ricordare.

Se imposti la radice su /srv/flarum, il rischio è concreto. Una richiesta a /config.php non restituisce informazioni utili, perché PHP esegue il file e questo restituisce soltanto un array. /storage/logs/flarum.log, invece, espone a un estraneo i tuoi stack trace e gli errori del database, mentre /composer.lock comunica la versione esatta di ogni pacchetto utilizzato: un elenco di vulnerabilità note da tentare.

Assegna a PHP-FPM un pool dedicato

Flarum richiede l'accesso in scrittura a tre percorsi: la directory radice del progetto, in modo che l'installer possa creare config.php; storage/, per i log e la cache; e assets/, per gli avatar e i loghi caricati. I file appartengono all'utente flarum, quindi la soluzione corretta è un pool PHP-FPM eseguito come flarum. nginx continua a essere eseguito come www-data e accede ai file soltanto in lettura.

Scrivi /etc/php/8.3/fpm/pool.d/flarum.conf:

[flarum]
user = flarum
group = flarum
listen = /run/php/php8.3-fpm-flarum.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = ondemand
pm.max_children = 10
pm.process_idle_timeout = 30s
php_admin_value[memory_limit] = 256M
php_admin_value[upload_max_filesize] = 16M
php_admin_value[post_max_size] = 17M

sudo systemctl restart php8.3-fpm
ls -l /run/php/php8.3-fpm-flarum.sock

Il socket deve essere indicato come srw-rw---- 1 www-data www-data. Il processo master viene eseguito come root e crea il socket; per questo può assegnarne la proprietà a www-data mentre i worker vengono eseguiti come flarum. Se il socket non esiste, sudo journalctl -u php8.3-fpm -n 30 stampa la riga FPM rifiutata. pm = ondemand avvia i processi worker solo quando arriva una richiesta, quindi un forum poco frequentato consuma quasi memoria tra una visita e l'altra.

Il blocco server di nginx

Flarum include nel root del progetto uno snippet nginx denominato .nginx.conf. Contiene la regola di riscrittura, gli header della cache e le impostazioni di compressione. Includetelo invece di copiarlo, così un aggiornamento di Flarum che modifica lo snippet applicherà le modifiche al server senza interventi manuali.

server {
    listen 80;
    listen [::]:80;
    server_name forum.example.com;

    root /srv/flarum/public;
    index index.php;
    client_max_body_size 16M;

    include /srv/flarum/.nginx.conf;

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm-flarum.sock;
    }
}

Salvate il file come /etc/nginx/sites-available/flarum, quindi abilitatelo.

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

nginx -t deve rispondere a syntax is ok e test is successful. La direttiva include è quella che viene più spesso omessa. Se manca, si verifica un sintomo molto specifico: la pagina iniziale viene caricata correttamente, mentre ogni link a una discussione restituisce un errore 404 da nginx. Flarum gestisce in PHP un URL come /d/1-hello-world. Questo percorso non corrisponde a un file presente sul disco. Senza la regola try_files $uri $uri/ /index.php?$query_string dello snippet, nginx cerca quindi una directory denominata d, non la trova e restituisce 404 prima ancora di inoltrare la richiesta a PHP. Apache applica la stessa logica di routing usando il file .htaccess già presente in public/. Il file ha effetto solo se il blocco <Directory> corrispondente imposta AllowOverride All.

Aggiungere TLS prima di eseguire l'installer

Generare il certificato adesso, non in seguito. Durante l'installazione Flarum scrive il proprio URL di base in config.php e ricava questo URL dall'indirizzo visualizzato nel browser. Se si esegue l'installazione su http://, tutti gli URL degli asset generati successivamente da Flarum iniziano con http://. Dopo l'aggiunta di TLS (Transport Layer Security), il browser blocca queste richieste come contenuto misto e il forum viene caricato come testo senza stile e senza JavaScript. Prima completare la configurazione di certbot per Let's Encrypt su nginx, verificare che https://forum.example.com mostri una pagina, quindi tornare a questa procedura.

Se l'installazione è già stata eseguita tramite HTTP non crittografato, la correzione richiede una sola riga. Modificare /srv/flarum/config.php in modo che la chiave url sia impostata su 'url' => 'https://forum.example.com',, quindi eseguire php flarum cache:clear con l'utente flarum.

Esegui l'installer e limita i permessi di config.php

Apri https://forum.example.com in un browser. L'installer web di Flarum richiede il nome del database, il nome utente e la password del database creati in precedenza, il titolo del forum e l'account amministratore. Scrive config.php e crea le tabelle. Al termine, limita i permessi del file che ora contiene la password del database.

sudo chmod 640 /srv/flarum/config.php

Il file rimane leggibile e scrivibile da flarum, ovvero l'utente con cui viene eseguito FPM, e non è leggibile da nessun altro account del server. Verifica quindi l'installazione dalla shell.

php flarum info

Il comando mostra la versione del core, la versione di PHP, le estensioni abilitate, il mail driver e i percorsi utilizzati. È il primo comando da eseguire quando qualcosa non funziona correttamente e la prima informazione che ti chiederà chiunque ti aiuti.

Perché le email di registrazione e reimpostazione della password falliscono senza messaggi

Questa sezione determina se il tuo forum supererà la prima settimana. Le prime due email che un nuovo forum invia sono la conferma della registrazione e la reimpostazione della password. Entrambe vengono inviate nel momento esatto in cui una persona sta decidendo se la tua community è reale. Entrambe possono fallire senza messaggi. Chi non riceve l'email non può segnalartelo e nulla nella dashboard di amministrazione diventa rosso.

Flarum dispone di quattro driver email, configurabili in Administration, quindi Email: smtp, mail, mailgun e log. Scegli smtp e configurarlo con un servizio email che recapiti effettivamente i messaggi. Il driver mail passa il messaggio a un binario sendmail locale. Questo binario non è presente in una nuova VPS Ubuntu, quindi il messaggio non viene recapitato e non viene generato alcun errore. Il driver log scrive il corpo del messaggio in storage/logs/ e non invia nulla, perché è destinato allo sviluppo.

Salva le impostazioni, quindi premi il pulsante Send Test Mail nella stessa pagina. Questo pulsante è l'unico meccanismo di verifica disponibile, quindi usalo prima di invitare qualcuno. Se il messaggio non arriva, consulta il log.

tail -n 50 /srv/flarum/storage/logs/flarum.log

Una connessione rifiutata, un accesso non riuscito e un errore di negoziazione TLS vengono registrati lì, insieme all'host e alla porta utilizzati. Una riga contenente Connection could not be established with host smtp.example.com indica che la porta è bloccata o errata. La causa più comune è che il provider blocchi per impostazione predefinita la porta 25 in uscita. La combinazione porta 587 e campo di cifratura impostato su tls funziona con quasi tutti i servizi email.

Quando l'invio email non funziona, un visitatore che si registra vede il banner di errore generico di Flarum, Oops! Something went wrong. Please reload the page and try again., perché si verifica un errore durante l'invio della conferma. In entrambi i casi, quella persona non può accedere e probabilmente non ti contatterà per segnalare il problema.

Ottenere l'accettazione del messaggio è un problema distinto dal suo invio. Un messaggio proveniente dall'indirizzo di una VPS, senza record SPF o DKIM pubblicati per il tuo dominio, finisce nella cartella spam oppure viene eliminato senza alcun messaggio di mancato recapito. Di conseguenza, il log mostra un invio riuscito, mentre il destinatario non vede nulla. Inviare email in modo affidabile dalle applicazioni self-hosted spiega quali record DNS pubblicare e quali servizi relay conviene utilizzare.

Le estensioni sono pacchetti Composer, quindi gli aggiornamenti si eseguono con un comando

In Flarum un'estensione è un pacchetto Composer. Non esiste un pulsante di caricamento e non c'è alcun file zip da copiare in una directory. È una scelta progettuale intenzionale: le versioni vengono risolte in relazione tra loro, l'insieme esatto viene registrato in composer.lock e un'estensione che dipende da una libreria PHP riceve quella libreria installata correttamente. Il costo è che aggiungerne una richiede tre comandi eseguiti dall'utente flarum.

composer require 'fof/upload:*'
php flarum migrate
php flarum cache:clear

Quindi abilitala in Administration, poi Extensions. Ogni comando svolge un compito distinto. composer require copia il codice sul disco. php flarum migrate esegue le migrazioni del database incluse nell'estensione, creando così le relative tabelle. php flarum cache:clear ricompila i bundle JavaScript e CSS che il browser carica. Saltare l'ultimo comando produce il problema tipico: l'estensione è elencata, l'interruttore è attivo, ma nel browser non cambia nulla, anche dopo numerosi ricaricamenti.

La rimozione di un'estensione avviene in ordine inverso. Disabilitala prima nel pannello di amministrazione, quindi rimuovi il pacchetto. Flarum lascia intenzionalmente le tabelle dell'estensione, così una successiva riattivazione non comporta la perdita dei dati. Per eliminarle a loro volta, annulla prima le relative migrazioni e poi rimuovi il codice.

php flarum migrate:reset --extension fof-upload
composer remove fof/upload
php flarum cache:clear

L'ID dell'estensione usato in quel comando è il nome del pacchetto con la barra sostituita da un trattino. Se preferisci fare clic invece di digitare, composer require 'flarum/extension-manager:*' aggiunge una pagina di amministrazione ufficiale che funge da interfaccia per Composer. Esegue le stesse operazioni dell'utente web, richiede la stessa memoria e gli stessi permessi di scrittura e presenta gli stessi problemi. Per questo, quando qualcosa non funziona, la riga di comando resta il metodo più affidabile.

Perché composer update rifiuta di aggiornare Flarum

L’aggiornamento di Flarum e di tutte le estensioni richiede un comando Composer seguito da due comandi Flarum. Prima esegui il backup del database.

composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear

Leggi l’output invece di presumere che l’operazione sia riuscita. Il caso rilevante si verifica quando Composer rifiuta di eseguire qualsiasi modifica:

Your requirements could not be resolved to an installable set of packages.

Il messaggio indica che un’estensione installata dichiara un vincolo flarum/core che esclude la release a cui vuoi eseguire l’aggiornamento. Composer non viola il vincolo. Mantiene quindi l’intera installazione alla versione precedente invece di creare una combinazione che l’autore dell’estensione ha dichiarato non funzionante. Individua il pacchetto responsabile.

composer why-not flarum/core 1.8.17

L’output elenca ogni pacchetto che impedisce l’uso di quella versione e il vincolo dichiarato da ciascuno. A questo punto puoi attendere che l’autore pubblichi una release compatibile oppure rimuovere l’estensione e rinunciarvi. Questo è il compromesso del modello Composer. È importante comprenderlo prima di installare quindici estensioni in un forum da cui dipendono altre persone. Preferisci le estensioni per cui è stata pubblicata di recente una release e mantieni l’elenco abbastanza breve da poterlo leggere.

Cosa eseguire nel backup

Eseguire il backup del database e della directory del progetto. Tutto il resto può essere ricreato.

mariadb-dump -u flarum -p --single-transaction flarum > flarum-$(date +%F).sql
sudo tar czf flarum-files.tgz -C /srv flarum

Nei sistemi meno recenti mariadb-dump si chiama mysqldump; in Ubuntu 24.04 entrambi i nomi funzionano. Il database contiene ogni post, ogni utente e ogni impostazione. La directory del progetto contiene config.php, composer.json (che rappresenta l’elenco effettivo delle estensioni in uso) e assets/ con gli avatar e i loghi caricati. È possibile ignorare vendor/, perché composer install lo ricrea da composer.lock e storage/ viene rigenerato automaticamente. Copiare entrambi i file fuori dal server, perché un backup archiviato sulla macchina che dovrebbe proteggere non è un backup. Il ripristino richiede un’installazione pulita di Flarum della stessa versione, composer install, il ripristino dei file salvati nella posizione corretta e il caricamento del file SQL.

FAQ

Flarum può essere eseguito su un VPS con 1 GB?

Sì, per una community di piccole dimensioni. In condizioni normali, Flarum è costituito da PHP-FPM che gestisce le richieste e da MariaDB; con pm = ondemand i processi PHP esistono soltanto mentre qualcuno sta leggendo. Il picco si verifica durante l'installazione: composer create-project risolve in memoria l'intero grafo delle dipendenze ed è il passaggio che più probabilmente viene interrotto dall'out-of-memory killer. Crea un file di swap prima dell'installazione oppure esegui Composer una volta su una macchina più potente e copia l'albero dei file.

Perché i link alle discussioni restituiscono 404 mentre la pagina iniziale funziona?

Nel server block di nginx manca include /srv/flarum/.nginx.conf;. Flarum gestisce tramite PHP URL come /d/1-hello-world, ma quel percorso non corrisponde a un file sul disco. Senza la direttiva try_files $uri $uri/ /index.php?$query_string dello snippet, nginx cerca una directory chiamata d, non la trova e restituisce direttamente 404 senza chiamare PHP. Su Apache lo stesso routing dipende da public/.htaccess, che viene ignorato se il blocco <Directory> non imposta AllowOverride All.

Perché il forum ha perso tutti gli stili dopo l'attivazione di HTTPS?

Flarum memorizza l'URL di base in config.php, acquisito dall'indirizzo usato durante l'esecuzione dell'installer. Se hai eseguito l'installazione su HTTP semplice, Flarum continua a generare URL degli asset http://; il browser li blocca come contenuto misto all'interno di una pagina HTTPS, lasciando il testo privo di stile. Modifica la chiave url in /srv/flarum/config.php impostandola sull'indirizzo https:// ed esegui php flarum cache:clear con l'utente proprietario dei file.

Perché nessuno riceve l'email di conferma della registrazione?

Controlla prima il driver di posta. Il driver mail richiede un binario sendmail locale, che un VPS Ubuntu appena creato non include, mentre il driver log scrive in storage/logs/ e non invia nulla. Passa a smtp, usa la porta 587 con la crittografia impostata su tls, perché la maggior parte dei provider blocca la porta 25 in uscita, quindi fai clic su Send Test Mail. Se il log mostra un invio riuscito ma il messaggio non arriva, il problema riguarda la deliverability e non la configurazione; pubblica quindi i record SPF e DKIM per il dominio usato per l'invio.

Devo installare Flarum 1.8 o 2.0?

Installa 1.8. Ad agosto 2026 Flarum 2.0 è una release candidate e, soprattutto, molte estensioni dichiarano ancora un vincolo flarum/core che si ferma alla versione 1.x. Installare oggi la versione 2.0 significa eseguire un forum le cui estensioni non possono essere aggiornate insieme; è esattamente il problema che composer why-not serve a diagnosticare. Blocca la versione con flarum/flarum:^1.8.0 e rivaluta la situazione quando le estensioni da cui dipendi avranno pubblicato le release per la versione 2.0.