Installazione e Configurazione di Sculpin in ServBay

Panoramica

Sculpin è un potente e flessibile generatore di siti statici basato su PHP, particolarmente adatto per la creazione di blog, siti di documentazione o qualsiasi progetto che richieda la trasformazione di contenuti dinamici (come template Twig e file Markdown) in pagine HTML statiche ad alte prestazioni. Utilizza Composer per la gestione delle dipendenze e si basa sui componenti Symfony, offrendo agli sviluppatori un’esperienza nota e affidabile.

ServBay è un ambiente di sviluppo web locale progettato appositamente per macOS, che integra numerosi pacchetti essenziali come PHP, Composer, database (MySQL, PostgreSQL, MongoDB, Redis), server web (Caddy, Nginx) e una pratica interfaccia grafica per la gestione. Utilizzare ServBay semplifica enormemente la configurazione dell’ambiente di sviluppo Sculpin su macOS, soprattutto nella gestione delle versioni PHP, delle dipendenze e della configurazione dei server web.

Questa guida ti spiegherà in dettaglio come installare e configurare Sculpin in ambiente ServBay e impostare un sito locale di sviluppo.

Scenari d'Uso

• Creazione di blog statici ad alte prestazioni utilizzando stack PHP.
• Generazione di siti di documentazione statici per progetti open-source o prodotti.
• Costruzione rapida di landing page o siti aziendali statici senza necessità di database back-end.
• Scrittura dei contenuti tramite Markdown e template Twig, beneficiando di velocità e sicurezza di un sito statico.

Prerequisiti

Prima di iniziare, assicurati di avere:

1. ServBay installato e in esecuzione su macOS. ServBay fornisce l’ambiente PHP necessario, Composer e il server web (Caddy o Nginx).
2. Conoscenze basilari sull’uso della linea di comando.
3. Familiarità con i concetti base di PHP, Composer e Markdown.

Passaggi per Installare Sculpin

Ecco i dettagli passo-passo per installare e configurare Sculpin nell’ambiente ServBay:

Passo 1: Crea la Directory del Progetto

Innanzitutto, crea una nuova directory per il progetto nella root dei siti ServBay (/Applications/ServBay/www). Useremo servbay-sculpin-app come nome di esempio.

Apri il terminale ed esegui:

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

Questa cartella conterrà i tuoi file del progetto Sculpin.

Passo 2: Crea il Progetto Sculpin con Composer

ServBay include già Composer, quindi non è necessaria un’installazione aggiuntiva. Puoi usare direttamente il comando composer nel terminale.

Per partire velocemente, utilizziamo lo scheletro ufficiale per blog di Sculpin. Nel percorso servbay-sculpin-app appena creato, esegui il comando:

composer create-project sculpin/sculpin-blog-skeleton .

Questo comando scaricherà il template blog di Sculpin e tutte le sue dipendenze tramite Composer, installandole nella directory corrente (.).

Passo 3: Configura il Sito in ServBay

Per rendere accessibile il tuo sito Sculpin tramite il server web di ServBay (Caddy o Nginx), è necessario aggiungere una nuova configurazione sito.

1. Apri l’app di ServBay: avvia l’interfaccia grafica di ServBay.
2. Vai alla scheda “Siti”: nell’app ServBay, seleziona la tab “Siti” dalla barra di navigazione.
3. Aggiungi un nuovo sito: clicca sul pulsante “+” nell’angolo in basso a sinistra per aggiungere una nuova configurazione sito.
4. Inserisci le informazioni del sito:
   • Nome (Name): inserisci un nome facilmente riconoscibile, ad esempio My Sculpin Site.
   • Dominio (Domain): immetti il dominio per l’accesso locale, come servbay-sculpin.local. ServBay configurerà automaticamente la risoluzione locale e il certificato SSL per il dominio .local (utilizzando ServBay User CA).
   • Tipo Sito (Type): scegli PHP, poiché Sculpin è un’app PHP.
   • Versione PHP (PHP Version): seleziona la versione PHP desiderata. ServBay supporta versioni multiple: scegline una compatibile con Sculpin (solitamente una versione recente va bene).
   • Root sito (Document Root): passaggio cruciale! I file statici generati da Sculpin vengono salvati di default in output_dev (sviluppo) o output_prod (produzione) all’interno della directory di progetto. Per lo sviluppo locale, punta la document root a: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Salva la configurazione: dopo aver compilato tutto, clicca su “Salva”. ServBay applicherà la nuova configurazione al suo server web (Caddy o Nginx). Nella maggior parte dei casi, non serve riavviare ServBay manualmente.

