Installare e Configurare Jigsaw nell’Ambiente ServBay

Panoramica

Questo documento guida l’utente attraverso l’installazione e la configurazione di Jigsaw, generatore di siti statici, nell’ambiente locale avanzato ServBay. ServBay offre un setup integrato per PHP, Node.js e altri stack tecnologici, semplificando notevolmente l’avvio di progetti Jigsaw. Con ServBay puoi configurare facilmente domini locali, HTTPS, e server web performanti per il tuo sito Jigsaw, così puoi concentrarti unicamente sullo sviluppo dei contenuti.

Che cos’è Jigsaw?

Jigsaw è un generatore di siti statici sviluppato da Tighten, basato sui componenti di Laravel. Sfrutta la potenza e la flessibilità del motore di template Blade di Laravel, unendolo ai file Markdown per generare siti web statici in HTML puro. Jigsaw è ideale per siti di documentazione, blog, pagine promozionali o qualsiasi sito che non richieda database o elaborazione lato server. I suoi principali punti di forza sono:

• Uso di strumenti familiari: Se conosci Laravel o il template Blade, imparare Jigsaw sarà rapido e semplice.
• Prestazioni e sicurezza: I siti statici prodotti sono velocissimi da caricare e, non eseguendo codice server-side, sono molto più sicuri.
• Template flessibili: Grazie a Blade puoi creare layout e componenti complessi.
• Supporto Markdown: Scrivere i contenuti è semplice e intuitivo.

Casi d’Uso

Jigsaw si presta perfettamente a questi scenari:

• Siti di documentazione tecnica e API
• Blog personali o siti di divulgazione tecnica
• Landing page promozionali aziendali o di prodotto
• Siti vetrina di piccole dimensioni
• Qualsiasi sito con contenuti stabili dove sono fondamentali sicurezza e performance

Prerequisiti

Prima di iniziare, assicurati di avere questi requisiti:

1. ServBay installato e attivo: Devi aver installato e avviato ServBay su macOS. ServBay include già PHP, Composer e Node.js/npm, strumenti necessari per Jigsaw.
2. Conoscenze di base del terminale: Dovrai eseguire alcuni comandi via terminale.
3. Familiarità base con Composer e npm: L’installazione di Jigsaw avviene tramite Composer, mentre per gli asset frontend si utilizza npm.

Guida all’Installazione e Configurazione

Questa sezione descrive passo per passo come installare e configurare il progetto Jigsaw all’interno dell’ambiente ServBay.

Passo 1: Crea la Cartella del Progetto

Per prima cosa, apri il terminale e vai nella cartella consigliata da ServBay per i siti web: /Applications/ServBay/www. Qui andrai a creare la nuova directory per il tuo progetto Jigsaw.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

Abbiamo nominato la cartella servbay-jigsaw-demo: tutti i file del progetto andranno inseriti qui.

Passo 2: Crea un Progetto Jigsaw con Composer

ServBay viene fornito con Composer già installato e configurato: puoi quindi usare subito il comando composer in qualsiasi terminale. Ora, all'interno della cartella appena creata (/Applications/ServBay/www/servbay-jigsaw-demo), esegui questo comando per creare il progetto Jigsaw:

composer create-project tightenco/jigsaw .

Questo comando scarica l’ultima versione di Jigsaw e tutte le sue dipendenze PHP nella cartella corrente (.). Nota il punto alla fine: così i file verranno collocati direttamente nella directory attuale, senza creare una sottocartella aggiuntiva chiamata jigsaw.

Passo 3: Configura il Sito in ServBay

Per poter accedere al tuo sito Jigsaw dal browser, devi configurare un nuovo sito locale all'interno di ServBay.

