Installare Drupal 11 su hosting condivisi: guida alla struttura FLAT senza cartella web/

Se stai leggendo questa guida, probabilmente hai già provato a installare Drupal 11 su un hosting condiviso e hai avuto problemi. Oppure hai seguito il tutorial ufficiale di Drupal e ti sei scontrato con un muro.

Nessun problema: questa guida ti spiegherà perché c'è un problema tecnico di fondo e come risolverlo in modo semplice e definitivo.

🤔 Il problema di base: perché la struttura standard di Drupal NON funziona sugli hosting condivisi?

Partiamo dall'inizio. Drupal 11, quando viene installato con Composer (il gestore di pacchetti PHP ufficiale), crea una struttura di cartelle come questa:

progetto-drupal/
├── composer.json
├── composer.lock
├── vendor/          ← tutte le librerie PHP (Symfony, Twig, ecc.)
└── web/             ← la ROOT pubblica (document root)
    ├── index.php
    ├── core/
    ├── modules/
    ├── themes/
    └── sites/

Questa struttura è perfetta dal punto di vista della sicurezza perché tutto il codice PHP sensibile (le librerie in vendor/, le configurazioni, ecc.) si trova fuori dalla cartella accessibile al web. Solo la cartella web/ è esposta pubblicamente.

Per far funzionare questa struttura, l'hosting deve permetterti di impostare la document root (la cartella che il server web mostra ai visitatori) su web/. In pratica, devi poter dire ad Apache/Nginx: "quando qualcuno visita il mio sito, mostra i file che stanno dentro la cartella web/, non quelli nella cartella principale".

🚫 Il problema sugli hosting condivisi

La maggior parte degli hosting condivisi NON ti permette di cambiare la document root. La document root è fissa e bloccata su public_html/ (o httpdocs/ o www/). Non puoi modificarla. Punto.

Ma c'è anche un secondo problema, ancora più subdolo: la direttiva open_basedir.

Facciamo un esempio concreto. Se provassi a installare Drupal con la struttura standard su un hosting condiviso:

public_html/         ← document root fissa (open_basedir punta qui)
├── web/             ← qui dentro ci sono index.php, core, modules...
│   └── ...
vendor/              ← FUORI da public_html! PHP non può accederci!

Il risultato? PHP non riesce a caricare le librerie in vendor/ perché si trovano fuori dai limiti imposti da open_basedir. Drupal non si avvia nemmeno, o dà errori inspiegabili.

Morale: sugli hosting condivisi, tutto il codice deve stare dentro public_html/. Non puoi avere nulla fuori. Ecco perché serve la struttura FLAT.

📜 Un po' di storia: come si installava Drupal "una volta"?

Prima dell'avvento di Composer (che è diventato lo standard ufficiale da Drupal 8 in poi), Drupal si installava in modo molto più semplice: scaricavi un pacchetto .zip o .tar.gz dal sito ufficiale, lo decomprimevi direttamente in public_html/, e il gioco era fatto.

Quelle si chiamano installazioni "legacy" (o "tradizionali"). Funzionavano così:

public_html/         ← tutto dentro qui
├── index.php
├── core/
├── modules/
├── themes/
├── sites/
├── vendor/          ← già incluso nel pacchetto
└── ...

Semplice, no? Nessun problema con open_basedir, nessuna storia di document root. E funzionava perfettamente.

Ma c'era un problema enorme: la gestione delle dipendenze. Drupal moderno usa decine di librerie PHP esterne (Symfony, Guzzle, Twig, Psr, ecc.). Nel pacchetto scaricabile, queste librerie erano già incluse nella cartella vendor/. Ma come si aggiornavano? Come si gestivano le versioni? Era un caos. Spesso le installazioni legacy finivano con versioni mixate, librerie mancanti o in conflitto.

Per questo motivo, dal 2018 circa, il team di Drupal ha abbandonato ufficialmente le installazioni "legacy" con pacchetto scaricabile. Oggi l'unico metodo supportato è Composer.

Ma Composer crea la struttura con web/... e noi non possiamo usarla sugli hosting condivisi. Sembra un paradosso, vero? Fortunatamente esiste una soluzione geniale: il plugin Scaffold.

✨ Cos'è il plugin Scaffold di Drupal (e perché è rivoluzionario)

Gli sviluppatori di Drupal erano ben consapevoli del problema degli hosting condivisi. Per questo hanno creato un plugin Composer chiamato drupal/scaffold.

