Installer et configurer Sculpin dans l’environnement ServBay

Vue d’ensemble

Sculpin est un générateur de sites statiques puissant et flexible basé sur PHP. Il est particulièrement adapté à la création de blogs, de sites de documentation ou de tout projet nécessitant de transformer du contenu dynamique (comme des modèles Twig et des fichiers Markdown) en pages HTML statiques à haute performance. Il s’appuie sur Composer pour la gestion des dépendances et utilise les composants Symfony, offrant aux développeurs une expérience familière et fiable.

ServBay est un environnement de développement Web local spécifiquement conçu pour macOS, intégrant de nombreux outils essentiels notamment PHP, Composer, des bases de données (MySQL, PostgreSQL, MongoDB, Redis), ainsi que des serveurs Web (Caddy, Nginx), tout en proposant une interface graphique conviviale. ServBay simplifie grandement le processus de mise en place d’un environnement de développement Sculpin sur macOS, notamment pour la gestion des versions PHP, des dépendances et la configuration du serveur Web.

Ce guide vous accompagne pas à pas pour installer et configurer Sculpin sous ServBay, et mettre en place un site de développement local.

Cas d’utilisation

• Créer un blog statique performant avec la stack PHP.
• Générer des sites de documentation statique pour des projets open source ou des produits.
• Déployer rapidement des pages marketing statiques ou des sites vitrines n’ayant pas besoin de base de données back-end.
• Rédiger du contenu en Markdown avec le moteur de templates Twig et profiter de la rapidité et la sécurité du statique.

Prérequis

Avant de commencer, vérifiez que vous remplissez les conditions suivantes :

1. ServBay est installé et fonctionnel sur votre système macOS. ServBay inclut l’environnement PHP nécessaire, le gestionnaire de dépendances Composer, et un serveur Web (Caddy ou Nginx).
2. Vous savez utiliser le terminal en ligne de commande.
3. Vous connaissez les bases de PHP, Composer et Markdown.

Étapes pour installer Sculpin

Voici le guide complet pour installer et configurer Sculpin dans ServBay :

Étape 1 : Créer le dossier du projet

Commencez par créer un nouveau dossier projet dans le dossier racine des sites ServBay (/Applications/ServBay/www). Nous utiliserons servbay-sculpin-app comme nom d’exemple.

Ouvrez le terminal et saisissez les commandes suivantes :

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

Ce dossier accueillera les fichiers de votre projet Sculpin.

Étape 2 : Créer un projet Sculpin avec Composer

ServBay inclut déjà Composer par défaut, vous n’avez donc rien à installer de plus. Vous pouvez utiliser la commande composer directement dans le terminal.

Nous allons initialiser le projet via la structure de blog officielle de Sculpin pour démarrer rapidement. Placez-vous dans le dossier servbay-sculpin-app créé précédemment et exécutez :

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

Cette commande télécharge l’ossature du blog Sculpin et toutes ses dépendances via Composer, puis les installe dans le dossier courant (.).

Étape 3 : Configurer le site ServBay

Pour accéder à votre site Sculpin via le serveur Web de ServBay (Caddy ou Nginx), vous devez ajouter une nouvelle configuration de site dans ServBay.

1. Ouvrez l’application ServBay : Lancez l’interface graphique de ServBay.
2. Allez à l’onglet « Sites » : Cliquez sur l’onglet « Sites » dans la barre de navigation.
3. Ajoutez un nouveau site : Cliquez sur le bouton « + » en bas à gauche pour ajouter une configuration de site.
4. Complétez les informations du site :
   • Nom : Saisissez un nom facile à reconnaître, par exemple My Sculpin Site.
   • Domaine : Renseignez le domaine local souhaité, comme servbay-sculpin.local. ServBay configure automatiquement la résolution locale et un certificat SSL pour tout domaine en .local (via ServBay User CA).
   • Type de site : Choisissez PHP, car Sculpin fonctionne avec PHP.
   • Version de PHP : Sélectionnez la version PHP de votre choix. ServBay gère plusieurs versions de PHP ; optez pour une compatible avec Sculpin (une version récente suffit généralement).
   • Racine du site (Document Root) : Cette étape est cruciale. Les fichiers statiques générés par Sculpin se trouvent par défaut dans le sous-dossier output_dev ou output_prod du projet. Pour le développement local, réglez la racine du site sur le dossier de sortie de développement : /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Enregistrez la configuration : Cliquez sur « Sauvegarder » après avoir tout rempli. ServBay appliquera immédiatement la nouvelle configuration sur le serveur Web (Caddy ou Nginx). Généralement, il n’est pas nécessaire de redémarrer les services manuellement.

