Installazione e Configurazione di OctoberCMS nell'Ambiente ServBay

Panoramica

OctoberCMS è un sistema di gestione dei contenuti (CMS) open source costruito sul potente framework Laravel, apprezzato per la sua semplicità, flessibilità e approccio orientato agli sviluppatori. Questo documento ti guida passo dopo passo nell'installazione e configurazione di OctoberCMS in ServBay, un ambiente locale tutto-in-uno per lo sviluppo web su macOS, così che tu possa iniziare rapidamente lo sviluppo dei tuoi progetti con OctoberCMS.

Che cos’è OctoberCMS?

OctoberCMS offre un pannello di amministrazione intuitivo e una potente capacità di sviluppo frontend, consentendo agli sviluppatori di creare ogni tipo di sito – dal blog semplice ad applicazioni aziendali più complesse – utilizzando concetti Laravel familiari come Eloquent ORM e il motore di template Blade.

Prerequisiti

Prima di iniziare l’installazione di OctoberCMS, assicurati di avere quanto segue:

1. ServBay installato e in esecuzione sul tuo macOS.
2. I pacchetti PHP (consigliato 7.4 o superiore) e MySQL/MariaDB attivati e funzionanti in ServBay.
3. Il pacchetto Composer abilitato in ServBay.
4. Conoscenza di base dei comandi da terminale.

Guida Passo-Passo all’Installazione di OctoberCMS

Ecco i passaggi dettagliati per installare e configurare OctoberCMS nell’ambiente ServBay:

Passo 1: Crea la Cartella del Progetto

Per prima cosa, spostati nella directory radice consigliata da ServBay per i siti web, /Applications/ServBay/www, e crea una nuova cartella per il tuo progetto OctoberCMS.

cd /Applications/ServBay/www
mkdir servbay-octobercms-app
cd servbay-octobercms-app

Passo 2: Installa OctoberCMS con Composer

Composer è già incluso e configurato in ServBay. Assicurati che Composer sia abilitato nel pannello di controllo ServBay. Ora, all'interno della directory appena creata, esegui il comando Composer per scaricare e installare i file core di OctoberCMS:

composer create-project october/october .

Questo comando scaricherà l’ultima versione di OctoberCMS dalla repository ufficiale direttamente nella directory corrente (.).

Passo 3: Crea Database e Utente

OctoberCMS richiede un database per archiviare contenuti, utenti, configurazioni, ecc. Useremo lo strumento phpMyAdmin fornito da ServBay per creare database e utente.

1. Accedi a phpMyAdmin di ServBay

   Apri il browser e vai al pannello di sviluppo locale di ServBay: https://servbay.host/. Clicca o vai al link phpMyAdmin, in genere https://servbay.host/phpmyadmin/, per entrare nell'interfaccia di gestione dei database.

2. Crea nuovo utente database

   È buona prassi assegnare ad ogni applicazione un proprio utente e database dedicato, per motivi di sicurezza e isolamento.

   1. Entra nella pagina degli utenti

      Nel menu principale di phpMyAdmin, clicca sulla scheda “Account utente”.

   2. Aggiungi nuovo utente

      Clicca “Aggiungi account utente” e compila quanto segue:

      • Nome utente: inserisci il nome utente per la connessione del database OctoberCMS, ad esempio october_user.
      • Host: seleziona localhost o 127.0.0.1, così l’utente potrà collegarsi solo localmente (più sicuro).
      • Password: scegli una password sicura e unica. Non usare la password di esempio password123 in ambienti di produzione.
      • Conferma password: reinserisci la password.
      • Nella sezione “Crea database per l'utente”, scegli l’opzione “Crea un database con lo stesso nome e garantisci tutti i privilegi”.
      • Verifica che sia selezionata l’opzione “Garantisci tutti i privilegi” (se hai scelto la creazione automatica, normalmente questa impostazione viene applicata in automatico).
      • Premi “Esegui” in fondo alla pagina per completare la creazione di utente e database.

Passo 4: Configura il Server Web (Aggiungi il Sito in ServBay)

Per rendere accessibile la tua applicazione OctoberCMS via browser, devi configurare un sito locale in ServBay.

1. Aggiungi nuovo sito

   Apri il pannello ServBay e clicca sulla voce “Siti” nella barra laterale (Nota: su versioni precedenti potrebbe chiamarsi “Host”). Fai clic su “Aggiungi sito”.

   Compila i campi nel modo seguente:

   • Nome: assegna al sito un nome facilmente identificabile, ad esempio My OctoberCMS Site.
   • Dominio: scegli il dominio locale che desideri, ad esempio servbay-octobercms.local. Utilizza sempre un suffisso .local per evitare conflitti con domini reali.
   • Tipo di sito: seleziona PHP.
   • Versione PHP: scegli la versione PHP desiderata, assicurandoti che sia compatibile e attiva in ServBay.
   • Root del sito: seleziona la cartella del progetto creata al Passo 1, /Applications/ServBay/www/servbay-octobercms-app.

2. Salva la configurazione e riavvia ServBay

   Dopo aver completato le impostazioni, salva. ServBay ti chiederà di applicare le modifiche: sarà solitamente necessario riavviare alcuni pacchetti (ad esempio Caddy o Nginx) e ServBay stesso. Segui le istruzioni per applicare i cambiamenti. ServBay provvederà ad associare servbay-octobercms.local all’indirizzo locale (127.0.0.1).

Passo 5: Configura le Variabili d’Ambiente di OctoberCMS

