Installazione e configurazione di Statamic in ambiente ServBay

Statamic è un moderno sistema di gestione dei contenuti (CMS) basato sul framework Laravel, rinomato per la sua flessibilità e le sue potenti funzionalità, ideale per costruire ogni tipo di sito web. Una caratteristica distintiva di Statamic è l'utilizzo, di default, del filesystem per archiviare contenuti e configurazioni, pur offrendo anche l'opzione database.

In questo articolo troverai una guida dettagliata su come installare e configurare Statamic tramite Composer nell'ambiente di sviluppo web completo ServBay. ServBay fornisce tutto il necessario per Statamic: ambiente PHP, supporto Composer e gestione intuitiva dei siti web.

Passaggi per installare Statamic

L'installazione di Statamic nell'ambiente ServBay è diretta ed efficiente. Segui questi passi:

Step 1: Crea la directory del progetto

Per prima cosa, crea una sottocartella dedicata a Statamic all'interno della directory root dei siti ServBay, /Applications/ServBay/www. Apri il terminale ed esegui:

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

Questo comando ti porterà nella cartella root dei siti ServBay, creerà una nuova cartella chiamata servbay-statamic-app e vi accederà.

2: Crea il progetto Statamic con Composer

ServBay viene fornito con Composer già preinstallato, lo strumento per la gestione delle dipendenze PHP. Puoi quindi usarlo direttamente per creare il progetto Statamic senza ulteriori installazioni.

All'interno della cartella servbay-statamic-app appena creata, esegui il seguente comando Composer:

composer create-project statamic/statamic .

Questo comando farà sì che Composer scarichi l’ultima versione di Statamic insieme a tutte le sue dipendenze, installandole nella cartella corrente (.). Attendi il completamento del download e dell’installazione.

Step 3: Configura il Web Server (aggiungi un sito in ServBay)

Affinché ServBay possa ospitare il tuo progetto Statamic, è necessario aggiungere una nuova configurazione sito nell'app ServBay.

1. Apri l'applicazione ServBay: Avvia l’app desktop di ServBay.

2. Vai alla scheda "Siti": Nella schermata ServBay, clicca sulla scheda "Siti" in alto (nota: nelle versioni precedenti potrebbe essere denominata "Host").

3. Aggiungi un nuovo sito: Clicca sul pulsante "+" in basso a sinistra per aggiungere una nuova configurazione sito.

4. Compila le informazioni del sito: Nella finestra di configurazione che appare, inserisci:

   • Nome: Un nome facilmente riconoscibile, ad esempio My Statamic Site.
   • Dominio: Il dominio locale con cui desideri accedere al sito; si consiglia di usare il suffisso .local (es: servbay-statamic.local). ServBay configurerà automaticamente la risoluzione DNS locale.
   • Tipo di sito: Seleziona PHP.
   • Versione di PHP: Scegli la versione PHP compatibile con il tuo Statamic (solitamente è raccomandata una versione stabile recente).
   • Directory root sito: Passaggio fondamentale. Il file di ingresso di Statamic, index.php, si trova nella sottocartella public del progetto. Quindi la root del sito deve essere: /Applications/ServBay/www/servbay-statamic-app/public.

5. Salva e applica la configurazione: Dopo aver compilato tutti i dati, clicca su "Salva”. Potrebbe comparire un messaggio che ti invita a riavviare i servizi per applicare la nuova configurazione. Segui le indicazioni, così il web server di ServBay (Caddy o Nginx di default) caricherà la configurazione aggiornata del tuo sito.

Step 4: Configura l’ambiente Statamic

Alla radice del progetto, Statamic fa uso del file .env per la gestione delle configurazioni d’ambiente (come chiavi applicative, connessione al database, ecc.).

1. Copia il file ambiente: Nel progetto Statamic troverai un file .env.example come modello. Dal terminale, assicurati di essere nella directory di progetto /Applications/ServBay/www/servbay-statamic-app, quindi esegui:

   cp .env.example .env

2. Genera la chiave applicativa: Laravel/Statamic richiede una chiave unica per la sicurezza (criptazione delle sessioni e dati sensibili). Dal root del progetto, genera la chiave con Artisan:

   php artisan key:generate

   Questo comando aggiornerà automaticamente il valore di APP_KEY nel file .env.

Step 5: Esegui Statamic e accedi al sito

A questo punto il tuo sito Statamic dovrebbe essere correttamente configurato ed in esecuzione tramite ServBay.

1. Accedi al sito Statamic: Apri il browser web e digita il dominio impostato nello step 3, ad esempio https://servbay-statamic.local. ServBay, di default, configurerà automaticamente il certificato SSL locale (tramite ServBay User CA o ServBay Public CA), permettendoti così di accedere via HTTPS. Dovresti visualizzare la pagina di benvenuto di Statamic.

2. Accedi al pannello di controllo: Il pannello amministrativo di Statamic è raggiungibile tramite il percorso /cp. Dal browser, visita https://servbay-statamic.local/cp. Comparirà la schermata di login o configurazione del pannello di controllo.

3. Crea un account amministratore: Al primo accesso al pannello, ti verrà richiesto di creare un account amministratore. Inserisci username, password e indirizzo email richiesti, quindi clicca su “Crea account”. Terminato questo passaggio, potrai accedere e gestire il tuo sito Statamic.

Step 6: Installa plugin e temi (opzionale)