Étape 4 : Générer le site Sculpin

Une fois votre site configuré dans ServBay, il faut générer les fichiers statiques de votre site avec Sculpin.

Dans le terminal, assurez-vous d’être toujours dans le dossier racine du projet /Applications/ServBay/www/servbay-sculpin-app puis lancez la commande suivante pour installer les dépendances du projet (ce n’est pas forcément nécessaire si l’étape 2 a déjà été réalisée, mais l’exécuter garantit que tout est installé correctement) :

composer install

Ensuite, générez le site avec Sculpin :

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin : chemin vers l’exécutable Sculpin installé via Composer.
• generate : commande qui dit à Sculpin de générer le site statique à partir du contenu du dossier source et des templates, et de placer les fichiers dans le dossier de sortie (output_dev par défaut).
• --watch : ce flag permet à Sculpin de surveiller le dossier source. Si un fichier est modifié, Sculpin regénère automatiquement le site, ce qui est très pratique en développement.

Lorsque la commande affiche un message comme "Sculpin has generated your site!", les fichiers statiques sont disponibles dans output_dev.

Étape 5 : Accéder à votre site local

Vous pouvez désormais accéder à votre site Sculpin via le domaine local configuré dans ServBay.

Ouvrez votre navigateur web et visitez le domaine défini lors de l’étape 3 :

https://servbay-sculpin.local

Puisque la racine du site pointe sur output_dev et que la commande sculpin generate --watch surveille les changements, vous pouvez prévisualiser en temps réel toutes vos modifications sur https://servbay-sculpin.local. Le certificat SSL automatique fourni par ServBay vous garantit une navigation HTTPS sécurisée même en local.

Développer avec Sculpin

Vous avez maintenant installé et configuré Sculpin avec succès dans ServBay et pouvez commencer à construire votre site statique. Voici les actions de base pour le développement :

Structure d’un projet Sculpin

Comprendre l’organisation d’un projet Sculpin vous aidera à développer efficacement :

servbay-sculpin-app/
├── app/                # Configuration de l’application et cache
├── output_dev/         # Dossier de sortie des fichiers statiques pour le développement (la racine du site ServBay pointe ici)
├── output_prod/        # Dossier de sortie des fichiers statiques pour la production
├── source/             # Sources du site : contenu Markdown, templates Twig, ressources statiques, etc.
│   ├── _layouts/       # Modèles de mise en page Twig
│   ├── _posts/         # Articles du blog au format Markdown
│   ├── assets/         # Ressources statiques (CSS, JS, images, etc.)
│   └── index.md        # Page d’accueil en Markdown
├── vendor/             # Bibliothèques installées avec Composer
├── sculpin.yml         # Fichier de configuration principal de Sculpin
├── composer.json       # Configuration des dépendances Composer
└── ...autres fichiers

L’essentiel de votre travail se fait dans le dossier source.

Créer un article de blog

Pour ajouter un article dans votre blog Sculpin, il suffit de créer un nouveau fichier Markdown dans source/_posts. Le nom du fichier suit en général le format YYYY-MM-DD-slug.md.

Par exemple, créez le fichier 2024-06-06-my-first-post.md :

---
title: "Mon premier article"
date: 2024-06-06
tags: [Tutoriel, Sculpin, ServBay]
---

# Mon premier article

Voici le contenu de mon tout premier article de blog Sculpin, où je partage quelques astuces sur l’utilisation de ServBay et Sculpin.

Vous pouvez écrire du contenu ici en syntaxe Markdown.

## Sous-titre

Liste :
- Élément 1
- Élément 2

