Come installare Neos CMS su Debian 12

Neos CMS su Debian 12: scelta dello stack

Per un’installazione pulita di Neos CMS su Debian 12 conviene partire da uno stack LEMP classico: Nginx come web server, PHP-FPM per l’esecuzione del codice e MariaDB come database. È una combinazione stabile, facilmente osservabile e semplice da mantenere nel tempo.

Neos non è un CMS “tradizionale” con file PHP esposti direttamente come WordPress: richiede una configurazione corretta del document root, del rewrite e di PHP, oltre a una base dati affidabile. La parte più importante, prima ancora dell’installazione, è preparare bene il sistema: versioni compatibili, estensioni PHP necessarie, permessi corretti e un virtual host senza ambiguità.

Questa procedura assume Debian 12 aggiornato, accesso root o sudo e un dominio già puntato verso il server. Se il server è dietro proxy o CDN, la logica non cambia, ma vanno rivisti anche header, TLS e trust del client.

Prerequisiti minimi

Prima di iniziare, verifica di avere:

• Debian 12 aggiornato
• Un nome host valido, ad esempio cms.example.com
• Accesso SSH con privilegi sudo
• Un database MariaDB dedicato
• PHP-FPM installato con le estensioni richieste da Neos

Se il server è in produzione, evita di installare tutto “a mano” senza un backup o uno snapshot. Anche una procedura semplice può impattare il sito se esiste già un virtual host in ascolto sulla stessa porta o se il document root è condiviso con altri servizi.

Assunzione operativa: uso Nginx, PHP-FPM e MariaDB. Se vuoi Apache o PostgreSQL, la logica cambia in alcuni punti e va adattata.

Aggiornamento base del sistema

Parti sempre da un sistema allineato. Su Debian 12 l’obiettivo è avere repository in ordine e pacchetti aggiornati prima di installare la stack applicativa.

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git unzip ca-certificates gnupg

Se il server è appena provisionato, controlla anche l’orario e la sincronizzazione NTP, perché certificati TLS e alcuni processi di build possono fallire con un clock fuori sync.

timedatectl status

Atteso: System clock synchronized: yes. Se è no, risolvi prima quel punto.

Installazione dei pacchetti necessari

Neos richiede PHP moderno e alcune estensioni comuni. Su Debian 12, la versione di PHP disponibile nei repository standard è adeguata per una base iniziale, a patto di installare le estensioni giuste.

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

Se usi una versione di Neos che richiede una release PHP specifica, verifica prima la compatibilità sul sito ufficiale del progetto o nella documentazione del pacchetto Composer. Non dare per scontato che “PHP 8.x” sia sempre sufficiente per tutte le major release.

Controlla che PHP-FPM sia attivo:

systemctl status php8.2-fpm

Atteso: active (running). Il nome del servizio può variare leggermente in base alla versione installata.

Configurazione del database MariaDB

Neos usa un database per contenuti, configurazioni e metadati. La pratica corretta è creare un database dedicato e un utente con privilegi limitati solo su quel database.

sudo mysql

All’interno della shell MariaDB:

CREATE DATABASE neos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'neosuser'@'localhost' IDENTIFIED BY 'password_forte_da_sostituire';
GRANT ALL PRIVILEGES ON neos.* TO 'neosuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Non riutilizzare utenti generici come root o account già presenti su altri servizi. Se devi cambiare la password, fallo subito e tieni il segreto fuori da ticket, chat e file condivisi in chiaro.

Verifica che il database esista:

mysql -u neosuser -p -e "SHOW DATABASES;"

Atteso: la lista deve includere neos.

Creazione dell’utente di sistema e directory applicativa

Per mantenere ordinati permessi e ownership, conviene creare una directory dedicata sotto /var/www e assegnarla a un utente di servizio coerente con il web server o con il deploy process.

sudo mkdir -p /var/www/neos
sudo chown -R www-data:www-data /var/www/neos