1. Apri l’interfaccia di ServBay: Fai doppio clic sull’icona di ServBay o usala dall’icona nella barra del menu.
2. Vai nella sezione “Siti”: Nel menu a sinistra, clicca sul tab “Siti”.
3. Aggiungi un nuovo sito: Clicca sul pulsante “+” in basso e scegli “Aggiungi sito”.
4. Compila i dettagli:
   • Nome (Name): Scegli un nome descrittivo, ad esempio ServBay Jigsaw Demo.
   • Dominio (Domain): Inserisci il dominio da usare localmente. È consigliato il suffisso .servbay.demo per evitare conflitti con domini reali, ad esempio jigsaw-demo.servbay.demo. ServBay farà puntare automaticamente i domini .servbay.demo all’ambiente locale.
   • Tipo di sito (Site Type): Scegli PHP, perché la build di Jigsaw richiede PHP.
   • Versione PHP (PHP Version): Seleziona una versione PHP già installata su ServBay; consigliamo una versione stabile recente.
   • Radice sito (Site Root): Passo fondamentale: i file statici generati da Jigsaw vengono salvati di default nella cartella build_local presente nella radice del progetto. Quindi, imposta la radice del sito qui: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Salva e applica: Dopo aver compilato tutti i dati, clicca su “Salva”. ServBay ti chiederà conferma per applicare le modifiche. Conferma: ServBay aggiornerà automaticamente la configurazione del server web (Caddy o Nginx) e imposterà il protocollo HTTPS.

Passo 4: Installa le Dipendenze Frontend

Un progetto Jigsaw solitamente utilizza npm per gestire e compilare gli asset frontend (come SASS, CSS, JavaScript). In ServBay sia Node.js che npm sono già pronti all’uso.

All’interno della cartella del progetto (/Applications/ServBay/www/servbay-jigsaw-demo), esegui questo comando per installare tutte le dipendenze frontend:

npm install

Questo comando legge il file package.json nella radice del progetto e scarica tutti i moduli Node necessari nella cartella node_modules.

Passo 5: Compila il Sito Jigsaw

Dopo aver installato tutte le dipendenze, esegui il comando di build di Jigsaw per generare i file statici del sito.

Da dentro la cartella del progetto:

./vendor/bin/jigsaw build

Cosa fa questo comando:

1. Elabora i file Markdown e i template Blade presenti nella cartella source.
2. Esegue i task di compilazione definiti in webpack.mix.js (se presente Laravel Mix, dopo l’installazione npm).
3. Salva il risultato finale — HTML, CSS, JS e altri asset statici — nella cartella build_local.

Passo 6: Accedi al sito

A questo punto, i file statici sono stati generati nella cartella /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Dato che hai già fatto puntare la radice del sito ServBay qui, ora puoi visualizzare il sito tramite browser sul dominio configurato.

Apri il browser e vai all’indirizzo configurato al Passo 3, come ad esempio https://jigsaw-demo.servbay.demo. ServBay gestirà automaticamente il certificato HTTPS (tramite la User CA di ServBay) e ti mostrerà la pagina di benvenuto predefinita di Jigsaw.

Personalizzazione e Sviluppo

Ora che hai configurato l’ambiente di base, puoi personalizzare i contenuti e lo stile del tuo sito Jigsaw.

Modifica contenuti e template

• Il codice sorgente del sito si trova nella cartella source nella radice del progetto.
• I layout HTML e i componenti realizzati con Blade sono sotto source/_layouts e source/_partials e altre sottocartelle.
• I contenuti delle pagine sono generalmente file Markdown dentro source o nelle sue sottocartelle (es. source/index.md, source/about.md).
• Gli articoli del blog vanno usualmente in source/_posts, con formato file YYYY-MM-DD-slug.md.

Aggiungi una nuova pagina o articolo

Per aggiungere una nuova pagina o un nuovo post, basta creare un file Markdown dentro la cartella source o sotto-cartelle rilevanti, come source/_posts.

Ad esempio, per creare una pagina “Chi siamo”, crea source/about.md:

---
title: "Chi siamo"
description: "Scopri di più su ServBay Jigsaw Demo"
---

# Chi siamo

Questa è una pagina "About" creata con Jigsaw.

Qui puoi aggiungere la presentazione dell’azienda, il team e altre informazioni.

Personalizzare stile e script

