Installazione

WebBlocks CMS supporta un flusso di installazione come pacchetto consumer per applicazioni Laravel nuove, una procedura guidata di installazione via browser per installazioni nuove dal repository di manutenzione e un percorso di installazione manuale tramite la CLI di Laravel.

Per un'installazione nuova, iniziate portando il codice sorgente di WebBlocks CMS sulla vostra macchina. Eseguite Composer, create .env, usate Artisan e aprite la procedura guidata di installazione nel browser solo dopo che il codice sorgente è presente in locale.

Un'installazione è considerata completa quando l'applicazione dispone di una base funzionante del CMS:

• esiste una chiave applicativa
• il database è raggiungibile
• esistono le tabelle richieste
• esistono i dati di seed di base
• esiste il primo super_admin attivo
• un marcatore di completamento dell'installazione è memorizzato in system_settings

Prima di eseguire qualsiasi comando di installazione, assicuratevi che il repository di WebBlocks CMS sia presente in locale.

Clonare in una nuova cartella:

Clonare in una cartella vuota già creata:

Quando il codice sorgente è presente in locale, proseguite con uno dei percorsi di installazione nuova descritti di seguito.

Le installazioni di WebBlocks CMS sono soltanto consumatrici di aggiornamenti. Possono eseguire fetch o pull degli aggiornamenti del CMS, oppure scaricarli, ma non devono inviare commit o tag verso l'upstream canonico del CMS. Per i cloni di installazione locali esistenti, eseguite git remote set-url --push origin DISABLED una volta nella copia di lavoro dell'installazione.

Usate questo flusso quando WebBlocks CMS viene installato in un'applicazione Laravel nuova tramite Composer.

Opzioni supportate:

• --name= nome visualizzato del primo super admin
• --email= indirizzo e-mail del primo super admin
• --password= password del primo super admin
• --site-name= nome del sito predefinito
• --site-handle= handle del sito predefinito
• --repair-partial rinomina le tabelle CMS parziali vuote prima delle migrazioni di installazione nuova
• --force sovrascrive gli asset CMS di proprietà del pacchetto o i file di configurazione pubblicati quando serve

Che cosa fa webblocks:install:

• pubblica config/webblocks-cms.php quando l'applicazione ospite non lo ha già
• rimuove da routes/web.php la rotta welcome intatta di un Laravel nuovo quando è sicuro farlo, creando prima un backup con marca temporale, così le rotte pubbliche del CMS possono servire /
• applica una patch a app/Models/User.php con WebBlocks\Cms\Auth\Concerns\HasWebBlocksCmsAccess
• crea un backup con marca temporale prima di modificare User.php
• salta la patch quando il trait è già presente
• fallisce in modo chiaro se User.php non è una classe App\Models\User extends Authenticatable riconoscibile
• esegue il percorso di migrazione di installazione nuova del pacchetto per installazioni consumer pulite
• rileva schemi CMS parziali prima di eseguire le migrazioni di installazione nuova e segnala le tabelle CMS esistenti, i conteggi delle righe, le righe di migrazione correlate e i conflitti noti di chiavi esterne
• ripara gli schemi CMS parziali vuoti solo quando viene fornito --repair-partial, rinominando le tabelle CMS vuote con un suffisso _before_cms_install_... con marca temporale prima di proseguire
• rifiuta la riparazione automatica quando una tabella CMS parziale contiene righe
• evita di rieseguire quello schema nuovo quando le tabelle del CMS esistono già
• crea le tabelle di supporto di Laravel senza eseguire le migrazioni dell'applicazione ospite; attualmente copre i token di reimpostazione password del CMS e sessions, cache e cache_locks quando quei driver basati su database sono configurati
• non esegue il normale insieme di migrazioni Laravel dell'applicazione ospite come parte dell'installazione del pacchetto, evitando così conflitti con la tabella users compatibile con il CMS già creata
• prepara la root del disco filesystem backups usata da Backup / Restore
• installa gli asset CMS di proprietà del pacchetto in public/cms
• crea public/storage quando manca e l'ambiente lo consente
• esegue in modo idempotente il seed di lingue, siti, tipi di slot, page layouts, icone e tipi di blocco di base
• registra la versione installata e il marcatore di completamento dell'installazione in system_settings
• crea il primo super_admin attivo solo quando non ne esiste già uno

