Sculpin installeren en configureren in de ServBay-omgeving

Overzicht

Sculpin is een krachtige en flexibele PHP-gebaseerde statische site generator, uitermate geschikt voor het bouwen van blogs, documentatiesites of elk project waarbij dynamische inhoud (zoals Twig-templates en Markdown-bestanden) omgezet moet worden naar supersnelle statische HTML-pagina's. Sculpin maakt gebruik van Composer voor afhankelijkheidsbeheer en is gebouwd met Symfony-componenten, wat ontwikkelaars een vertrouwde en betrouwbare ontwikkelervaring biedt.

ServBay is een lokaal webontwikkelplatform, speciaal ontworpen voor macOS. Het integreert veelgebruikte pakketten zoals PHP, Composer, databases (MySQL, PostgreSQL, MongoDB, Redis) en webservers (Caddy, Nginx), en biedt daarnaast een gebruiksvriendelijke grafische interface voor beheertaken. Met ServBay wordt het opzetten van een Sculpin-ontwikkelomgeving op macOS aanzienlijk eenvoudiger—vooral als het gaat om het beheren van PHP-versies, afhankelijkheden en webserverconfiguraties.

In deze handleiding lees je stap voor stap hoe je Sculpin installeert, configureert en een lokale ontwikkelsite opzet binnen de ServBay-omgeving.

Toepassingsscenario’s

• Het bouwen van een razendsnelle statische blog met PHP-technologie.
• Genereren van statische documentatiesites voor open source-projecten of producten.
• Snel opzetten van statische marketing- of bedrijfspagina’s zonder backend-database.
• Inhoud schrijven met Twig-templating en Markdown, en profiteren van de snelheid en veiligheid van een statische website.

Vereisten

Controleer voordat je begint of je aan de volgende voorwaarden voldoet:

1. ServBay is geïnstalleerd en actief op je macOS-systeem. ServBay levert een geschikte PHP-omgeving, de Composer package manager en een webserver (Caddy of Nginx).
2. Je hebt basiskennis van de commandoregel.
3. Je bent bekend met de basisbegrippen van PHP, Composer en Markdown.

Stappen voor het installeren van Sculpin

Hieronder de gedetailleerde stappen voor het installeren en instellen van Sculpin in een ServBay-omgeving:

Stap 1: Maak een projectmap aan

Maak eerst een nieuwe projectmap in de website root van ServBay (/Applications/ServBay/www). In dit voorbeeld noemen we het project servbay-sculpin-app.

Open de terminal en voer de volgende commando’s uit:

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

In deze map komen je Sculpin-projectbestanden terecht.

Stap 2: Maak een Sculpin-project met Composer

ServBay wordt geleverd met Composer; je hoeft Composer dus niet los te installeren. Je kunt direct het composer commando in de terminal gebruiken.

Gebruik de door Sculpin geleverde blog-skelet als startpunt. Voer in de eerder aangemaakte map servbay-sculpin-app het volgende Composer-commando uit:

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

Dit commando downloadt het blog-skelet en alle afhankelijkheden via Composer en plaatst ze in de huidige map (.).

Stap 3: ServBay-site configureren

Om je Sculpin-website toegankelijk te maken via de webserver van ServBay (Caddy of Nginx), voeg je een nieuwe site-configuratie toe in ServBay.

1. Open de ServBay-app: Start de grafische interface van ServBay.
2. Ga naar het tabblad “Sites”: Klik bovenin het ServBay-venster op het tabblad “Sites”.
3. Voeg een nieuwe site toe: Klik linksonder op de “+”-knop om een nieuwe site toe te voegen.
4. Vul de sitegegevens in:
   • Naam (Name): Geef een herkenbare naam, bijvoorbeeld My Sculpin Site.
   • Domein (Domain): Voer het lokale domein in, bijvoorbeeld servbay-sculpin.local. ServBay regelt automatisch de lokale DNS en een SSL-certificaat voor .local domeinen (via de ServBay User CA).
   • Type (Type): Kies voor PHP, aangezien Sculpin een PHP-applicatie is.
   • PHP-versie (PHP Version): Kies de gewenste PHP-versie. ServBay ondersteunt meerdere PHP-versies; selecteer een versie die door Sculpin ondersteund wordt (meestal een recente versie).
   • Document root (Website root directory): Belangrijk! Sculpin plaatst standaard de gegenereerde statische bestanden in de map output_dev of output_prod. Voor lokale ontwikkeling verwijs je de root naar de ontwikkel-outputmap: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Sla de configuratie op: Klik na het invullen op “Opslaan”. ServBay past je instellingen direct toe op de webserver (Caddy of Nginx). In de meeste gevallen hoef je ServBay niet handmatig te herstarten.