I progetti Jigsaw usano solitamente Laravel Mix (webpack.mix.js) per la compilazione degli asset frontend.

• I fogli di stile (solitamente SASS/SCSS) sono sotto source/_assets/sass.
• I file JavaScript sono in source/_assets/js.

Dalla directory principale del progetto puoi utilizzare i seguenti comandi npm per compilare gli asset:

• npm run dev: compila gli asset in modalità sviluppo (con Source Map, senza compressione).
• npm run watch: compila in modalità sviluppo e ricompila automaticamente ad ogni modifica dei file, utilissimo in sviluppo.
• npm run prod: compila per la produzione, effettuando compressioni e ottimizzazioni.

Ad esempio, dopo aver modificato source/_assets/sass/main.scss, esegui npm run dev o npm run watch per generare il CSS corrispondente.

Ricompilare il sito

Nota importante: Ogni volta che modifichi i contenuti (Markdown) o i template (Blade) nella cartella source, devi eseguire nuovamente il comando di build di Jigsaw per aggiornare i file statici in build_local:

./vendor/bin/jigsaw build

Se invece modifichi gli asset frontend (SASS, JS), ricompila con npm run dev o npm run watch. In molti progetti Jigsaw, il comando jigsaw build può già includere la compilazione Mix, ma separare i task può aiutare nella fase di debug.

Note Importanti

• Cartella di output della build: Per impostazione predefinita Jigsaw crea la build in build_local (ambiente di sviluppo) e build_production (ambiente di produzione). Accertati che la radice del sito in ServBay punti alla cartella desiderata (in genere in sviluppo si punta a build_local).
• Server web: ServBay usa Caddy o Nginx, che espongono direttamente i file statici presenti in build_local, garantendo massima efficienza. Non serve avviare il server integrato di Jigsaw (jigsaw serve), pensato solo per anteprima rapida e meno potente rispetto ai server web completi di ServBay.
• HTTPS: ServBay configura automaticamente HTTPS per i domini .servbay.demo e rilascia i certificati tramite la ServBay User CA. Potrebbe essere necessario aggiungere la User CA tra i certificati attendibili del sistema per evitare avvisi del browser.
• Build pulita: Se riscontri strani problemi di compilazione, prova ad eseguire una build pulita con il comando ./vendor/bin/jigsaw build --clean.

Domande Frequenti (FAQ)

D: Ho modificato un file Markdown, ma non vedo i cambi nel browser. Cosa devo fare?

R: Dopo aver modificato i contenuti o i template, ricompila il sito con ./vendor/bin/jigsaw build dal terminale.

D: Ho cambiato file SCSS ma gli stili non sono aggiornati nel sito. Perché?

R: Dopo aver modificato asset frontend, esegui da terminale npm run dev o npm run watch nella cartella del progetto.

D: Quando provo ad accedere al dominio locale, vedo “Impossibile accedere” o “File non trovato”. Soluzioni?

R: Controlla questi punti:

1. ServBay è in esecuzione?
2. La configurazione del sito in ServBay è corretta? Dominio giusto? La root punta esattamente a /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Hai eseguito ./vendor/bin/jigsaw build e nella cartella build_local sono apparsi i file statici necessari (come index.html)?

D: Come si effettua il deploy di un sito Jigsaw?

R: Jigsaw produce solo file statici. Procedi così:

1. Esegui ./vendor/bin/jigsaw build production per generare la versione ottimizzata per la produzione.
2. Carica tutto il contenuto della cartella build_production su un qualsiasi hosting compatibile con siti statici (Netlify, Vercel, GitHub Pages, vari object storage cloud, ecc.).

Conclusioni

Con ServBay, installare e configurare Jigsaw come generatore di siti statici su macOS è rapido ed efficiente. ServBay fornisce tutto l’ambiente necessario (PHP, Composer, Node.js, npm) e potenti strumenti di configurazione web locali. Seguendo questa guida puoi avviare subito un nuovo progetto Jigsaw e sfruttare al meglio tutte le funzionalità di ServBay per ottimizzare il tuo ciclo di sviluppo locale.