Instalacja i konfiguracja Kirby CMS w środowisku ServBay

Kirby to elastyczny i potężny plikowy system zarządzania treścią (CMS), idealny do tworzenia różnorodnych stron internetowych. W przeciwieństwie do tradycyjnych CMS-ów opartych o bazy danych, Kirby przechowuje całą zawartość w systemie plików, co sprawia, że jest wyjątkowo lekki, łatwy do wersjonowania i prosty w wdrożeniu.

Ten poradnik przeprowadzi Cię przez proces instalacji i konfiguracji przykładowego Kirby 4.2 Starterkit z użyciem Composer w środowisku ServBay – lokalnym narzędziu programistycznym zoptymalizowanym pod kątem twórców stron WWW. ServBay zapewnia gotowe konfiguracje PHP, serwera WWW (np. Caddy lub Nginx) oraz Composer, stanowiąc idealną platformę do lokalnego rozwoju z użyciem Kirby.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

1. Zainstalowano i uruchomiono na macOS aplikację ServBay.
2. W ServBay została aktywowana odpowiednia wersja PHP (w tym przykładzie używamy PHP 8.2).
3. Composer jest już dostępny w ServBay – nie musisz instalować go osobno.

Kroki instalacji Kirby

Poniżej znajdziesz szczegółową instrukcję instalacji i konfiguracji Kirby w środowisku ServBay:

Krok 1: Utwórz katalog projektu

Najpierw otwórz aplikację Terminal. Przejdź do domyślnego katalogu głównego serwisów www ServBay (/Applications/ServBay/www) i utwórz nowy katalog projektu. W tym przykładzie nadajemy mu nazwę servbay-kirby-app.

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

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

Composer jest już zintegrowany w środowisku ServBay, więc możesz od razu skorzystać z niego w terminalu. Będąc w katalogu projektu servbay-kirby-app, uruchom poniższe polecenie, aby pobrać i zainicjować Starterkit Kirby w bieżącym katalogu:

composer create-project getkirby/starterkit .

To polecenie pobiera pliki główne Kirby, zależności oraz Starterkit z przykładową zawartością i szablonami do bieżącego katalogu (.).

Krok 3: Skonfiguruj serwer WWW (dodawanie strony w ServBay)

Aby Twój projekt Kirby był obsługiwany przez serwer WWW ServBay (Caddy lub Nginx), musisz dodać nową stronę w konfiguracji aplikacji ServBay.

1. Otwórz aplikację ServBay: Uruchom ServBay.
2. Przejdź do zarządzania stronami: Kliknij w zakładkę „Strony” w bocznym panelu ServBay.
3. Dodaj nową stronę: Użyj przycisku „+” lub innej opcji dodania strony na dole interfejsu.
4. Wypełnij dane strony w wyskakującym oknie konfiguracji:
   • Nazwa: Podaj łatwą do rozpoznania nazwę, np. My Kirby Site.
   • Domena: Ustaw domenę dla rozwoju lokalnego, najlepiej kończącą się na .local lub .servbay.demo, np. servbay-kirby.local. ServBay automatycznie skonfiguruje lokalny DNS dla tej domeny.
   • Typ strony: Wybierz PHP, ponieważ Kirby to aplikacja PHP.
   • Wersja PHP: Wskaż wersję PHP, np. 8.2. Upewnij się, że spełnia ona minimalne wymagania Kirby.
   • Katalog główny serwisu: Wskaż katalog, w którym znajduje się plik index.php Twojego projektu Kirby. Dla Starterkit będzie to katalog główny projektu: /Applications/ServBay/www/servbay-kirby-app.
5. Zapisz konfigurację: Po upewnieniu się, że wszystko jest poprawnie ustawione, zapisz stronę. ServBay automatycznie zastosuje nową konfigurację i może poprosić o restart odpowiedniego serwera WWW.

Krok 4: Wstępna konfiguracja Kirby

Konfiguracja główna Kirby znajduje się w pliku site/config/config.php. W Starterkit najważniejsze ustawienia są już skonfigurowane i możesz od razu uruchomić aplikację. Możesz jednak w tym pliku dodać własne opcje, np.:

• Włączyć tryb debugowania (c::set('debug', true);)
• Ustawić język panelu administracyjnego
• Zdefiniować niestandardowe trasy

W katalogu głównym projektu content został automatycznie utworzony przez Starterkit i do niego trafi cała treść Twoich stron.

Krok 5: Uruchom i odwiedź stronę Kirby

Po konfiguracji ServBay Twój serwis Kirby jest dostępny pod wybraną domeną.

1. Upewnij się, że ServBay działa: Zweryfikuj, czy ServBay oraz odpowiednie serwery WWW (Caddy lub Nginx) i PHP są aktywne.
2. Odwiedź stronę: Otwórz wybraną przeglądarkę i wpisz w pasku adresu skonfigurowaną przez Ciebie domenę – np. https://servbay-kirby.local.

