Встановлення та налаштування Sculpin у середовищі ServBay

Огляд

Sculpin — це потужний і гнучкий генератор статичних сайтів на основі PHP, який ідеально підходить для створення блогів, сайтів документації або будь-яких інших проєктів, де потрібно перетворювати динамічний вміст (наприклад, шаблони Twig та файли Markdown) на високопродуктивні статичні HTML-сторінки. Він керує залежностями через Composer і побудований на компонентах Symfony, що забезпечує розробникам знайомий і надійний досвід розробки.

ServBay — це локальне середовище розробки для macOS, яке об'єднує популярні пакети, зокрема PHP, Composer, бази даних (MySQL, PostgreSQL, MongoDB, Redis), веб-сервери (Caddy, Nginx) тощо, та надає зручний графічний інтерфейс для керування. ServBay значно спрощує налаштування середовища для розробки Sculpin на macOS, особливо з керуванням версіями PHP, менеджментом залежностей і налаштуванням веб-сервера.

Цей посібник докладно описує, як встановити та налаштувати Sculpin у ServBay, а також створити локальний сайт для розробки.

Сценарії використання

• Створення високопродуктивного статичного блогу на основі PHP.
• Генерація статичної документації для open source проєктів або продуктів.
• Швидкий запуск простих маркетингових сторінок або корпоративних сайтів без бекенд-бази даних.
• Використання шаблонізатора Twig і розмітки Markdown для створення, із перевагами швидкості та безпеки статичних сайтів.

Передумови

Перш ніж почати, переконайтеся, що ви виконали такі умови:

1. Встановили та запустили ServBay на macOS. ServBay вже містить середовище PHP, менеджер залежностей Composer та веб-сервер (Caddy або Nginx).
2. Маєте базові навички роботи з командним рядком.
3. Розумієте основи PHP, Composer і Markdown.

Кроки встановлення Sculpin

Нижче наведені докладні кроки зі встановлення та налаштування Sculpin у ServBay.

Крок 1: Створення директорії проєкту

Спочатку створіть нову папку для вашого проєкту в кореневому каталозі сайтів ServBay (/Applications/ServBay/www). В якості прикладу використаємо назву проєкту servbay-sculpin-app.

Відкрийте термінал і виконайте:

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

У цій директорії зберігатимуться всі файли вашого Sculpin-проєкту.

Крок 2: Створення Sculpin-проєкту через Composer

ServBay вже містить Composer, тому нічого додатково встановлювати не потрібно. Ви можете виконувати команду composer безпосередньо у терміналі.

Для швидкого старту використаємо офіційний шаблон блогу Sculpin. Знаходячись у каталозі servbay-sculpin-app, виконайте:

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

Ця команда завантажить шаблон блогу Sculpin із усіма залежностями до поточної папки (.).

Крок 3: Налаштування сайту в ServBay

Щоб зробити ваш Sculpin-сайт доступним через веб-сервер (Caddy або Nginx) у ServBay, необхідно додати нову конфігурацію сайту.

1. Запустіть додаток ServBay: відкрийте графічний інтерфейс ServBay.
2. Перейдіть на вкладку «Сайти»: у вікні ServBay виберіть вкладку «Сайти» в навігації.
3. Додайте новий сайт: натисніть кнопку «+» у лівому нижньому куті для створення нового сайту.
4. Заповніть інформацію про сайт:
   • Ім’я (Name): вкажіть зручну назву, наприклад My Sculpin Site.
   • Домен (Domain): впишіть локальний домен для доступу, наприклад servbay-sculpin.local. ServBay автоматично налаштує локальне вирішення і SSL для домену з суфіксом .local (через ServBay User CA).
   • Тип сайту (Type): виберіть PHP, оскільки Sculpin — це PHP-додаток.
   • Версія PHP (PHP Version): виберіть бажану версію PHP, сумісну з Sculpin (зазвичай підійде версія новіша).
   • Кореневий каталог сайту (Document Root): важливо! Sculpin за замовчуванням генерує статичні файли у output_dev або output_prod. Для розробки налаштуйте root на: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Збережіть налаштування: натисніть «Зберегти». ServBay автоматично застосує налаштування до вибраного веб-сервера (Caddy або Nginx). Сервіси не потребують ручного перезапуску.