Quando lanci composer create-project per installare Drupal, Scaffold viene eseguito automaticamente e copia i file "scaffold" nella cartella che tu gli indichi. Di default, li copia in web/. Ma grazie a Scaffold, puoi decidere tu la cartella di destinazione, modificando il file composer.json.

In poche parole, Scaffold disaccoppia la posizione dei file pubblici dal resto del progetto. Questo significa che possiamo dire a Scaffold: "copia index.php, .htaccess e tutti i file pubblici direttamente nella root del progetto, non dentro web/".

Ed è esattamente quello che faremo in questa guida: useremo Scaffold per generare una struttura FLAT, dove tutto (inclusi i file pubblici) sta dentro public_html/, risolvendo così i problemi di document root fissa e open_basedir.

Il bello è che manteniamo tutti i vantaggi di Composer: composer.json, composer.lock, aggiornamenti sicuri, gestione perfetta delle dipendenze. Il meglio di entrambi i mondi.

🔧 Cosa significa "struttura FLAT"?

La struttura FLAT è semplicemente l'installazione di Drupal in cui non esiste la cartella web/. Tutto è nella stessa cartella root.

Struttura standard (NON funziona su hosting condivisi):

public_html/
└── web/
    ├── core/
    ├── modules/
    ├── themes/
    ├── vendor/
    └── index.php

Struttura FLAT (funziona su hosting condivisi):

public_html/
├── core/
├── modules/
├── themes/
├── vendor/
├── index.php
├── .htaccess
├── composer.json
├── composer.lock
└── sites/
    └── default/
        └── files/

In pratica, prendiamo tutto ciò che starebbe dentro web/ e lo "spostiamo su" di un livello, eliminando la cartella intermedia.

Questa struttura risolve entrambi i problemi:

• ✅ La document root può rimanere public_html/ (nessun problema con hosting che non permettono di cambiarla)
• ✅ Tutto il codice (compreso vendor/) sta dentro public_html/, quindi open_basedir non blocca nulla
• ✅ Manteniamo Composer e il plugin Scaffold per la gestione dei file pubblici

📋 Requisiti

• Accesso SSH al tuo hosting
• Composer installato (la maggior parte degli hosting lo ha, altrimenti chiedi al supporto)
• Dominio puntato alla cartella public_html/
• PHP 8.1 o superiore

🧭 GUIDA PASSO PASSO

1️⃣ Prepara l'ambiente

Collegati via SSH e vai nella cartella del dominio:

cd ~/domains/tuodominio.it

Elimina eventuali installazioni precedenti (per partire da zero):

rm -rf public_html
rm -rf drupal11tmp

Crea una nuova public_html vuota:

mkdir public_html

2️⃣ Installa Drupal in una cartella temporanea

Usiamo una cartella temporanea per preparare l'installazione senza toccare ancora public_html/:

composer create-project drupal/recommended-project:^11 drupal11tmp

Questo comando crea la cartella drupal11tmp/ con dentro la struttura standard (inclusa web/).

3️⃣ Entra nella cartella temporanea

cd drupal11tmp

4️⃣ Trasforma in struttura FLAT

Ora spostiamo tutto il contenuto di web/ nella root del progetto temporaneo:

mv web/* web/.* . 2>/dev/null
rmdir web

Ora la cartella drupal11tmp/ contiene core/, modules/, index.php, ecc. direttamente nella root.

5️⃣ Modifica il file composer.json

Dobbiamo dire a Composer e a Scaffold che la nuova root pubblica è la cartella corrente (non più web/). Apri composer.json e modifica la sezione extra.drupal-scaffold.locations:

{
    "extra": {
        "drupal-scaffold": {
            "locations": {
                "web-root": "./"
            }
        }
    }
}

Poi rigenera i file di Drupal con Scaffold:

composer drupal:scaffold
composer dump-autoload

6️⃣ Copia tutto in public_html

Ora copiamo l'intera installazione (con struttura FLAT già pronta) dentro public_html/:

cp -R * ~/domains/tuodominio.it/public_html
cp -R .* ~/domains/tuodominio.it/public_html 2>/dev/null

7️⃣ Crea la cartella files per i file caricati

mkdir -p ~/domains/tuodominio.it/public_html/sites/default/files
chmod 775 ~/domains/tuodominio.it/public_html/sites/default/files

8️⃣ Elimina la cartella temporanea (non serve più)

cd ..
rm -rf drupal11tmp

9️⃣ Sistema composer.lock

Entra in public_html/ e aggiorna il lock file per sicurezza:

cd ~/domains/tuodominio.it/public_html
composer update --lock

🔟 Installa Drupal dal browser

Apri il tuo dominio:

https://tuodominio.it

Segui la procedura guidata di installazione di Drupal. Inserisci i dati del database, configura il sito e il gioco è fatto!

⚠️ Problema comune dopo l'installazione: interfaccia admin "monca"

Su alcuni hosting condivisi, dopo l'installazione potrebbe capitare che:

• la toolbar di amministrazione sia ridotta o incompleta
• mancano voci di menu
• l'interfaccia sembri "tagliata" o non funzioni correttamente

Causa: un file .htaccess generato da Drupal in sites/default/files/ che usa direttive Apache (Options) non sempre permesse sugli hosting condivisi. Apache non dà errore 500, ma impedisce a Drupal di funzionare correttamente.

✅ Soluzione

Apri il file:

public_html/sites/default/files/.htaccess

Trova questa riga:

Options -Indexes -ExecCGI -Includes -MultiViews

Commentala così (basta mettere il cancelletto all'inizio):

#Options -Indexes -ExecCGI -Includes -MultiViews

Salva il file e ricostruisci la cache di Drupal:

cd ~/domains/tuodominio.it/public_html
php core/scripts/drupal cache:rebuild

Oppure vai su /admin/config/development/performance e clicca "Svuota tutte le cache".

L'interfaccia tornerà immediatamente normale.

🚫 Perché evitare gli installer automatici (tipo "installazione in 1 click")

❌ I problemi delle installazioni automatiche

• Nessuna gestione delle dipendenze: Drupal oggi è fatto di decine di librerie PHP (Symfony, Guzzle, Twig...). Un installer automatico te le dà "impacchettate" alla meglio, senza un vero sistema di aggiornamento.
• Il file composer.lock non esiste o è incompleto: Questo è il punto fondamentale. composer.lock è il file che congela esattamente la versione di OGNI singola libreria e modulo installato. Senza di esso, non sai mai cosa c'è realmente nel tuo sito.
• Nessuna mappatura delle versioni: Con Composer, ogni pacchetto ha una versione precisa (es. symfony/http-foundation: v6.4.0). Con un installer automatico, hai una "zuppa" di file senza un vero controllo di versione.
• Aggiornamenti un disastro: Prova ad aggiornare Drupal installato con un installer automatico. Molto probabilmente si rompe tutto perché mancano le informazioni su quali versioni esatte delle dipendenze erano presenti.
• Non puoi aggiungere moduli via Composer: Il comando composer require drupal/nome_modulo è il modo standard per aggiungere moduli. Con un installer automatico, o non funziona o crea conflitti.
• Struttura fragile: Questi installer spesso modificano i percorsi, spostano file, creano configurazioni anomale. Funzionano "oggi", ma domani? Nessuna garanzia.

📊 Il cuore del problema: composer.lock e la mappatura delle dipendenze

Quando installi Drupal con Composer, vengono generati DUE file fondamentali:

composer.json   → cosa vuoi (es. "drupal/core": "^11")
composer.lock   → cosa hai ESATTAMENTE (es. "drupal/core": "11.0.3", 
                   "symfony/http-foundation": "6.4.0",
                   "twig/twig": "3.8.0", ...)

composer.lock è un file che elenca OGNI singolo pacchetto con la sua versione precisa, il suo hash di integrità, le sue dipendenze e sottodipendenze. È come la "mappa catastale" del tuo progetto. Senza di essa, stai navigando alla cieca.

Con un installer automatico, tipicamente:

• ❌ composer.lock è assente
• ❌ Oppure è un file falso, generato a mano
• ❌ La cartella vendor/ è un ammasso di file senza tracciabilità
• ❌ Non sai quali versioni di Symfony, Twig, Guzzle ecc. stai usando

🎯 Cosa fare se hai già usato un installer automatico?

Se hai già installato Drupal con un "1-click installer", hai due opzioni:

1. Butta via tutto e reinstalla con questa guida (soluzione consigliata, ci metti 15 minuti e hai un sito professionale, aggiornabile e sicuro).
2. Converti manualmente (procedura complessa: devi ricostruire composer.json, generare un vero composer.lock, riorganizzare le cartelle... sconsigliato).

Il mio consiglio: esporta i contenuti (se ne hai già creati), cancella l'installazione automatica e segui questa guida da zero. Ne guadagni in sanità mentale, sicurezza e futuro.

🎯 Conclusione

🖱️ Consiglio: i comandi sono copiabili con un click sul pulsante "Copia" in ogni riquadro grigio.
Guida basata sull'esperienza reale di installazione su hosting condiviso del Provider Host.it