Passo 4: Genera il Sito Sculpin

Dopo avere configurato il sito in ServBay, devi generare i file statici con Sculpin.

Nel terminale, assicurati di essere nella directory /Applications/ServBay/www/servbay-sculpin-app e installa le dipendenze del progetto (se già fatto al passo 2 puoi saltare, ma un’ulteriore esecuzione garantisce che tutto sia a posto):

composer install

Ora avvia la generazione del sito con:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: percorso all’eseguibile Sculpin installato tramite Composer.
• generate: comando di Sculpin per generare il sito statico. Legge contenuti e template dalla directory source e scrive i file statici nella cartella di output configurata (di default output_dev).
• --watch: opzione che fa sì che Sculpin monitori i cambiamenti nei file dentro source. Al variare dei file, Sculpin rigenera il sito in automatico: ottimo per lo sviluppo.

Quando appare il messaggio "Sculpin has generated your site!" o simile, i file statici saranno disponibili nella directory output_dev.

Passo 5: Visita il Tuo Sito Locale di Sviluppo

Ora puoi visitare il sito Sculpin dal dominio configurato in ServBay.

Apri il browser e vai al dominio scelto al passo 3:

https://servbay-sculpin.local

Dato che la document root punta a output_dev e il comando sculpin generate --watch monitora i cambiamenti, puoi vedere in tempo reale le modifiche effettuate su contenuti e template accedendo a https://servbay-sculpin.local. Il certificato SSL automatico di ServBay ti consente di visitare il sito locale via HTTPS in sicurezza.

Sviluppare con Sculpin

Dopo aver installato e configurato Sculpin in ServBay, puoi iniziare a creare il tuo sito statico. Ecco alcuni passaggi fondamentali:

Struttura Principale di un Progetto Sculpin

Conoscere la struttura base di un progetto Sculpin aiuta molto nello sviluppo:

servbay-sculpin-app/
├── app/                # Configurazione dell’applicazione e cache
├── output_dev/         # Directory di output dei file statici per lo sviluppo (root configurata su ServBay)
├── output_prod/        # Directory di output dei file statici per produzione
├── source/             # File sorgente del sito (contenuti Markdown, template Twig, risorse statiche, ecc.)
│   ├── _layouts/       # File layout Twig
│   ├── _posts/         # Articoli del blog in formato Markdown
│   ├── assets/         # Risorse statiche (CSS, JS, immagini, ecc.)
│   └── index.md        # File Markdown per la homepage
├── vendor/             # Dipendenze installate via Composer
├── sculpin.yml         # File principale di configurazione Sculpin
├── composer.json       # File di configurazione dipendenze Composer
└── ...altri file

La maggior parte del lavoro si svolge nella directory source.

Creare un Articolo sul Blog

Per pubblicare un nuovo articolo sul blog Sculpin, crea un file Markdown nella cartella source/_posts. Il nome file solitamente segue lo schema YYYY-MM-DD-slug.md.

Esempio: crea il file 2024-06-06-my-first-post.md:

---
title: "Il mio primo articolo"
date: 2024-06-06
tags: [Guida, Sculpin, ServBay]
---

# Il mio primo articolo

Questo è il contenuto del mio primo articolo su Sculpin. Qui condivido alcune esperienze d'uso tra ServBay e Sculpin.

Qui puoi scrivere contenuti utilizzando la sintassi Markdown.

## Sottotitolo

Lista:
- Elemento 1
- Elemento 2

Dopo aver salvato il file, dato che stai eseguendo il comando sculpin generate --watch, Sculpin rileverà automaticamente la modifica e rigenererà il sito. Ti basterà ricaricare la pagina su https://servbay-sculpin.local per vedere il nuovo post.

Creare una Nuova Pagina