Se preferisci separare i privilegi, puoi usare un utente dedicato al deploy e lasciare a www-data solo i permessi necessari in runtime. In ogni caso, evita scritture indiscriminate sulla root del progetto.

Scarica il progetto con Composer. Se Composer non è installato, aggiungilo prima:

sudo apt install -y composer

Poi inizializza il progetto Neos con il metodo consigliato dal framework. In molti casi si usa il package distribution ufficiale come base del sito:

cd /var/www/neos
composer create-project --no-dev neos/neos-base-distribution .

Se il comando fallisce, la prima verifica è la versione di PHP e la connettività verso Packagist e GitHub. I failure più comuni sono estensioni mancanti o limiti di memoria troppo bassi durante il download e l’installazione dei pacchetti.

Configurazione di PHP-FPM per Neos

Neos beneficia di una configurazione PHP coerente, con limiti adeguati a backend e importazione contenuti. I valori esatti dipendono dal carico, ma una base ragionevole per partire è questa:

sudo nano /etc/php/8.2/fpm/php.ini

Cerca e regola, con cautela, i parametri principali:

memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 120
max_input_vars = 5000

Dopo le modifiche, riavvia PHP-FPM:

sudo systemctl restart php8.2-fpm

Verifica che non ci siano errori di sintassi o crash del worker:

journalctl -u php8.2-fpm -n 50 --no-pager

Atteso: nessun errore grave di pool o di configurazione. Se trovi errori su memory_limit o file di pool, correggi prima di proseguire.

Configurazione di Nginx

Neos deve essere servito dal directory pubblico del progetto, in genere /var/www/neos/Web o la directory pubblica prevista dalla versione installata. La parte critica è il rewrite: tutte le richieste non statiche devono passare dall’entry point del framework.

Crea un virtual host dedicato:

sudo nano /etc/nginx/sites-available/neos.conf

Usa una configurazione di base simile alla seguente, adattando dominio e socket PHP-FPM:

server {
    listen 80;
    server_name cms.example.com;

    root /var/www/neos/Web;
    index index.php;

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

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

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

Abilita il sito e testa la sintassi:

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

Se nginx -t fallisce, non ricaricare il servizio. Il rollback è semplice: correggi il file o rimuovi il symlink in sites-enabled. Questo evita un downtime inutile.

Installazione tramite Composer e configurazione iniziale

Dopo aver creato la base del progetto, verifica che Composer abbia completato l’installazione senza errori e che la struttura delle directory sia coerente.

cd /var/www/neos
composer install --no-dev

In alcune versioni di Neos, la configurazione iniziale può richiedere un wizard web o un comando CLI per generare la chiave di sito e completare il bootstrap. La procedura esatta dipende dalla release e dal package distribution utilizzato. Se la documentazione della versione installata prevede un comando specifico, eseguilo dal path del progetto con l’utente corretto.

Un controllo utile è vedere se i file di configurazione base sono presenti:

find /var/www/neos -maxdepth 2 -type f | head

Atteso: presenza di file del progetto, directory Configuration e Web o struttura equivalente.

Permessi corretti

I problemi più fastidiosi su CMS PHP sono quasi sempre permessi o ownership sbagliati. Neos deve poter scrivere solo dove serve: cache, log, upload e configurazioni runtime previste dal framework.

In modo conservativo, assegna i file all’utente del web server e verifica che non ci siano directory world-writable:

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

Se hai un workflow di deploy più avanzato, questa parte va adattata. L’obiettivo non è “aprire tutto”, ma mantenere il minimo privilegio necessario. Dopo l’installazione, controlla i log se compaiono errori di scrittura su cache o file temporanei.

Abilitare HTTPS con Let’s Encrypt

Su un’installazione pubblica, non lasciare il sito in HTTP puro. Con Nginx e Debian 12 puoi usare Certbot per ottenere un certificato Let’s Encrypt.

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

Dopo il rilascio del certificato, verifica il rinnovo automatico:

systemctl status certbot.timer

Atteso: timer attivo. In caso di proxy esterni o CDN, verifica anche che il certificato lato origin e lato edge non siano in conflitto. Se il frontend termina TLS altrove, il certificato su origin può essere comunque utile per il tratto interno o per test diretti.

Verifiche post-installazione

Prima di considerare chiusa l’installazione, fai tre controlli semplici ma importanti: risposta HTTP, log del web server e log PHP-FPM.

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

Atteso: 200, 301 o 302 coerenti con il redirect verso HTTPS o verso il wizard iniziale. Se ottieni 500, il problema è quasi sempre PHP, rewrite o permessi.

Controlla i log Nginx:

sudo tail -n 50 /var/log/nginx/error.log

e i log PHP-FPM:

journalctl -u php8.2-fpm -n 50 --no-pager

Se il sito mostra pagina bianca, il primo sospetto è un errore PHP non mostrato a schermo ma registrato nei log. Non abilitare display_errors in produzione; usa i log.

Hardening base e manutenzione

Una volta online, conviene chiudere il cerchio con un hardening minimo. Non serve complicare tutto: bastano poche misure sensate per ridurre il rischio operativo.

• Aggiorna regolarmente Debian e i pacchetti PHP
• Limita l’accesso SSH con chiavi e, se possibile, con MFA
• Disabilita l’accesso diretto a directory sensibili via web server
• Monitora spazio disco, RAM e stato dei servizi
• Fai backup del database e della directory applicativa

Per i backup, la parte davvero importante è la verifica del restore. Un backup non testato non vale molto in caso di incidente. Tieni almeno una copia fuori dal server e una procedura di ripristino documentata.

Backup e rollback

Prima di modificare configurazioni importanti, salva sempre i file originali. Per Nginx e PHP-FPM basta anche una copia semplice con timestamp.

sudo cp /etc/nginx/sites-available/neos.conf /etc/nginx/sites-available/neos.conf.bak
sudo cp /etc/php/8.2/fpm/php.ini /etc/php/8.2/fpm/php.ini.bak

Se una modifica rompe il sito, il rollback più rapido consiste nel ripristinare il file di configurazione e ricaricare il servizio:

sudo cp /etc/nginx/sites-available/neos.conf.bak /etc/nginx/sites-available/neos.conf
sudo nginx -t && sudo systemctl reload nginx

Per il database, prima di qualsiasi intervento significativo, fai un dump:

mysqldump -u root -p neos > neos.sql

Conserva il dump in un posto sicuro, meglio se cifrato e fuori dal server. Se devi ripristinare, verifica prima la compatibilità tra schema e versione del CMS.

Problemi tipici e correzioni rapide

Se l’installazione si blocca, i casi più comuni sono prevedibili:

• 502 Bad Gateway: PHP-FPM non gira o socket errato
• 500 Internal Server Error: errore PHP, permessi o rewrite
• Pagina bianca: fatal error PHP non mostrato a schermo
• Impossibile scrivere cache: ownership o permessi errati
• Wizard non raggiungibile: document root sbagliato o Nginx senza try_files

Nel dubbio, il metodo più efficace resta sempre lo stesso: controlla prima il layer più basso che può spiegare il sintomo. DNS, poi Nginx, poi PHP-FPM, poi database. Saltare direttamente alle modifiche applicative fa perdere tempo e aumenta il rischio di introdurre altri problemi.

Conclusione operativa

Installare Neos CMS su Debian 12 non è complicato, ma richiede ordine. Il punto decisivo non è solo far partire il wizard: è avere un sistema coerente, con PHP-FPM allineato, Nginx configurato bene, database dedicato e permessi sotto controllo.

Se vuoi un setup più robusto, il passo successivo è integrare monitoraggio, backup automatici e una pipeline di deploy ripetibile. In ambiente hosting o multi-sito, conviene anche standardizzare template Nginx, versioni PHP e policy di aggiornamento, così ogni installazione Neos resta prevedibile e facile da mantenere.