Statamic offre un ricco ecosistema di plugin e temi che ti permettono di estendere le funzionalità e personalizzare l'aspetto del sito.

1. Installa plugin: Dopo aver effettuato l’accesso al pannello, puoi installare plugin tramite l’interfaccia (solitamente nella barra laterale sinistra) oppure con Composer da terminale. L’installazione tramite pannello è spesso più intuitiva.
2. Installa temi: Allo stesso modo, puoi aggiungere temi dal pannello di controllo o posizionando i file tema nelle apposite directory.

Creare un sito con Statamic

Una volta completata l'installazione e configurazione, puoi iniziare a sfruttare tutte le potenzialità di Statamic per costruire il tuo sito. Ecco alcune istruzioni di base:

Creazione di contenuti e collection

Statamic utilizza le “Collection” (Collezioni) per organizzare i contenuti, in modo simile alle tipologie di post e pagine dei CMS tradizionali.

1. Crea una Collection: Dal pannello di controllo Statamic, vai su “Contenuto” > “Collection” e clicca su “Crea collection”. Assegna un nome (ad esempio Posts, Pages) e configura eventuali altre impostazioni (routing, blueprint dei campi, ecc).
2. Crea un contenuto: All’interno della collection, clicca su “Nuovo” per aggiungere una nuova voce (es. articolo o pagina). Compila i campi in base al blueprint definito per la collection.

Configura il menu di navigazione

Puoi creare e gestire facilmente il menu principale del tuo sito.

1. Crea una navigazione: Nel pannello Statamic, vai su “Contenuto” > “Navigazione” e clicca su “Crea navigazione”. Dai un nome, ad esempio “Navigazione Principale”.
2. Aggiungi voci di menu: Trascina nel menu i contenuti (provenienti da collection o pagine singole) creando la gerarchia desiderata.

Personalizza template e stili

Statamic sfrutta Laravel, quindi puoi utilizzare il motore di template Blade per controllare il layout e la resa dei contenuti.

1. Modifica i template: I file delle viste si trovano di solito nella directory resources/views del progetto. Puoi modificare o creare file Blade (.blade.php) personalizzando la struttura HTML della pagina, secondo la convenzione di Statamic (sottocartelle layouts, partials, collections, ecc). Ad esempio, modifica il layout generale in resources/views/layouts/default.blade.php:

   <!-- resources/views/layouts/default.blade.php -->
   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>{{ $title ?? 'My Statamic Site' }}</title>
       {{-- Collegamento al CSS compilato --}}
       <link rel="stylesheet" href="{{ mix('css/app.css') }}">
   </head>
   <body>
       <header>
           {{-- Esempio: renderizza la navigazione chiamata 'main_navigation' --}}
           @inject('nav', 'Statamic\View\ViewServiceProvider')
           @if ($main_navigation = $nav->navigation('main_navigation'))
               <nav>
                   <ul>
                       @foreach ($main_navigation->tree() as $item)
                           <li><a href="{{ $item->url() }}">{{ $item->title() }}</a></li>
                       @endforeach
                   </ul>
               </nav>
           @endif
       </header>
       <main>
           {{-- Renderizza il contenuto della pagina corrente --}}
           @yield('content')
       </main>
       {{-- Collegamento al JavaScript compilato --}}
       <script src="{{ mix('js/app.js') }}"></script>
   </body>
   </html>

2. Aggiungi stili e script: I progetti Statamic integrano solitamente Laravel Mix o Vite come strumenti per la compilazione frontend. I file sorgente CSS e JavaScript si trovano di solito in resources/css e resources/js.

   Ad esempio, scrivi i tuoi stili CSS in resources/css/app.css:

   /* resources/css/app.css */
   body {
       font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
       line-height: 1.6;
       color: #333;
       margin: 0;
       padding: 20px;
   }
   nav ul {
       list-style: none;
       padding: 0;
   }
   nav ul li {
       display: inline;
       margin-right: 15px;
   }

   E codifica il tuo JavaScript in resources/js/app.js:

   // resources/js/app.js
   console.log('Asset frontend di Statamic caricati!');
   
   // Esempio: semplice interazione
   document.addEventListener('DOMContentLoaded', function() {
       const navItems = document.querySelectorAll('nav li a');
       navItems.forEach(item => {
           item.addEventListener('mouseover', () => {
               console.log(`Hover su: ${item.textContent}`);
           });
       });
   });

3. Compila le risorse frontend: Per trasformare i file sorgente in CSS e JS utilizzabili dal browser, esegui i comandi di build. Il progetto Statamic include un file package.json, quindi puoi installare le dipendenze frontend e lanciare la compilazione con npm o yarn. ServBay supporta Node.js, puoi quindi eseguire:

   npm install
   npm run dev

   npm install installerà tutte le dipendenze (Laravel Mix/Vite, Tailwind CSS, Vue/React ecc.) dalla descrizione in package.json. npm run dev effettuerà la compilazione in modalità sviluppo, generando asset non compressi e spesso source map per il debugging. In produzione, usa invece npm run prod o npm run build.

Conclusioni

Seguendo questi passaggi, hai installato e configurato con successo Statamic CMS nel potente ambiente locale ServBay. L’integrazione che ServBay offre (PHP, Composer, web server, gestione progetti e supporto Node.js) semplifica enormemente il ciclo di sviluppo locale di Statamic. Ora puoi sfruttare la struttura file flessibile e le ricche funzionalità di Statamic per creare e iterare rapidamente i tuoi progetti web.