Installazione e Configurazione di Kirby CMS in Ambiente ServBay

Kirby è un sistema di gestione dei contenuti (CMS) file-based, flessibile e potente, ideale per costruire siti web di ogni tipo. A differenza dei CMS tradizionali basati su database, Kirby memorizza i contenuti nel filesystem, risultando leggerissimo, facile da versionare e semplice da distribuire.

Questa guida ti accompagna attraverso il processo di installazione e configurazione di Kirby 4.2 Starterkit in ServBay, un ambiente di sviluppo locale pensato per sviluppatori web. ServBay offre PHP preconfigurato, server web (come Caddy o Nginx) e Composer, rendendolo la piattaforma ideale per lo sviluppo locale con Kirby.

Prerequisiti

Prima di iniziare, assicurati di avere:

1. ServBay installato e attivo su macOS.
2. La versione richiesta di PHP abilitata in ServBay (in questo esempio, PHP 8.2).
3. Composer già fornito da ServBay, senza bisogno di installazioni aggiuntive.

Passaggi per Installare Kirby

Di seguito i passaggi dettagliati per installare e configurare Kirby nell'ambiente ServBay:

Passaggio 1: Creare la Cartella del Progetto

Per prima cosa, apri il terminale. Naviga nella cartella root predefinita dei siti web di ServBay, /Applications/ServBay/www, e crea una nuova directory di progetto. In questo esempio useremo servbay-kirby-app come nome del progetto.

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

Passaggio 2: Creare il Progetto Kirby con Composer

ServBay integra già Composer, quindi puoi utilizzarlo direttamente dal terminale. All'interno della directory servbay-kirby-app, esegui il seguente comando per scaricare e creare il progetto Starterkit di Kirby:

composer create-project getkirby/starterkit .

Questo comando scarica i file core di Kirby, le dipendenze e uno Starterkit con contenuti e template di esempio nella directory corrente (.).

Passaggio 3: Configurare il Server Web (Aggiungere il Sito in ServBay)

Per far sì che il server web di ServBay (Caddy o Nginx) serva il tuo progetto Kirby, dovrai aggiungere una nuova configurazione sito tramite l’app di ServBay.

1. Apri l’app ServBay: Avvia il programma ServBay.
2. Accedi alla gestione siti: Clicca su “Siti” nella barra di navigazione laterale di ServBay.
3. Aggiungi un nuovo sito: Premi il pulsante “+” in basso o seleziona l’opzione per aggiungere un sito.
4. Completa le informazioni del sito: Nella finestra di configurazione che compare, inserisci quanto segue:
   • Nome: Dai al sito un nome facile da riconoscere, ad esempio My Kirby Site.
   • Dominio: Scegli un dominio di sviluppo locale, consigliata l’estensione .local o .servbay.demo, tipo servbay-kirby.local. ServBay configurerà automaticamente il DNS locale.
   • Tipo sito: Seleziona PHP, dato che Kirby è un’applicazione PHP.
   • Versione PHP: Seleziona la versione PHP desiderata, ad esempio 8.2, assicurandoti che sia compatibile con i requisiti minimi di Kirby.
   • Directory root sito: Specifica la cartella dove si trova il file index.php di Kirby. Con lo Starterkit, di solito è la root stessa del progetto: /Applications/ServBay/www/servbay-kirby-app.
5. Salva la configurazione: Dopo aver verificato che tutto sia corretto, salva. ServBay applicherà la nuova configurazione e potrebbe riavviare i server web coinvolti.

Passaggio 4: Configurare Kirby (Impostazioni Iniziali)

La configurazione principale di Kirby avviene tramite il file site/config/config.php. Con lo Starterkit la configurazione di base è già a posto e puoi avviare subito il sito. Puoi però personalizzare varie impostazioni, come:

• Attivare la modalità debug (c::set('debug', true);)
• Configurare la lingua del pannello di amministrazione
• Definire i tuoi percorsi personalizzati ecc.

Nella root del progetto troverai la cartella content, già creata dallo Starterkit di Kirby, dove risiederanno i contenuti delle tue pagine.

Passaggio 5: Avviare e Visitare il Sito Kirby

Una volta configurato ServBay, il tuo sito Kirby sarà accessibile tramite il dominio scelto.

1. Assicurati che ServBay sia attivo: Controlla che l’app ServBay sia in esecuzione e che server web (Caddy o Nginx) e PHP siano avviati.
2. Apri il sito nel browser: Digita il dominio configurato nel passaggio 3, per esempio https://servbay-kirby.local, nella barra degli indirizzi del browser.