Per aggiungere una pagina indipendente (ad esempio “Chi siamo”), crea semplicemente un file Markdown nella directory source, ad esempio about.md:

---
title: "Chi siamo"
layout: page.html.twig # Specifica il layout da utilizzare
---

# Guida Sculpin per ServBay

Questa pagina è una guida su come usare ServBay e Sculpin per creare siti statici.

Salvando il file, Sculpin genererà output_dev/about/index.html (se hai attivato le URL “belle”). Puoi visitare questa pagina tramite https://servbay-sculpin.local/about/.

Personalizzare Stili e Script

Le risorse statiche (come file CSS o JavaScript) sono tipicamente nella cartella source/assets. Puoi modificare direttamente questi file.

Ad esempio, modifica il file source/assets/css/style.css per cambiare lo stile del sito.

Queste risorse verranno copiate nella directory di output durante la generazione del sito. Qualsiasi modifica sarà rilevata dal comando Sculpin in modalità --watch e scatenerà una rigenerazione automatica.

Generare il Sito per la Produzione

Concluso lo sviluppo, puoi produrre una versione ottimizzata da pubblicare online. La build di produzione solitamente abilita ottimizzazioni come la compressione delle risorse.

Per generare la versione produzione, usa:

vendor/bin/sculpin generate --env=prod

I file risultanti andranno nella cartella output_prod. Ora puoi caricare i contenuti di output_prod su qualsiasi servizio di hosting per siti statici (ad es. GitHub Pages, Netlify, Vercel o sul tuo server).

Se vuoi visualizzare il risultato della build di produzione tramite ServBay, aggiorna la configurazione del sito modificando la "root" in /Applications/ServBay/www/servbay-sculpin-app/output_prod, salva e visita il dominio come di consueto.

Note Importanti

• Assicurati che ServBay sia in esecuzione e che il sito sia abilitato.
• Verifica che il comando sculpin generate --watch sia attivo nel terminale, così il sito si aggiorna automaticamente durante lo sviluppo.
• Controlla che la “root” configurata del sito in ServBay punti alla cartella di output corretta (output_dev durante lo sviluppo).
• ServBay genera in automatico certificati SSL per i domini .local, ma potrebbe essere necessario autorizzare la ServBay User CA nel sistema operativo. Consulta la documentazione di ServBay per i dettagli.

FAQ (Domande Frequenti)

D: Ho modificato un file ma il sito non si aggiorna?

R: Assicurati di aver eseguito nella cartella progetto il comando vendor/bin/sculpin generate --watch e che questo non si sia interrotto per errori. Controlla il terminale per eventuali messaggi di errore. Prova anche a svuotare la cache del browser o usa la modalità incognito.

D: Ricevo errori SSL su https://servbay-sculpin.local?

R: ServBay genera certificati autofirmati per i domini .local. Potresti dover autorizzare manualmente la ServBay User CA nel sistema operativo. Segui la guida ufficiale ServBay per installare e fidarti del certificato CA.

D: Come posso cambiare la versione PHP?

R: Vai nella scheda “Pacchetti” nell’app ServBay per installare e gestire versioni diverse di PHP. Poi, nella tab “Siti”, modifica la configurazione del sito Sculpin e seleziona la versione PHP desiderata, quindi salva.

D: Quali template engine e formati supporta Sculpin?

R: Sculpin utilizza Twig come motore di template predefinito e supporta estensivamente Markdown per la scrittura dei contenuti.

Conclusioni

Grazie all’ambiente integrato offerto da ServBay, installare e configurare Sculpin come generatore di siti statici su macOS è rapido e semplice. PHP e Composer preinstallati, la configurazione intuitiva del server web e la gestione SSL automatica rendono ServBay la piattaforma ideale per lo sviluppo locale con Sculpin. Segui questa guida per creare velocemente il tuo ambiente Sculpin e sviluppare, modificare e anteporre i tuoi progetti di siti statici in modo efficiente. Sfrutta la potenza di Sculpin unita alla comodità di ServBay per concentrarti sulla produzione di contenuti di qualità senza perdere tempo in configurazioni tecniche complesse dell’ambiente di sviluppo locale.