Instalacja i konfiguracja Sculpin w środowisku ServBay

Wprowadzenie

Sculpin to potężny i elastyczny statyczny generator stron oparty na PHP, idealny do budowy blogów, stron dokumentacyjnych i wszelkich projektów wymagających przekształcenia dynamicznych treści (np. szablonów Twig i plików Markdown) w szybkie, statyczne strony HTML. Narzędzie to korzysta z Composer do zarządzania zależnościami i bazuje na komponentach Symfony, oferując programistom znane i niezawodne środowisko pracy.

ServBay to lokalne środowisko do tworzenia stron WWW, zaprojektowane specjalnie dla macOS. Integruje wiele najczęściej używanych pakietów jak PHP, Composer, bazy danych (MySQL, PostgreSQL, MongoDB, Redis), serwery WWW (Caddy, Nginx) i oferuje wygodny graficzny interfejs zarządzania. Dzięki ServBay znacznie upraszczasz instalację środowiska deweloperskiego Sculpin na macOS, zwłaszcza zarządzanie wersjami PHP, zależnościami i konfiguracją serwera WWW.

W tym przewodniku szczegółowo opisujemy proces instalacji i konfiguracji Sculpin w środowisku ServBay oraz zakładanie lokalnej strony deweloperskiej.

Przykładowe zastosowania

• Budowa wydajnego bloga statycznego w ekosystemie PHP.
• Generowanie statycznych stron dokumentacyjnych dla projektów open-source lub produktów.
• Szybkie uruchamianie prostych stron marketingowych lub firmowych bez backendu i bazy danych.
• Tworzenie treści w Markdown i zarządzanie szablonami w Twig, aby korzystać z wysokiej prędkości i bezpieczeństwa statycznych witryn.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że spełniasz poniższe warunki:

1. ServBay jest zainstalowany i uruchomiony na macOS. ServBay zawiera wszystkie niezbędne komponenty: środowisko PHP, menedżer zależności Composer i serwer WWW (Caddy lub Nginx).
2. Masz podstawową znajomość obsługi terminala.
3. Rozumiesz podstawowe pojęcia związane z PHP, Composerem i Markdownem.

Kroki instalacji Sculpin

Oto szczegółowa instrukcja instalacji i konfiguracji Sculpin w środowisku ServBay:

Krok 1: Utwórz katalog projektu

Najpierw w katalogu głównym stron w ServBay (/Applications/ServBay/www) utwórz nowy folder na projekt. W tym przykładzie użyjemy nazwy servbay-sculpin-app.

Otwórz Terminal i wykonaj następujące polecenia:

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

Ten katalog będzie zawierał Twoje pliki projektu Sculpin.

Krok 2: Utwórz projekt Sculpin za pomocą Composer

ServBay posiada wbudowanego Composer’a, więc nie musisz instalować go osobno. Wystarczy użyć polecenia composer w terminalu.

Błyskawicznie rozpoczniemy pracę, korzystając z oficjalnego szablonu bloga Sculpin. Będąc w katalogu servbay-sculpin-app, uruchom polecenie:

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

To polecenie pobierze szkielet bloga Sculpin i wszystkie wymagane zależności, instalując wszystko w bieżącym katalogu (.).

Krok 3: Konfiguracja strony w ServBay

Aby uzyskać dostęp do witryny Sculpin przez serwer WWW ServBay (Caddy lub Nginx), należy utworzyć nową konfigurację strony.

1. Uruchom aplikację ServBay: Otwórz graficzny interfejs ServBay.
2. Przejdź do zakładki „Strony”: W głównym oknie ServBay kliknij zakładkę „Strony” w nawigacji.
3. Dodaj nową stronę: Kliknij przycisk „+” w lewym dolnym rogu, aby dodać nową konfigurację.
4. Wypełnij szczegóły strony:
   • Nazwa (Name): Wprowadź rozpoznawalną nazwę, np. My Sculpin Site.
   • Domena (Domain): Podaj nazwę domeny do lokalnego podglądu, np. servbay-sculpin.local. ServBay automatycznie skonfiguruje przekierowanie i wystawi certyfikat SSL dla domeny z końcówką .local (za pomocą ServBay User CA).
   • Typ strony (Type): Wybierz PHP, ponieważ Sculpin to aplikacja PHP.
   • Wersja PHP (PHP Version): Wybierz preferowaną wersję PHP. ServBay obsługuje wiele wersji – wybierz kompatybilną (zwykle nowsza będzie odpowiednia).
   • Katalog główny strony (Document Root): To kluczowy krok. Pliki statyczne Sculpin domyślnie znajdują się w katalogu output_dev lub output_prod projektu. Na potrzeby developmentu wskaż katalog wyjściowy na: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Zapisz konfigurację: Po uzupełnieniu kliknij „Zapisz”. ServBay automatycznie wdroży nową konfigurację do serwera WWW (Caddy lub Nginx). Zazwyczaj nie musisz ręcznie restartować usług ServBay.