Powinieneś zobaczyć domyślną stronę powitalną Starterkit Kirby. ServBay domyślnie obsługuje HTTPS, dlatego zalecane jest używanie https:// podczas dostępu do serwisu.

Krok 6: Instalacja i korzystanie z panelu Kirby (opcjonalnie)

Kirby oferuje rozbudowany panel administracyjny, który pozwala zarządzać treścią, użytkownikami i opcjami strony.

1. Odwiedź stronę instalacji panelu: Przejdź na swoją domenę i dopisz do adresu /panel, np. https://servbay-kirby.local/panel.
2. Utwórz konto administratora: Przy pierwszym wejściu do /panel zostaniesz przekierowany do strony instalacji panelu – podaj wymagane dane (nazwa użytkownika, hasło, e-mail), aby utworzyć swoje konto.
3. Zaloguj się do panelu: Po założeniu konta możesz zalogować się i zarządzać treściami swojej strony przez graficzny interfejs.

Tworzenie stron z użyciem Kirby

Po poprawnej instalacji i konfiguracji Kirby w środowisku ServBay możesz zacząć budować własną stronę, wykorzystując zalety plikowego systemu Kirby. Oto podstawowe pojęcia i operacje, które przydadzą się na starcie:

Struktura treści (Content)

Treść Kirby znajduje się w katalogu content. Każda podstrona to osobny folder w katalogu content. Zawartość strony zapisana jest zazwyczaj w plikach tekstowych (np. page.txt) w formacie zbliżonym do Markdown.

Przykład: utworzenie strony „O nas”

W terminalu:

cd /Applications/ServBay/www/servbay-kirby-app
mkdir content/about
echo "Title: O nas\n----\nTo jest treść strony o nas." > content/about/about.txt

Następnie odwiedź https://servbay-kirby.local/about (jeśli Twój szablon pozwala na wyświetlanie tej podstrony).

Szablony (Templates)

Szablony znajdziesz w katalogu site/templates i decydują one o sposobie renderowania poszczególnych stron. Nazwa szablonu zwykle odpowiada nazwie folderu w content lub nazwie blueprinta (np. about.php dla folderu content/about lub stron na blueprintcie about).

Przykład: utworzenie szablonu about.php

W pliku site/templates/about.php:

<?php snippet('header') ?>

<main>
  <h1><?= $page->title() ?></h1>
  <div class="text">
    <?= $page->text()->kt() // Renderowanie z użyciem KirbyText ?>
  </div>
</main>

<?php snippet('footer') ?>

Wykorzystujemy tu funkcję snippet(), aby włączyć wspólne elementy, np. nagłówek i stopkę.

Blueprinty (Blueprints)

Blueprinty definiują strukturę, pola i opcje stron w panelu administracyjnym Kirby. Są zapisane w plikach YAML w katalogu site/blueprints.

Przykład: utworzenie blueprinta about.yml

W pliku site/blueprints/pages/about.yml:

title: Strona „O nas”

columns:
  - width: 2/3
    fields:
      text:
        label: Treść
        type: textarea
        size: large
        buttons:
          - bold
          - italic
          - link
          - email

  - width: 1/3
    fields:
      # Pola w sidebarze, np. przesyłanie zdjęcia
      cover_image:
        label: Zdjęcie okładkowe
        type: files
        max: 1
        uploads:
          template: image

Po utworzeniu blueprinta, podczas dodawania w panelu nowej podstrony „O nas” pojawią się zadeklarowane tu pola.

Snippety (Snippets)

Snippet to wielokrotnie wykorzystywany plik PHP, zwykle używany do generowania nagłówka, stopki lub nawigacji i umieszczany w site/snippets.

Kontrolery (Controllers) i modele (Models)

Jeśli potrzebujesz bardziej zaawansowanej logiki, możesz użyć kontrolerów (site/controllers) do obsługi danych na stronach oraz modeli (site/models) do definiowania własnych typów podstron.

Zasoby statyczne (Assets)

Pliki CSS, JavaScript, grafiki i inne zasoby statyczne znajdują się zwykle w katalogu assets w głównym folderze projektu. W szablonach możesz korzystać z funkcji url('assets/...') w celu pobrania ścieżki do tych plików.

Przykład: podłączanie CSS i JS

W pliku site/templates/default.php lub site/snippets/header.php:

<link rel="stylesheet" href="<?= url('assets/css/style.css') ?>">
<script src="<?= url('assets/js/script.js') ?>"></script>

Podsumowanie

Wykonując powyższe kroki, poprawnie zainstalowałeś i skonfigurowałeś Kirby CMS w lokalnym środowisku ServBay. Dzięki zintegrowanemu środowisku ServBay wdrażanie i zarządzanie aplikacjami PHP jest wyjątkowo proste, co pozwala Ci skupić się na wykorzystaniu pełnych możliwości Kirby i elastyczności plikowego CMS-a podczas budowy własnych stron. Teraz możesz zagłębić się w dokumentację Kirby, zgłębiać szablony, blueprinty, snippety i tworzyć coraz bardziej zaawansowane struktury oraz funkcjonalności serwisu.