Instalacja i konfiguracja OctoberCMS w środowisku ServBay

Przegląd

OctoberCMS to open-source'owy system zarządzania treścią (CMS) oparty na potężnym frameworku Laravel, ceniony za swoją prostotę, elastyczność i przyjazność dla deweloperów. Niniejszy dokument poprowadzi Cię krok po kroku przez proces instalacji i konfiguracji OctoberCMS w ServBay — kompleksowym, lokalnym środowisku deweloperskim zaprojektowanym dla macOS — aby umożliwić Ci szybki start z nowymi projektami opartymi o OctoberCMS.

Czym jest OctoberCMS?

OctoberCMS oferuje intuicyjny panel administracyjny oraz zaawansowane możliwości frontendowe, pozwalając deweloperom korzystającym z dobrze znanych koncepcji Laravela (takich jak Eloquent ORM, silnik szablonów Blade itp.) budować dowolne strony — od prostych blogów po złożone aplikacje korporacyjne.

Wymagania wstępne

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

1. ServBay jest zainstalowany i uruchomiony na Twoim macOS.
2. Pakiety PHP (zalecane 7.4 lub wyżej) oraz MySQL/MariaDB są włączone i aktywne w ServBay.
3. Pakiet Composer jest aktywny w ServBay.
4. Masz podstawową wiedzę z obsługi terminala/wiersza polecenia.

Instrukcja instalacji OctoberCMS

Poniżej znajdziesz szczegółowy opis procesu instalacji i konfiguracji OctoberCMS w środowisku ServBay:

Krok 1: Utworzenie katalogu projektu

Najpierw przejdź do zalecanego przez ServBay katalogu głównego stron /Applications/ServBay/www i utwórz w nim nowy folder na swój projekt OctoberCMS.

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

Krok 2: Instalacja OctoberCMS przez Composer

ServBay dostarcza i konfiguruje Composer w standardzie. Upewnij się, że Composer jest włączony w panelu zarządzania ServBay. Następnie, będąc w katalogu projektu, uruchom polecenie Composer, aby pobrać i zainstalować pliki OctoberCMS:

composer create-project october/october .

To polecenie pobierze najnowszą wersję OctoberCMS z oficjalnego repozytorium bezpośrednio do bieżącego katalogu (.).

Krok 3: Utworzenie bazy danych i użytkownika

OctoberCMS wymaga bazy danych do przechowywania treści, użytkowników, konfiguracji i innych informacji. Skorzystamy z dołączonego do ServBay narzędzia phpMyAdmin, aby utworzyć bazę oraz użytkownika.

1. Dostęp do phpMyAdmin od ServBay

   Otwórz przeglądarkę i przejdź do lokalnego panelu ServBay https://servbay.host/. Następnie wybierz lub wejdź w link do phpMyAdmin — zazwyczaj znajduje się pod adresem https://servbay.host/phpmyadmin/.

2. Utworzenie użytkownika bazy danych

   Dla bezpieczeństwa i izolacji każda aplikacja powinna mieć osobnego użytkownika i dedykowaną bazę danych.

   1. Wejdź na stronę zarządzania użytkownikami

      W głównym menu phpMyAdmin kliknij „Użytkownicy”.

   2. Dodaj nowego użytkownika

      Kliknij „Dodaj użytkownika”. Uzupełnij dane według poniższych wskazówek:

      • Nazwa użytkownika: np. october_user — nazwa użytkownika, przez którą OctoberCMS uzyska dostęp do bazy.
      • Host: wybierz localhost lub 127.0.0.1 — w ten sposób konto będzie mogło łączyć się z bazą tylko z maszyny lokalnej, co zwiększa bezpieczeństwo.
      • Hasło: ustaw silne i unikalne hasło. Nie używaj przykładowego hasła password123 w środowisku produkcyjnym!
      • Potwierdź hasło: wprowadź ponownie wybrane hasło.
      • W sekcji „Baza danych dla użytkownika” zaznacz „Utwórz bazę danych o takiej samej nazwie i przyznaj wszystkie uprawnienia”. To automatycznie utworzy bazę i doda pełne prawa dla użytkownika o nazwie october_user.
      • Upewnij się, że masz zaznaczone „Przyznaj wszystkie uprawnienia” w sekcji uprawnień globalnych (jeśli wcześniej zaznaczono tworzenie bazy i nadawanie uprawnień, często nie trzeba robić nic więcej).
      • Zatwierdź klikając „Wykonaj” na dole strony, aby utworzyć użytkownika i bazę.