Крок 4: Збірка Sculpin-сайту

Після налаштування сайту у ServBay, потрібно згенерувати статичні файли Sculpin.

В терміналі, залишаючись у каталозі /Applications/ServBay/www/servbay-sculpin-app, виконайте встановлення залежностей (якщо вже виконували крок 2 — достатньо виконати це для впевненості):

composer install

Далі — запустіть генерацію сайту:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin — шлях до виконавчого файлу Sculpin, встановленого Composer.
• generate — команда для побудови статичного сайту. Вона читає вміст із директорії source і виводить статичні файли у вказаний каталог (за замовчуванням output_dev).
• --watch — цей прапорець дозволяє Sculpin автоматично відстежувати зміни у source та перебудовувати сайт під час розробки.

Коли побачите повідомлення на зразок "Sculpin has generated your site!", статичні файли вже створено у output_dev.

Крок 5: Доступ до локального сайту

Тепер ви можете перейти за налаштованим у ServBay доменом для перегляду сайту.

Відкрийте браузер і відвідайте вказану на кроці 3 адресу:

https://servbay-sculpin.local

Оскільки ви вказали корінь сайту як output_dev, а команда sculpin generate --watch запущена й стежить за змінами, ви можете в режимі реального часу переглядати усі зміни контенту й шаблонів на https://servbay-sculpin.local. Автоматичний SSL від ServBay гарантує безпечний доступ по HTTPS.

Робота з Sculpin у розробці

Тепер, коли Sculpin повністю встановлений і налаштований у ServBay, можна приступати до створення власного статичного сайту. Основні кроки та поради нижче:

Основна структура проєкту Sculpin

Ознайомлення зі структурою проєкту Sculpin допоможе вам ефективніше розробляти сайт:

servbay-sculpin-app/
├── app/                # Конфігурації програми та кеш
├── output_dev/         # Каталог для вихідних статичних файлів у режимі розробки (корінь сайту ServBay)
├── output_prod/        # Вихідний каталог для продакшен-версії сайту
├── source/             # Вихідні файли сайту (контент Markdown, шаблони Twig, статичні ресурси тощо)
│   ├── _layouts/       # Шаблони Twig
│   ├── _posts/         # Блог-пости у форматі Markdown
│   ├── assets/         # Статичні ресурси (CSS, JS, зображення тощо)
│   └── index.md        # Головна сторінка у форматі Markdown
├── vendor/             # Залежності, встановлені через Composer
├── sculpin.yml         # Головний файл конфігурації Sculpin
├── composer.json       # Файл конфігурації залежностей Composer
└── ...інші файли

Основна робота ведеться у папці source.

Додавання блогу-постів

Щоб створити новий допис у блог Sculpin, додайте файл Markdown у директорію source/_posts. Назва файлу — у форматі YYYY-MM-DD-slug.md.

Наприклад, створіть файл 2024-06-06-my-first-post.md:

---
title: "Мій перший допис"
date: 2024-06-06
tags: [Туторіал, Sculpin, ServBay]
---

# Мій перший допис

Це перший допис у моєму блозі на Sculpin. Тут я поділюся досвідом роботи з ServBay і Sculpin.

Ви можете додавати контент за допомогою розмітки Markdown.

## Підзаголовок

Список:
- Пункт 1
- Пункт 2

Після збереження файлу (й якщо запущено команду sculpin generate --watch), Sculpin автоматично перебудує сайт, і на https://servbay-sculpin.local буде видно нову статтю.

Додавання окремих сторінок