Dovresti visualizzare la pagina di benvenuto dello Starterkit di Kirby. ServBay abilita HTTPS di default, quindi ti consigliamo di accedere tramite https://.

Passaggio 6: Installazione e Utilizzo del Pannello Kirby (Opzionale)

Kirby offre un pannello di amministrazione avanzato per gestire contenuti, utenti e impostazioni del sito in modo visuale.

1. Visita la pagina di installazione del pannello: Vai su https://servbay-kirby.local/panel tramite browser.
2. Crea un account amministratore: Se è la prima volta che accedi a /panel, sarai guidato nella schermata di configurazione amministratore. Compila i dati richiesti (nome utente, password, email) per creare il primo amministratore.
3. Accedi al pannello: Dopo la creazione dell’account, puoi accedere al pannello di Kirby e iniziare a gestire i contenuti tramite interfaccia grafica.

Creare un Sito con Kirby

Ora che hai installato e configurato con successo Kirby in ServBay, puoi cominciare a costruire il tuo sito sfruttando la versatilità del CMS file-based. Ecco alcuni concetti di base utili nello sviluppo con Kirby:

Struttura dei Contenuti (Content)

I contenuti sono salvati nella cartella content. Ogni pagina corrisponde a una cartella dentro content. Le informazioni della pagina risiedono solitamente in file di testo (es. page.txt) nella rispettiva cartella, con sintassi simile al Markdown.

Esempio: creare la pagina "Chi siamo"

Nel terminale:

cd /Applications/ServBay/www/servbay-kirby-app
mkdir content/about
echo "Title: Chi siamo\n----\nQuesta è la pagina su di noi." > content/about/about.txt

Visita https://servbay-kirby.local/about (se previsto dal template).

Template

I file template si trovano in site/templates e definiscono come viene visualizzata una pagina. I nomi dei file coincidono spesso con il nome della cartella dei contenuti o con il blueprint usato (ad esempio, about.php per content/about o per una pagina con blueprint about).

Esempio: creare il template about.php

Nel file site/templates/about.php:

<?php snippet('header') ?>

<main>
  <h1><?= $page->title() ?></h1>
  <div class="text">
    <?= $page->text()->kt() // Renderizza con KirbyText ?>
  </div>
</main>

<?php snippet('footer') ?>

Qui si utilizza la funzione snippet() per includere parti riutilizzabili come header e footer.

Blueprint

I blueprint si trovano in site/blueprints e definiscono, in formato YAML, la struttura e i campi visualizzati nel pannello per ogni pagina.

Esempio: creare il blueprint about.yml

Nel file site/blueprints/pages/about.yml:

title: Pagina Chi siamo

columns:
  - width: 2/3
    fields:
      text:
        label: Contenuto testo
        type: textarea
        size: large
        buttons:
          - bold
          - italic
          - link
          - email

  - width: 1/3
    fields:
      # Campi della sidebar, ad esempio per il caricamento immagini
      cover_image:
        label: Immagine di copertina
        type: files
        max: 1
        uploads:
          template: image

Dopo aver definito il blueprint, nel pannello troverai questi campi creando una nuova pagina “Chi siamo”.

Snippet

Gli snippet sono file PHP riutilizzabili (ad esempio header, footer, navigazione) e risiedono in site/snippets.

Controller e Model

Per logiche più avanzate puoi usare i controller (site/controllers) per gestire i dati delle pagine, e i model (site/models) per definire classi personalizzate di pagina.

Risorse Statiche (Assets)

CSS, JavaScript, immagini e altri asset statici si trovano normalmente nella cartella assets alla root del progetto. Nei template puoi recuperare l’URL di queste risorse tramite la funzione helper url('assets/...').

Esempio: includere CSS e JS

In site/templates/default.php o site/snippets/header.php:

<link rel="stylesheet" href="<?= url('assets/css/style.css') ?>">
<script src="<?= url('assets/js/script.js') ?>"></script>

Conclusioni

Con questi passaggi hai installato e configurato con successo Kirby CMS nell’ambiente di sviluppo locale ServBay. Grazie all’ambiente integrato di ServBay, la gestione e il deploy di applicazioni PHP risulta molto più agevole, permettendoti di concentrarti su tutte le potenzialità e la flessibilità file-based offerte da Kirby per lo sviluppo web. Ora puoi approfondire concetti come template, blueprint e snippet di Kirby, per costruire strutture e funzionalità sempre più avanzate nei tuoi siti.