Krok 4: Zbuduj stronę Sculpin

Po skonfigurowaniu strony w ServBay musisz wygenerować pliki statyczne witryny za pomocą Sculpin.

W terminalu, upewnij się, że jesteś w głównym katalogu projektu /Applications/ServBay/www/servbay-sculpin-app, a następnie, aby upewnić się, że wszystkie zależności są zainstalowane (jeżeli wykonałeś już krok 2 – możesz pominąć, ale warto to zrobić dla pewności):

composer install

Następnie uruchom polecenie generowania witryny przez Sculpin:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: Ścieżka do pliku wykonywalnego Sculpin zainstalowanego przez Composer.
• generate: Polecenie generujące statyczną stronę – odczytuje treści i szablony z katalogu source, generuje pliki HTML w katalogu wyjściowym (domyślnie output_dev).
• --watch: Ten parametr nakazuje Sculpin monitorować zmiany w katalogu source i automatycznie przebudowywać stronę przy każdym zapisie pliku – idealnie na czas developmentu.

Gdy zobaczysz w terminalu komunikat „Sculpin has generated your site!” lub podobny, pliki statyczne są już wygenerowane i znajdują się w katalogu output_dev.

Krok 5: Podgląd lokalnej strony deweloperskiej

Teraz możesz podejrzeć swoją witrynę Sculpin pod skonfigurowaną domeną ServBay.

Otwórz przeglądarkę i wejdź na adres podany w kroku 3:

https://servbay-sculpin.local

Ponieważ jako katalog główny ServBay wskazałeś output_dev, a komenda sculpin generate --watch działa i monitoruje zmiany, masz możliwość na bieżąco oglądać wyniki swoich prac i modyfikacji na stronie pod adresem https://servbay-sculpin.local. Automatyczny certyfikat SSL wystawiony przez ServBay umożliwia bezpieczny podgląd przez HTTPS.

Rozwój strony przy użyciu Sculpin

Po udanym zainstalowaniu i konfiguracji Sculpin w ServBay, możesz rozpocząć budowę własnej statycznej witryny. Oto podstawy pracy:

Struktura projektu Sculpin

Znajomość struktury ułatwia rozwój projektu Sculpin:

servbay-sculpin-app/
├── app/                # Konfiguracja aplikacji i cache
├── output_dev/         # Katalog wyjściowy dla środowiska developerskiego (ServBay wskazuje tutaj katalog główny strony)
├── output_prod/        # Katalog wyjściowy dla środowiska produkcyjnego
├── source/             # Pliki źródłowe strony (treści Markdown, szablony Twig, zasoby statyczne)
│   ├── _layouts/       # Szablony Twig layout
│   ├── _posts/         # Pliki artykułów blogowych w Markdown
│   ├── assets/         # Zasoby statyczne (CSS, JS, obrazy)
│   └── index.md        # Plik Markdown strony głównej
├── vendor/             # Biblioteki zainstalowane przez Composer
├── sculpin.yml         # Główny plik konfiguracyjny Sculpin
├── composer.json       # Konfiguracja zależności Composer
└── ...inne pliki

Główną pracę wykonujesz w katalogu source.

Tworzenie artykułów blogowych

Aby dodać nowy post na blogu Sculpin, wystarczy utworzyć nowy plik Markdown w katalogu source/_posts. Przyjętą konwencją jest nazewnictwo plików w formacie YYYY-MM-DD-slug.md.

Na przykład, utwórz plik 2024-06-06-my-first-post.md:

---
title: "Mój pierwszy post"
date: 2024-06-06
tags: [Poradnik, Sculpin, ServBay]
---

# Mój pierwszy post

To jest treść mojego pierwszego artykułu na blogu Sculpin. Tutaj dzielę się doświadczeniami związanymi z użyciem ServBay i Sculpin.

Możesz pisać treści używając składni Markdown.

## Podtytuł

Lista:
- Element 1
- Element 2

Po zapisaniu pliku, jeśli masz uruchomioną komendę sculpin generate --watch, Sculpin automatycznie wykryje zmiany i przebuduje stronę. Odśwież stronę pod https://servbay-sculpin.local, aby zobaczyć nowy post.

Dodawanie nowych podstron