Stap 4: De Sculpin-site genereren

Na het configureren van de site in ServBay moet je Sculpin de statische bestanden van je website laten genereren.

Zorg dat je terminal zich nog steeds in de projectroot bevindt:/Applications/ServBay/www/servbay-sculpin-app. Voer om zeker te zijn dat alle afhankelijkheden aanwezig zijn (eventueel dubbel met stap 2, maar geen probleem) het volgende commando uit:

composer install

Daarna genereer je de site met Sculpin:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: het pad naar het uitvoerbare Sculpin-bestand, geïnstalleerd via Composer.
• generate: de opdracht om de statische site aan te maken. Sculpin leest alles uit de source map en zet de sitebestanden in de outputmap (standaard output_dev).
• --watch: hiermee ‘luistert’ Sculpin naar wijzigingen in de source-map en genereert bij elke aanpassing automatisch de site opnieuw—ideaal tijdens ontwikkeling.

Na een melding als "Sculpin has generated your site!" vind je de statische sitebestanden terug in de map output_dev.

Stap 5: Je lokale ontwikkelsite bezoeken

Nu kun je je Sculpin-site bekijken op het domein dat je in ServBay instelde.

Open je browser en ga naar het opgegeven domein:

https://servbay-sculpin.local

Doordat je de document root hebt ingesteld op output_dev (en het commando sculpin generate --watch draait en de site actueel houdt), kun je alle wijzigingen direct live zien via https://servbay-sculpin.local. ServBay regelt automatisch het SSL-certificaat voor een veilige HTTPS-verbinding.

Ontwikkelen met Sculpin

Nu Sculpin succesvol is geïnstalleerd binnen ServBay kun je starten met het bouwen van je eigen statische website. Enkele basiswerkzaamheden:

Projectstructuur van Sculpin in het kort

Het helpt om de globaal opbouw van een Sculpin-project te kennen:

servbay-sculpin-app/
├── app/                # Applicatieconfiguratie en cachebestanden
├── output_dev/         # Output-map voor de ontwikkelomgeving (hier wijst je ServBay site naar)
├── output_prod/        # Geoptimaliseerde output-map voor productie
├── source/             # Bronbestanden (Markdown, Twig-templates, assets)
│   ├── _layouts/       # Twig-layoutbestanden
│   ├── _posts/         # Blogposts als Markdown-bestanden
│   ├── assets/         # Statische bronnen (CSS, JS, afbeeldingen, etc.)
│   └── index.md        # De homepage als Markdown-bestand
├── vendor/             # Door Composer geïnstalleerde libraries
├── sculpin.yml         # Sculpin-configuratiebestand
├── composer.json       # Composer dependency-configuratie
└── ...overige bestanden

Het merendeel van je werkzaamheden gebeurt in de source-map.

Een blogpost aanmaken

Een nieuwe blogpost maken is simpel: plaats een nieuw Markdown-bestand in de map source/_posts. Gebruik meestal het formaat YYYY-MM-DD-slug.md voor de bestandsnaam.

Bijvoorbeeld, maak het bestand 2024-06-06-my-first-post.md aan:

---
title: "Mijn eerste bericht"
date: 2024-06-06
tags: [Tutorial, Sculpin, ServBay]
---

# Mijn eerste bericht

Dit is de inhoud van mijn eerste Sculpin-blogpost. Hier deel ik ervaring met ServBay en Sculpin.

Je kunt hier gewoon Markdown gebruiken voor je teksten.

## Subkop

Lijst:
- Item 1
- Item 2

Zodra je opslaat, detecteert Sculpin direct het nieuwe bestand (mits sculpin generate --watch draait) en regenereert de website. Herlaad https://servbay-sculpin.local in je browser voor het resultaat.

Nieuwe pagina’s aanmaken