Krok 4: Konfiguracja serwera WWW (dodanie strony w ServBay)

Aby uzyskać dostęp do aplikacji OctoberCMS przez przeglądarkę, należy skonfigurować nową, lokalną stronę w ServBay.

1. Dodanie nowej strony

   Otwórz panel zarządzania ServBay i kliknij zakładkę „Strony” (w starszych wersjach może być oznaczona jako „Hosty”). Następnie wybierz opcję „Dodaj stronę”.

   Wypełnij poniższe pola:

   • Nazwa: np. My OctoberCMS Site — dowolna, ułatwiająca identyfikację.
   • Domena: np. servbay-octobercms.local — użyj końcówki .local, aby uniknąć konfliktów z rzeczywistymi domenami.
   • Typ strony: wybierz PHP.
   • Wersja PHP: wybierz wersję zgodną z wymaganiami OctoberCMS, zgodną z aktywną wersją w ServBay.
   • Katalog główny strony: wybierz folder utworzony w kroku 1 /Applications/ServBay/www/servbay-octobercms-app.

2. Zapisanie konfiguracji i ponowne uruchomienie ServBay

   Zapisz zmiany. ServBay poprosi Cię o ponowne uruchomienie wybranych usług (np. Caddy lub Nginx) oraz być może samego ServBay. Postępuj według instrukcji, aby nowe ustawienia zostały załadowane. ServBay automatycznie przypisze domenę servbay-octobercms.local do adresu lokalnego (127.0.0.1).

Krok 5: Konfiguracja zmiennych środowiskowych OctoberCMS

OctoberCMS (tak jak i Laravel) wykorzystuje plik .env do zarządzania zmiennymi środowiskowymi: m.in. danymi dostępowymi do bazy czy kluczem aplikacji.

1. Skopiuj przykładowy plik konfiguracyjny

   Przejdź do katalogu z projektem (/Applications/ServBay/www/servbay-octobercms-app) i skopiuj plik .env.example jako .env:

   cd /Applications/ServBay/www/servbay-octobercms-app
   cp .env.example .env

2. Edytuj plik .env

   Otwórz plik .env ulubionym edytorem tekstu. Znajdź część konfiguracji dotyczącej bazy danych i zaktualizuj ją zgodnie z danymi z kroku 3:

   # ... inne ustawienia ...
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=october_user  # Zamień na nazwę swojej bazy danych
   DB_USERNAME=october_user  # Zamień na nazwę użytkownika bazy
   DB_PASSWORD=password123   # Zamień na ustawione hasło
   
   # ... inne ustawienia ...

   Ważne: Upewnij się, że wartości DB_DATABASE, DB_USERNAME oraz DB_PASSWORD odpowiadają tym, które podałeś przy tworzeniu bazy w kroku 3.

Krok 6: Uruchomienie instalatora OctoberCMS

OctoberCMS oferuje przystępny graficzny instalator dostępny przez przeglądarkę. Przeprowadzi on przez końcowe etapy (migracje bazy, utworzenie konta administratora itd.).

1. Wejście na stronę instalatora

   W przeglądarce przejdź pod domenę skonfigurowaną w kroku 4, dodając na końcu /install.php, np.:

   https://servbay-octobercms.local/install.php

   Powinien wyświetlić się kreator instalacji OctoberCMS.

2. Podanie danych bazy danych

   Kreator poprosi o dane dostępowe do bazy — wpisz dokładnie te same wartości, które znajdują się w pliku .env:

   • Typ bazy: MySQL
   • Host bazy: localhost lub 127.0.0.1
   • Nazwa bazy: october_user
   • Użytkownik bazy: october_user
   • Hasło: password123

   (Jeszcze raz: użyj rzeczywistego utworzonego przez Ciebie hasła!)