By utworzyć osobną podstronę (np. „O nas”), stwórz plik Markdown w katalogu source, np. about.md:

---
title: "O nas"
layout: page.html.twig # Określa używany szablon layout
---

# Przewodnik po ServBay Sculpin

Ta strona zawiera przewodnik dotyczący budowy statycznej witryny przy użyciu ServBay i Sculpin.

Po zapisaniu Sculpin utworzy plik output_dev/about/index.html (jeśli masz skonfigurowane przyjazne adresy URL). Odwiedzając https://servbay-sculpin.local/about/ możesz obejrzeć tę stronę.

Dostosowanie stylów i skryptów

Zasoby statyczne (np. pliki CSS i JavaScript) znajdują się zwykle w katalogu source/assets. Możesz je dowolnie edytować.

Na przykład, edytuj plik source/assets/css/style.css, aby zmienić wygląd strony.

Przy generowaniu witryny zasoby zostaną automatycznie skopiowane do katalogu wyjściowego. Jeśli edytujesz te pliki, funkcja --watch w Sculpin wykryje zmianę i zaktualizuje stronę.

Budowanie wersji na produkcję

Po zakończeniu developmentu witryny, możesz przygotować zoptymalizowaną wersję do wdrożenia. Wersje produkcyjne są często dodatkowo optymalizowane, np. przez minimalizację zasobów.

Wygeneruj wersję produkcyjną poleceniem:

vendor/bin/sculpin generate --env=prod

Wygenerowane pliki będą w katalogu output_prod. Wystarczy wgrać zawartość tego katalogu na hosting statyczny (np. GitHub Pages, Netlify, Vercel lub własny serwer WWW).

Jeśli chcesz obejrzeć wersję produkcyjną strony przez ServBay, zmień w konfiguracji ServBay katalog główny strony na /Applications/ServBay/www/servbay-sculpin-app/output_prod, zapisz zmiany i odwiedź domenę.

Wskazówki i uwagi

• Upewnij się, że ServBay działa i skonfigurowana strona jest włączona.
• Sprawdź, czy w terminalu działa polecenie sculpin generate --watch – pozwoli to na automatyczne budowanie strony podczas developmentu.
• Upewnij się, że „Katalog główny strony” w ServBay wskazuje odpowiedni katalog wyjściowy Sculpin (output_dev w trybie developerskim).
• ServBay automatycznie wystawia certyfikat SSL dla domen .local, ale system operacyjny musi ufać certyfikatowi ServBay User CA – instrukcję znajdziesz w oficjalnej dokumentacji ServBay.

Najczęściej zadawane pytania (FAQ)

Q: Wprowadziłem zmiany w plikach, ale strona się nie odświeża?

A: Sprawdź, czy polecenie vendor/bin/sculpin generate --watch jest uruchomione w katalogu projektu i czy nie wystąpiły błędy. Przejrzyj komunikaty w terminalu. W razie potrzeby wyczyść pamięć podręczną przeglądarki lub użyj trybu incognito.

Q: Otrzymuję błąd SSL przy próbie wejścia na https://servbay-sculpin.local?

A: Serwer ServBay generuje samopodpisane certyfikaty SSL dla domen .local, dlatego należy zaufać ServBay User CA na swoim systemie. Instrukcję znajdziesz w dokumentacji ServBay.

Q: Jak zmienić wersję PHP?

A: W zakładce „Pakiety” w aplikacji ServBay możesz zarządzać różnymi wersjami PHP. Następnie w zakładce „Strony” edytuj konfigurację swojej strony Sculpin i wskaż odpowiednią wersję PHP w ustawieniach.

Q: Jakie szablony i języki znaczników obsługuje Sculpin?

A: Sculpin domyślnie korzysta z silnika szablonów Twig i szeroko obsługuje język Markdown do pisania treści.

Podsumowanie

Dzięki zintegrowanemu środowisku ServBay, instalacja i konfiguracja statycznego generatora stron Sculpin na macOS staje się niezwykle prosta. ServBay oferuje preinstalowane PHP i Composer, łatwe do skonfigurowania serwery WWW oraz automatyczny SSL – wszystko, czego potrzeba do wygodnego lokalnego developmentu z Sculpin. Stosując się do powyższego poradnika, szybko uruchomisz środowisko developerskie Sculpin i zbudujesz oraz zweryfikujesz swoją statyczną stronę. W pełni wykorzystaj możliwości Sculpin w połączeniu z wygodą ServBay, koncentrując się na tworzeniu wartościowych treści bez zmartwień o skomplikowaną konfigurację środowiska programistycznego.