Wil je een losse pagina toevoegen, zoals een “Over ons”-pagina? Maak dan simpelweg direct in de source-map een Markdown-bestand aan, bijvoorbeeld about.md:

---
title: "Over ons"
layout: page.html.twig # Gekozen layoutbestand
---

# Over deze ServBay Sculpin Gids

Op deze pagina vind je informatie over het bouwen van een statische site met ServBay en Sculpin.

Na opslaan maakt Sculpin automatisch output_dev/about/index.html aan (bij gebruik van prettige URL’s). Je pagina is bereikbaar via https://servbay-sculpin.local/about/.

Stijlen en scripts aanpassen

Statische resources als CSS en JavaScript staan in de source/assets-map. Je kunt deze bestanden direct aanpassen.

Bijvoorbeeld: bewerk source/assets/css/style.css om de website-stijl aan te passen.

Sculpin kopieert deze assets automatisch naar de outputmap—ook wijzigingen in deze bestanden worden direct gedetecteerd en verwerkt dankzij --watch.

De productieversie van je site bouwen

Ben je klaar met ontwikkelen? Bouw dan een geoptimaliseerde productieversie. Hierbij worden onder andere resources geminimaliseerd.

Gebruik hiervoor het commando:

vendor/bin/sculpin generate --env=prod

De geproduceerde site komt terecht in de map output_prod. Upload de inhoud van deze map naar een statische hostingservice (zoals GitHub Pages, Netlify, Vercel of je eigen webserver) om de site te publiceren.

Wil je het productieresultaat lokaal bekijken via ServBay? Wijzig dan de document root in de ServBay-siteconfiguratie naar /Applications/ServBay/www/servbay-sculpin-app/output_prod, sla op en bezoek het domein.

Belangrijke aandachtspunten

• Zorg dat ServBay actief is en dat de betreffende site is ingeschakeld.
• Draait het sculpin generate --watch-commando in de terminal? Dit is nodig voor automatische updates.
• Controleer of je ServBay-siteconfiguratie qua document root naar de juiste outputmap van Sculpin verwijst (tijdens ontwikkeling is dit meestal output_dev).
• ServBay levert automatisch SSL-certificaten voor .local domeinen, maar mogelijk dien je het ServBay User CA-certificaat op je besturingssysteem te vertrouwen. Volg de instructies in de ServBay-documentatie.

Veelgestelde vragen (FAQ)

Q: Ik heb bestanden aangepast, maar mijn website wordt niet bijgewerkt.

A: Controleer of het vendor/bin/sculpin generate --watch-commando actief is in de projectmap en niet is afgebroken door een foutmelding. Check voor eventuele errors in de terminaloutput. Wis eventueel je browsercache of gebruik de privémodus.

Q: Ik krijg een SSL-fout bij het bezoeken van https://servbay-sculpin.local.

A: Dit komt doordat ServBay een zelfondertekend certificaat gebruikt voor .local domeinen. Je besturingssysteem moet mogelijk de ServBay User CA vertrouwen. Raadpleeg hiervoor de ServBay-documentatie.

Q: Hoe verander ik de PHP-versie?

A: Gebruik het tabblad “Packages” in de ServBay-app om meerdere PHP-versies te installeren en beheren. Vervolgens kun je in het tabblad “Sites” de gewenste PHP-versie selecteren voor je Sculpin-site en dit opslaan.

Q: Welke templating engines en markup-talen ondersteunt Sculpin?

A: Sculpin gebruikt standaard Twig als template-engine en ondersteunt breed Markdown voor contentcreatie.

Samenvatting

Dankzij de complete en geïntegreerde ServBay-omgeving is het installeren en configureren van de Sculpin statische site generator op macOS erg eenvoudig. Met vooraf geïnstalleerde PHP en Composer, gemakkelijk in te stellen webservers en automatische SSL-functionaliteit, biedt ServBay een solide basis voor lokale Sculpin-ontwikkeling. Volg deze gids om in korte tijd je Sculpin-ontwikkelomgeving op te zetten en efficiënt je statische websiteproject te bouwen en te testen. Door de kracht van Sculpin te combineren met het gemak van ServBay, kun je je volledig richten op kwalitatieve content—zonder je zorgen te hoeven maken over omslachtig lokaal configuratiewerk.