Après avoir sauvegardé le fichier, puisque la commande sculpin generate --watch est en cours d’exécution, Sculpin détectera le changement et mettra à jour le site automatiquement. Rafraîchissez la page sur https://servbay-sculpin.local pour voir votre nouvel article.

Créer une nouvelle page

Pour ajouter une page indépendante (par exemple « À propos »), créez directement un fichier Markdown dans le dossier source, par exemple about.md :

---
title: "À propos"
layout: page.html.twig # Spécifie le modèle de page à utiliser
---

# Guide Sculpin ServBay

Cette page présente le guide pour construire un site statique avec ServBay et Sculpin.

Une fois sauvegardée, cette page sera générée dans output_dev/about/index.html (si vous avez configuré des URLs jolies). Accédez-y via https://servbay-sculpin.local/about/.

Personnaliser les styles et scripts

Les ressources statiques, comme les fichiers CSS ou JavaScript, se placent dans source/assets. Modifiez-les directement pour ajuster le style de votre site.

Exemple : modifiez le fichier source/assets/css/style.css pour changer l’apparence du site.

Lors de la génération du site, ces ressources sont recopiées dans le dossier de sortie. Toute modification sera détectée par la commande Sculpin avec --watch qui relancera la génération du site.

Générer le site pour la production

Quand votre site est prêt pour la mise en ligne, construisez une version de production. Celle-ci sera optimisée, avec notamment compression des assets.

Utilisez la commande suivante :

vendor/bin/sculpin generate --env=prod

Les fichiers statiques seront générés dans le dossier output_prod. Vous pourrez alors les transférer vers n’importe quel hébergeur de sites statiques (GitHub Pages, Netlify, Vercel, ou votre propre serveur web).

Pour visualiser le résultat en local, changez l’option « Racine du site » dans la configuration ServBay vers /Applications/ServBay/www/servbay-sculpin-app/output_prod, enregistrez puis visitez le domaine configuré.

Points d’attention

• Vérifiez que ServBay est bien lancé et que votre site y est activé.
• Assurez-vous que la commande sculpin generate --watch tourne dans le terminal pour les mises à jour automatiques.
• La « racine du site » dans la configuration ServBay doit pointer sur le dossier de sortie de Sculpin (généralement output_dev en développement).
• ServBay génère automatiquement des certificats SSL pour les domaines .local, mais votre système d’exploitation doit faire confiance à la ServBay User CA. Reportez-vous à la documentation ServBay pour les instructions.

FAQ (Foire Aux Questions)

Q : J’ai modifié un fichier, mais le site ne se met pas à jour ?

R : Assurez-vous d’avoir lancé vendor/bin/sculpin generate --watch dans le dossier du projet et que la commande ne s’est pas arrêtée à cause d’une erreur. Vérifiez également les éventuels messages d’erreur dans le terminal. Pensez à vider le cache du navigateur ou à utiliser le mode de navigation privée.

Q : Je rencontre une erreur SSL en accédant à https://servbay-sculpin.local ?

R : ServBay génère un certificat auto-signé pour les domaines .local, que votre système doit approuver. Suivez le guide de la documentation ServBay pour installer et faire confiance au certificat CA.

Q : Comment changer de version PHP ?

R : Depuis l’onglet « Packages » de ServBay, installez et gérez différentes versions de PHP. Ensuite, modifiez la configuration du site correspondant dans l’onglet « Sites » en sélectionnant la version souhaitée et sauvegardez.

Q : Quels moteurs de templates et langages de balisage Sculpin supporte-t-il ?

R : Sculpin utilise Twig comme moteur de template par défaut et prend parfaitement en charge le Markdown pour la rédaction des contenus.

Conclusion

Grâce à l’environnement intégré proposé par ServBay, installer et configurer Sculpin (générateur de site statique PHP) sur macOS devient un jeu d’enfant. ServBay préinstalle PHP et Composer, facilite la gestion du serveur Web et automatise les certificats SSL, offrant ainsi une excellente base pour le développement local de Sculpin. En suivant ce guide, vous pouvez rapidement mettre en place un environnement de développement, construire et prévisualiser efficacement vos projets de sites statiques. Associez la puissance de Sculpin à la simplicité de ServBay pour vous concentrer sur le contenu et non sur la complexité de la configuration technique.