L'autenticazione del pacchetto è nativa di Laravel e non richiede Breeze, Jetstream, Laravel UI o Fortify. Dopo l'installazione, accedete da /webadmin/login quando le rotte di autenticazione del pacchetto CMS sono attive. Le viste di autenticazione di proprietà del CMS e i redirect per gli ospiti nell'amministrazione usano nomi di rotta del pacchetto come webblocks.auth.login e webblocks.auth.logout, così un prodotto ospite può mantenere la propria rotta globale login, per esempio /quiztem/login, senza sottrarre le azioni dei form del CMS o i redirect verso /webadmin.

Per l'attuale confine consumer del pacchetto v1.32.x, l'App\Models\User dell'applicazione ospite resta il modello di autenticazione e il bersaglio della patch al momento dell'installazione.

Se webblocks:install si arresta dopo un'esecuzione precedente fallita o interrotta, rieseguitelo prima senza riparazione e leggete la diagnostica dell'installazione parziale. Le tabelle CMS vuote possono essere spostate da parte in modo esplicito:

La modalità di riparazione rinomina soltanto le tabelle candidate vuote di proprietà del CMS. Non elimina tabelle, non altera automaticamente le tabelle non vuote e non presume che il CMS sia proprietario dell'applicazione ospite.

Usate la procedura guidata del browser per un'installazione nuova.

Quando il codice sorgente è presente in locale, iniziate con:

Poi aprite http://127.0.0.1:8000/install.

La procedura guidata copre:

• controlli di prontezza dell'ambiente
• configurazione del database e convalida della connessione
• installazione del nucleo del CMS
• creazione del primo super_admin
• blocco dell'installazione al completamento

Note:

• l'installer è pensato per installazioni nuove
• se la configurazione è incompleta, la procedura guidata può essere riaperta e ripresa in sicurezza
• al termine, le rotte di installazione vengono bloccate e subentra il normale flusso di autenticazione/amministrazione
• l'installer scrive la configurazione del database selezionata in .env

Usate il flusso da CLI quando preferite un percorso di configurazione Laravel standard per un'installazione nuova.

Note:

• php artisan db:seed installa i cataloghi di base del CMS e registra la versione attuale dell'applicazione come versione installata per un'installazione nuova
• php artisan storage:link è necessario se la distribuzione pubblica dei file deve usare storage/app/public
• le cartelle di runtime sotto storage/framework, storage/logs e bootstrap/cache vengono create automaticamente alla prima esecuzione
• Backup / Restore memorizza gli archivi sul disco filesystem backups, per impostazione predefinita storage/app/backups. L'utente del runtime PHP dovrebbe essere proprietario di quella cartella o condividere un gruppo di deployment con accesso in lettura/scrittura; evitate modalità 777 troppo ampie.

Per un progetto Laravel nuovo eseguito con PHP e Composer installati localmente:

Poi aprite:

• sito pubblico: /
• login amministrativo: /webadmin/login
• amministrazione: /webadmin

Quando il codice sorgente è presente in locale:

Note:

• lo sviluppo locale attendibile dovrebbe usare domini .test e HTTPS, con https://webblocks-cms.test come URL canonico di sviluppo del CMS
• php artisan serve resta utile per controlli rapidi solo da CLI, ma i flussi di lavoro attendibili nel browser dovrebbero usare la configurazione nativa Nginx/PHP-FPM documentata in docs/native-local-development.md
• le notifiche e-mail del modulo di contatto in locale dovrebbero usare un catcher SMTP locale o un account SMTP di prova attendibile; i valori SMTP locali abituali dipendono dallo strumento installato
• i destinatari delle notifiche di Contact Form si risolvono in questo ordine: recipient_email a livello di blocco, il destinatario di contatto predefinito del sito corrente, CONTACT_RECIPIENT_EMAIL e infine MAIL_FROM_ADDRESS come ultimo fallback sicuro
• gli invii di contatto vengono memorizzati indipendentemente dalla consegna della notifica, quindi una risposta pubblica Message sent conferma il successo dell'archiviazione anche se in seguito l'amministrazione mostra la notifica come Failed, Skipped o Not configured
• MAIL_MAILER=log, MAIL_MAILER=array e MAIL_MAILER=null non costituiscono una consegna in uscita reale e vengono mostrati come non configurati per la notifica di Contact Message
• i blocchi Contact Form renderizzano un wrapper nascosto .wb-form-check di proprietà del CMS con inert, aria-hidden="true", un campo form_check_{token} generato dal renderer, tabindex="-1" e autocomplete="off"; quando quel campo di controllo generato viene compilato, il server restituisce lo stesso redirect generico di successo e non memorizza alcun Contact Message né tenta la notifica
• gli invii che superano il campo di controllo generato possono comunque essere classificati come spam in base a segnali memorizzati conservativi, come linguaggio di contatto commerciale, densità di link, invii ripetuti dallo stesso IP o una proposta di vendita da posta gratuita con oggetto generico; questo stato è una classificazione amministrativa durevole ed è separato dallo stato della notifica e-mail
• quando la consegna della notifica fallisce, gli amministratori possono ispezionare il messaggio salvato in Admin -> Contact Messages per vedere lo stato di errore compatto nell'elenco e il dettaglio dell'errore memorizzato nella schermata di dettaglio del messaggio

Poi aprite:

• sito pubblico: https://webblocks-cms.test
• amministrazione: https://webblocks-cms.test/webadmin
• installer in un'installazione nuova: https://webblocks-cms.test/install

Completate l'installazione nuova nella procedura guidata del browser dopo aver eseguito quei passaggi di configurazione.

• le installazioni nuove reindirizzano automaticamente a /install
• potete anche aprire manualmente la procedura guidata su /install
• potete aprire /install/core per passare direttamente al passaggio di installazione del nucleo quando i requisiti precedenti sono già soddisfatti
• la procedura guidata può avanzare automaticamente tra i passaggi man mano che i requisiti vengono soddisfatti
• aprire / e /install in più schede del browser può mostrare passaggi diversi della procedura guidata; è previsto, perché l'installer tiene traccia dell'avanzamento e instrada di conseguenza

Il primo super_admin è necessario perché un'installazione sia completa.

• nella procedura guidata del browser, create il primo amministratore durante il passaggio finale di configurazione
• nel flusso da CLI come pacchetto consumer, fornite --name, --email e --password a webblocks:install
• in un'installazione manuale, assicuratevi che esista almeno un account super_admin attivo prima di considerare il CMS completamente installato

super_admin è il ruolo a livello di installazione che può accedere a Users, siti, lingue, impostazioni, aggiornamenti, backup, esportazione/importazione e a tutti i contenuti dei siti.

• l'installer viene bloccato al termine
• /webadmin è il punto di ingresso amministrativo canonico del CMS
• le installazioni come pacchetto consumer possono accedere tramite /webadmin/login; le app coinstallate possono mantenere il /login di proprietà dell'host
• /webadmin/dashboard reindirizza a /webadmin
• gli asset del CMS restano sotto /cms, per esempio /cms/css, /cms/js e /cms/brand
• il /webadmin/login di proprietà del pacchetto usa viste Blade del pacchetto, lo shell di autenticazione guest di WebBlocks UI, asset di WebBlocks UI fissati, /cms/css/guest.css e gli asset di marchio del prodotto CMS da /cms/brand, comprese le varianti di favicon e scheda del browser normale, per superficie scura, su colore d'accento/inversa e ad alto contrasto
• /cms è riservato agli asset pubblici statici di proprietà del CMS e non deve essere usato come prefisso, alias o redirect delle rotte amministrative del CMS
• /admin non è di proprietà del CMS e non deve essere ripristinato come rotta amministrativa del CMS
• le pagine nuove partono in draft
• se funzionalità a livello di installazione come revisioni, backup o aggiornamenti segnalano tabelle mancanti, eseguite php artisan migrate