Щоб створити окрему сторінку (наприклад, «Про нас»), просто створіть файл Markdown у папці source, наприклад, about.md:

---
title: "Про нас"
layout: page.html.twig # Вказати шаблон сторінки
---

# Посібник із використання ServBay Sculpin

Ця сторінка — довідка щодо створення статичних сайтів із ServBay і Sculpin.

Після збереження Sculpin згенерує файл output_dev/about/index.html (якщо увімкнено гарні URL). Сторінка буде доступна за адресою https://servbay-sculpin.local/about/.

Кастомізація стилів і скриптів

Статичні ресурси (CSS, JavaScript) зберігаються в source/assets. Ви можете редагувати, наприклад, файл стилів у source/assets/css/style.css.

Під час генерації сайту ці ресурси буде скопійовано у вихідний каталог. Якщо змінити будь-який із цих файлів, Sculpin з прапорцем --watch миттєво відслідкує зміни й перебудує сайт.

Збірка сайту для продакшену

Коли сайт готовий до публікації, потрібно зібрати версію для продакшену, зазвичай із додатковою оптимізацією (наприклад, мінімізація ресурсів):

vendor/bin/sculpin generate --env=prod

Ця команда виведе сайт до каталогу output_prod. Ви можете розмістити вміст цієї папки на будь-якому статичному хостингу (GitHub Pages, Netlify, Vercel або ваш власний сервер).

Щоб переглянути продакшен-версію через ServBay, змініть у налаштуваннях сайта «Кореневий каталог» на /Applications/ServBay/www/servbay-sculpin-app/output_prod, збережіть зміни й відкрийте домен у браузері.

На що звернути увагу

• Перевірте, що ServBay запущено, а сайт активований.
• Переконайтеся, що команда sculpin generate --watch виконується у терміналі для автоматичної перебудови під час розробки.
• Перегляньте, чи правильно вказано «Кореневий каталог» у налаштуваннях сайта ServBay (зазвичай це output_dev для розробки).
• ServBay автоматично видає SSL-сертифікат для доменів .local, але macOS може вимагати довіри до ServBay User CA. Дивіться докладніше у документації ServBay.

Часті питання (FAQ)

Питання: Я вніс зміни, але сайт не оновлюється?

Відповідь: Переконайтеся, що ви запустили команду vendor/bin/sculpin generate --watch у директорії проєкту, і вона не припинила виконання через помилки. Перегляньте вихідні повідомлення у терміналі та спробуйте очистити кеш браузера або використати приватний режим.

Питання: З’являється помилка SSL під час доступу до https://servbay-sculpin.local?

Відповідь: ServBay генерує самопідписаний сертифікат для доменів .local — потрібно, щоб macOS довіряла ServBay User CA. Дотримуйтеся інструкцій з документації ServBay для встановлення та довіри до Root CA.

Питання: Як змінити версію PHP?

Відповідь: Ви можете керувати різними версіями PHP у вкладці «Пакети» програми ServBay, а потім у вкладці «Сайти» вибрати потрібну версію для вашого Sculpin-сайту і зберегти зміни.

Питання: Які шаблони і розмітки підтримує Sculpin?

Відповідь: За замовчуванням Sculpin використовує Twig як шаблонізатор і Markdown як основну мову контенту.

Висновки

Завдяки інтегрованому середовищу ServBay встановлення і налаштування генератора статичних сайтів Sculpin на macOS стає надзвичайно простим. Попередньо встановлені PHP і Composer, зручне налаштування веб-сервера та автоматичний SSL у ServBay створюють чудову основу для локальної розробки сайтів на Sculpin. Дотримуючись цього посібника, ви зможете швидко налаштувати середовище розробки й ефективно створювати, оновлювати і тестувати свій статичний сайт. Комбінуйте потужність Sculpin із зручністю ServBay — і зосередьтеся на створенні якісного контенту, не витрачаючи часу на складне налаштування локального середовища.