3. Utworzenie konta administratora

   Kolejne kroki instalatora umożliwią wybór danych administratora panelu OctoberCMS: nazwy użytkownika, hasła, adresu e-mail itd.

4. Finalizacja instalacji

   Kliknij „Zainstaluj” lub odpowiedni przycisk. Instalator przeprowadzi migracje, wygeneruje klucz aplikacji i wykona inne niezbędne czynności. Poczekaj na zakończenie procesu.

Krok 7: Instalacja wtyczek i motywów (opcjonalnie)

Po ukończeniu instalacji zaloguj się do panelu administracyjnego OctoberCMS (https://servbay-octobercms.local/backend).

1. Instalacja wtyczek

   W panelu przejdź do „System” -> „Aktualizacje” -> „Wtyczki”. Tutaj możesz wyszukiwać i instalować rozszerzenia z oficjalnego marketplace OctoberCMS, by rozbudować funkcjonalność strony.

2. Instalacja motywów

   Wejdź do „System” -> „Aktualizacje” -> „Motywy” i przeglądaj motywy, spośród których możesz wybrać ten najlepiej dopasowany do Twojego projektu.

Podstawowa konfiguracja i użycie po instalacji

Gdy OctoberCMS jest już zainstalowany, możesz rozpocząć budowę własnej strony. Oto przykładowe pierwsze kroki:

• Przeglądanie strony głównej: Wpisz w przeglądarce https://servbay-octobercms.local/, by zobaczyć frontend (najczęściej z domyślnym motywem).
• Dostęp do panelu admina: Przejdź pod https://servbay-octobercms.local/backend i zaloguj się danymi administratora.
• Tworzenie stron: W panelu wybierz „CMS” -> „Strony”, aby dodawać/edytować podstrony witryny.
• Tworzenie bloków treści: W panelu „CMS” -> „Treść” możesz utworzyć wielokrotnego użytku fragmenty treści.
• Konfiguracja motywu: W „CMS” -> „Motywy” skonfigurujesz bieżący motyw, układy, sekcje itp.
• Zarządzanie użytkownikami i uprawnieniami: W „System” -> „Zarządzanie” kontrolujesz panelowych użytkowników i ich uprawnienia.

Najczęstsze problemy (FAQ)

• P: Po wejściu na servbay-octobercms.local widzę domyślną stronę ServBay lub błąd.
  • O: Sprawdź czy dodałeś stronę servbay-octobercms.local w panelu ServBay oraz czy katalog główny wskazuje na /Applications/ServBay/www/servbay-octobercms-app. Po każdej zmianie w konfiguracji zrestartuj ServBay i upewnij się, że Caddy/Nginx oraz PHP są uruchomione.
• P: Pod adresem https://servbay-octobercms.local/install.php pojawia się pusta strona lub błąd.
  • O: Winne są prawdopodobnie błędy PHP. Sprawdź logi błędów PHP w ServBay. Najczęstsze powody to: niewłaściwe uprawnienia do plików/katalogów (storage, themes, plugins muszą mieć prawo zapisu dla serwera WWW), zła wersja PHP lub brak wymaganych rozszerzeń.
• P: Występuje problem z połączeniem z bazą podczas instalacji.
  • O: Zweryfikuj dokładnie wartości w pliku .env (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD) — muszą się dokładnie zgadzać z tym, co zapisane w phpMyAdmin. Upewnij się, że MySQL/MariaDB jest aktywny w ServBay.
• P: Komenda composer create-project się nie powiodła.
  • O: Sprawdź, czy Composer i PHP są aktywne w ServBay, oraz czy wersja PHP jest odpowiednia. Upewnij się, że masz dostęp do internetu — Composer musi pobrać pliki.

Podsumowanie

Dzięki przyjaznemu środowisku ServBay możesz z łatwością i szybko zainstalować oraz skonfigurować OctoberCMS na macOS. Postępując zgodnie z powyższą instrukcją, zbudujesz profesjonalne, nowoczesne, lokalne środowisko deweloperskie pod swoją stronę www. Teraz możesz zgłębiać bogate możliwości OctoberCMS i tworzyć niesamowite projekty internetowe!