La separazione tra /webadmin e /cms evita la collisione di try_files in Nginx in cui /cms/ può essere risolto come la cartella fisica di asset public/cms/ prima che Laravel gestisca una rotta. Non risolvete l'accesso amministrativo aggiungendo un passaggio public/cms/index.php; quel ponte di front controller deve restare assente dagli asset pubblici della root e del pacchetto.

Configurate la consegna della posta di Laravel prima di pubblicare una pagina di contatto pubblica. Una tipica configurazione SMTP in .env ha questo aspetto:

MAIL_* controlla la consegna della posta di Laravel per i tentativi di notifica di Contact Form. MAIL_FROM_ADDRESS è l'indirizzo mittente sicuro di fallback ed è anche l'ultimo destinatario sicuro di fallback di Contact Form quando non è configurato un destinatario più specifico. CONTACT_RECIPIENT_EMAIL è opzionale e funge da destinatario di fallback a livello di ambiente. Preferite configurare il destinatario di contatto a livello di sito in Site -> Edit -> Contact quando è disponibile, così l'instradamento dei contatti risiede con il sito e non solo in .env.

Dopo aver modificato le impostazioni di posta in .env in produzione o in un'installazione da pacchetto, svuotate la configurazione in cache se l'installazione usa la cache di configurazione:

Le notifiche di Contact Form risolvono i destinatari in questo ordine:

1. recipient_email del blocco Contact Form
2. destinatario di contatto predefinito del sito, da Site -> Edit -> Contact
3. CONTACT_RECIPIENT_EMAIL in .env
4. fallback sicuro MAIL_FROM_ADDRESS

Gli invii reali accettati di Contact Form vengono memorizzati prima di tentare la notifica e-mail. Un errore di notifica non significa che l'invio pubblico del modulo sia fallito. Gli amministratori dovrebbero controllare /webadmin/contact-messages per i messaggi memorizzati, lo stato della notifica e i dettagli sicuri dell'errore. I visitatori pubblici dovrebbero vedere solo il normale riscontro di successo o di convalida, non le diagnostiche di posta.

Sent significa che il CMS ha consegnato la notifica al trasporto di posta configurato senza eccezioni; non garantisce la consegna nella casella di posta. Skipped o Not configured significano che non è stato tentato alcun invio reale della notifica.

Usate il blocco nativo contact_form per le pagine di contatto. Non sostituitelo con Trusted HTML, con markup <form> grezzo o con fallback mailto:. Il renderer del CMS genera automaticamente il campo nascosto di controllo antispam; non createlo manualmente. Il vecchio campo honeypot website non è più il contratto pubblico.

Smoke test pratico di Contact Form:

1. Pubblicate o visualizzate in anteprima una pagina che contiene il blocco nativo contact_form.
2. Inviate un messaggio di prova con nome, e-mail, oggetto e messaggio.
3. Aprite /webadmin/contact-messages.
4. Verificate che il messaggio sia stato memorizzato.
5. Esaminate lo stato della notifica.
6. Se l'e-mail non è arrivata, ispezionate i dettagli sicuri dell'errore ed eseguite le diagnostiche di posta.

Comandi di diagnostica:

Il comando di diagnostica non deve stampare password, token o segreti di posta. Usate --block=ID per ispezionare la catena di fallback dei destinatari di un singolo blocco Contact Form. Usate --send-test= solo per un controllo di invio SMTP controllato verso un indirizzo di prova intenzionale.

1. Accedete a /webadmin.
2. Verificate la configurazione del vostro sito e delle lingue (locale).
3. Configurate l'identità del sito e i domini.
4. Configurate le impostazioni di posta di Laravel oppure le impostazioni di posta di sistema approvate.
5. Configurate un destinatario per il Contact Form, preferibilmente in Site -> Edit -> Contact.
6. Eseguite php artisan contact:mail-diagnose.
7. Inviate un Contact Form nativo di prova e verificate che venga salvato un Contact Message.
8. Controllate lo stato della notifica e-mail per quel messaggio di prova.
9. Create la vostra prima pagina.
10. Aggiungete media, navigazione e blocchi.
11. Pubblicate i contenuti attraverso il flusso di lavoro editoriale.