OctoberCMS, basato su Laravel, utilizza il file .env per gestire le variabili d’ambiente dell’applicazione, come la connessione al database e le chiavi di sicurezza.

1. Copia il file di esempio delle variabili ambiente

   Dalla radice del progetto OctoberCMS (/Applications/ServBay/www/servbay-octobercms-app), copia il file .env.example e rinominalo in .env:

   cd /Applications/ServBay/www/servbay-octobercms-app
   cp .env.example .env

2. Modifica il file .env

   Apri il file .env con un editor di testo a tua scelta, cerca i parametri relativi al database e aggiorna i dati in base alle credenziali create al Passo 3:

   # ... altre impostazioni ...
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=october_user  # Sostituisci con il nome del database creato
   DB_USERNAME=october_user  # Sostituisci con il nome utente creato
   DB_PASSWORD=password123   # Sostituisci con la password impostata
   
   # ... altre impostazioni ...

   Importante: Assicurati di sostituire DB_DATABASE, DB_USERNAME e DB_PASSWORD con i valori reali usati al Passo 3.

Passo 6: Avvia l’Installazione Web di OctoberCMS

OctoberCMS include una procedura guidata via web per completare la configurazione finale, incluse le migrazioni del database e la creazione dell’account amministratore.

1. Accedi alla pagina di installazione

   Apri il browser, vai al dominio locale configurato al Passo 4, aggiungendo /install.php. Ad esempio:

   https://servbay-octobercms.local/install.php

   Dovresti visualizzare la pagina di setup guidato di OctoberCMS.

2. Inserisci i dati del database

   Il wizard chiederà le credenziali del database: inserisci le stesse presenti nel file .env:

   • Tipo database: MySQL
   • Host database: localhost oppure 127.0.0.1
   • Nome database: october_user
   • Username database: october_user
   • Password database: password123

   (Ricorda di usare la password che hai realmente impostato!)

3. Crea l’account amministratore

   Segui le istruzioni per inserire i dati dell’account amministratore che userai per accedere al backend: username, password, email etc.

4. Completa l’installazione

   Clicca su “Installa” o il relativo pulsante nella schermata. La procedura completerà le migrazioni e genererà la chiave dell’applicazione. Attendi il termine del processo.

Passo 7: Installazione di Plugin e Temi (Facoltativo)

Una volta completata l’installazione, puoi accedere al pannello amministrativo di OctoberCMS (https://servbay-octobercms.local/backend).

1. Installa i plugin

   Dal backend, naviga su “Sistema” -> “Aggiornamenti” -> “Plugin”. Da qui puoi cercare e installare plugin dal Marketplace ufficiale di OctoberCMS per estendere le funzionalità del sito.

2. Installa i temi

   Vai su “Sistema” -> “Aggiornamenti” -> “Temi” per scoprire e installare temi compatibili con il tuo progetto.

Configurazione e utilizzo base post installazione

Dopo una installazione di successo, sei pronto per costruire il tuo sito web. Ecco alcune azioni iniziali comuni:

• Visita frontend: accedi al dominio scelto, ad esempio https://servbay-octobercms.local/, per vedere la homepage (di solito con il tema predefinito).
• Visita backend: vai su https://servbay-octobercms.local/backend e accedi con le credenziali dell’utente amministratore creato.
• Crea pagine: dal backend, naviga su “CMS” -> “Pagine” per iniziare a creare o modificare le pagine del sito.
• Crea blocchi di contenuto: vai su “CMS” -> “Contenuti” per creare snippet di testo o blocchi riutilizzabili.
• Gestisci il tema: sotto “CMS” -> “Temi” puoi configurare le impostazioni del tema, layout e sezioni.
• Utenti e permessi: nella sezione “Sistema” -> “Gestione”, puoi amministrare gli utenti del backend e i relativi privilegi.

Domande Frequenti (FAQ)

• Domanda: Visualizzo la pagina predefinita di ServBay o un errore su servbay-octobercms.local?
  • Risposta: Controlla nel pannello di controllo ServBay che il sito servbay-octobercms.local sia stato aggiunto correttamente e che la root sia impostata su /Applications/ServBay/www/servbay-octobercms-app. Dopo ogni modifica, riavvia ServBay per applicare i cambiamenti. Verifica che Caddy/Nginx e PHP siano attivi.
• Domanda: Vedo una pagina bianca o un errore su https://servbay-octobercms.local/install.php?
  • Risposta: Questo solitamente indica un errore PHP. Controlla i log di errori di PHP dal pannello ServBay. Motivi comuni possono essere: permessi errati sulle cartelle (storage, themes, plugins e sottocartelle devono essere scrivibili dal web server), versione PHP non compatibile, estensioni mancanti ecc.
• Domanda: Errore di connessione al database durante l’installazione?
  • Risposta: Ricontrolla che le impostazioni del database (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD nel file .env) coincidano con le credenziali effettivamente create in phpMyAdmin. Assicurati che MySQL/MariaDB sia attivo in ServBay.
• Domanda: Fallimento del comando composer create-project?
  • Risposta: Verifica che Composer sia abilitato (così come il pacchetto PHP) nel pannello di ServBay e che la versione PHP sia corretta. Controlla la tua connessione internet: Composer scarica file online.

Conclusione

Con l’ambiente pratico offerto da ServBay, puoi installare e configurare rapidamente OctoberCMS su macOS. Seguendo questa guida, avrai una piattaforma di sviluppo locale potente e flessibile per il tuo prossimo progetto web. Ora non ti resta che esplorare le potenzialità di OctoberCMS e costruire siti web straordinari!