Szczegółowy przewodnik po strukturze katalogów ServBay

Wprowadzenie

ServBay to lokalne środowisko programistyczne dla macOS i Windows, którego struktura katalogów jest przejrzysta i logiczna. Jeśli masz doświadczenie z systemami Linux/Unix, szybko zauważysz podobieństwa w organizacji plików, co zdecydowanie ułatwia ich odnajdywanie i zarządzanie nimi podczas pracy deweloperskiej.

Lokalizacja instalacji ServBay

Domyślne ścieżki instalacji ServBay różnią się w zależności od systemu operacyjnego:

• macOS: /Applications/ServBay
• Windows: C:\ServBay

Znajomość struktury katalogów ServBay jest kluczowa dla efektywnego rozwoju, konfiguracji środowiska, rozwiązywania problemów oraz wykonywania kopii zapasowych. W tym dokumencie omówimy najważniejsze katalogi oraz ich zastosowanie.

Typowa struktura katalogów ServBay wygląda następująco:

ServBay
|____backup                 # Katalog kopii zapasowych
| |____config               # Kopie konfiguracji
| |____databases            # Kopie baz danych
| |____ssl                  # Kopie certyfikatów SSL
| |____websites             # Kopie plików stron
|____bin                    # Katalog plików wykonywalnych użytkownika (symlink do package/bin)
|____data                   # Wewnętrzny katalog danych ServBay
| |____servbay              # Kluczowe ustawienia i dane ServBay
|____db                     # Katalog plików baz danych
| |____mariadb              # Pliki danych MariaDB
| |____mongodb              # Pliki danych MongoDB
| |____mysql                # Pliki danych MySQL
| |____postgresql           # Pliki danych PostgreSQL
| |____redis                # Pliki danych Redis
|____etc                    # Katalog plików konfiguracyjnych (symlink do package/etc)
|____logs                   # Katalog logów (symlink do package/var/log)
|____package                # Katalog instalowanych pakietów
| |____bin                  # Pliki wykonywalne pakietów
| |____common               # Wspólne oraz biblioteki programistyczne
| | |____imap-uw
| | |____include            # Pliki nagłówkowe (ServBay Development Library)
| | |____lib                # Biblioteki współdzielone i statyczne (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Faktyczne miejsce przechowywania konfiguracji pakietów
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (Inne jak Python, Go, Java, Ruby, Rust itp.)
| |____<package_name>       # Główny katalog pakietu
| | |____<major_version>   # Katalog głównego wydania
| | | |____<full_version> # Katalog pełnej wersji (wraz z plikami pakietu)
| | | |____current         # Symlink do najnowszej wersji
| | |____...
| |____sbin                 # Systemowe pliki wykonywalne pakietów
| |____var                  # Dane zmienne pakietów (np. prawdziwa lokalizacja logów)
| | |____log                # Faktyczne miejsce przechowywania logów
| | |____run                # Pliki runtime (np. .pid)
|____sbin                   # Systemowy katalog wykonywalny (symlink do package/sbin)
|____script                 # Skrypty zarządzające ServBay
|____ssl                    # Katalog certyfikatów SSL
| |____acme                 # Certyfikaty z ACME
| |____caddy                # Automatycznie generowane certyfikaty Caddy
| |____import               # Importowane przez użytkownika certyfikaty SSL
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Pliki tymczasowe i sockety
|____www                    # Katalog główny stron WWW
| |____servbay              # Przykładowa strona

Poniżej szczegółowo omawiamy znaczenie każdego katalogu.

Katalog główny ServBay

Domyślny katalog główny ServBay znajduje się pod ścieżką /Applications/ServBay. Tutaj przechowywane są wszystkie powiązane pakiety, konfiguracje, dane, logi i inne pliki SerVBaya.

Aby zapewnić bezpieczeństwo systemu oraz danych, zalecamy regularne wykonywanie kopii zapasowych katalogu głównego. Możesz do tego użyć Time Machine lub dowolnego programu do backupu, aby utworzyć pełną kopię katalogu /Applications/ServBay.

Katalog stron WWW (www)

Główne miejsce na pliki stron WWW to /Applications/ServBay/www. Tutaj przechowywane są wszystkie projekty lokalnych stron.

Aby zachować przejrzystość i ułatwić zarządzanie, zalecamy tworzenie osobnych podkatalogów dla każdego projektu lub wirtualnej strony (w ServBay nazywanej „stroną”).

Na przykład, jeśli tworzysz strony web.servbay.demo, api.servbay.demo i new.servbay.local, zalecana struktura to:

/Applications/ServBay/www
|____servbay.demo           # Wszystkie strony z domeny *.servbay.demo
| |____web               # Pliki web.servbay.demo
| |____api               # Pliki api.servbay.demo
|____servbay.local          # Wszystkie strony z domeny *.servbay.local
| |____new               # Pliki new.servbay.local
|____myproject              # Inne projekty, np. myproject.local

Taka struktura ułatwia zarządzanie wieloma stronami i domenami.

Katalog plików konfiguracyjnych (etc)

Katalog /Applications/ServBay/etc to w rzeczywistości symlink do /Applications/ServBay/package/etc. Tutaj przechowywane są najważniejsze pliki konfiguracyjne zainstalowanych pakietów ServBay (np. PHP, MariaDB, Nginx, Caddy itp.).

Zazwyczaj możesz edytować pliki konfiguracyjne bezpośrednio przez tę ścieżkę. Po większości zmian należy zrestartować powiązany serwis, aby nowe ustawienia zadziałały.

Przykłady lokalizacji konfiguracji wybranych pakietów:

PHP (etc/php)

Katalog konfiguracyjny PHP jest dwupoziomowy — rozdziela duże wersje PHP (np. 5.6, 7.4, 8.3). Przykładowa struktura:

php
|____5.6                    # Konfiguracja PHP 5.6
| |____conf.d               # Katalog dodatkowych konfiguracji/rozszerzeń
| |____php.ini              # Główny plik konfiguracyjny PHP
|____7.4                    # Konfiguracja PHP 7.4
| |____conf.d               # Rozszerzenia PHP
| |____php-fpm.d            # Konfiguracja pul FPM
| |____php-fpm.conf         # Główny plik FPM
| |____php.ini              # Główny plik PHP
|____8.3                    # Konfiguracja PHP 8.3
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (Inne wersje PHP)

W katalogu każdej wersji znajdziesz php.ini (główny plik ustawień PHP), php-fpm.conf (gdy obsługiwany), pear.conf itd. Po każdej modyfikacji tych plików należy zrestartować FPM przez panel ServBay lub polecenie servbayctl, by zmiany zadziałały.

W katalogu conf.d znajdziesz ustawienia rozszerzeń, np. xdebug.ini, opcache.ini, redis.ini. Możesz tu włączać, wyłączać lub edytować konfiguracje poszczególnych rozszerzeń. Po modyfikacji konieczny jest restart FPM.

Uwaga: każda mniejsza wersja PHP korzysta z tej samej konfiguracji co duża wersja (np. PHP 8.3.3 i 8.3.5 używają etc/php/8.3).

MariaDB / MySQL / PostgreSQL (etc/mariadb, etc/mysql, etc/postgresql)

Katalog konfiguracji dla baz danych również rozdziela wersje (np. etc/mariadb/11.2). Znajdziesz tu my.cnf (MariaDB/MySQL) lub postgresql.conf (PostgreSQL). Po zmianie konfiguracji wymagany jest restart usługi. Każda duża wersja używa wspólnej konfiguracji.

Aby zresetować hasło roota tych baz, używa się odpowiednich narzędzi lub funkcji panelu ServBay, bez potrzeby modyfikowania plików konfiguracyjnych.

Caddy (etc/caddy)

Główny plik konfiguracyjny Caddy to Caddyfile, dostępny w katalogu etc/caddy.

Ważne: ServBay automatycznie generuje Caddyfile na podstawie Twoich ustawień „stron” w panelu. Nie edytuj ręcznie tego pliku – Twoje zmiany mogą zostać nadpisane. Aby dodać niestandardowe ustawienia Caddy dla strony, korzystaj z panelu ServBay.

Nginx (etc/nginx)

Główny plik konfiguracji Nginx to nginx.conf w katalogu etc/nginx. Podobnie jak w przypadku Caddy, większość ustawień jest generowana automatycznie. Ręczne zmiany wymagają ostrożności, a najlepiej korzystać z panelu ServBay.

dnsmasq (etc/dnsmasq)

Katalog zawiera dnsmasq.conf (domyślne ustawienia) oraz domains.conf (pliki generowane przez ServBay dla lokalnych domen).

Ważne: obydwa pliki są automatycznie generowane i zarządzane przez ServBay, aby prawidłowo rozwiązywać lokalne domeny. Nie edytuj ich ręcznie, bo to może uniemożliwić dostęp do stron lokalnych.

Konfiguracje innych pakietów

W przypadku innych wspieranych przez ServBay pakietów (Node.js, Python, Go, Java, Ruby, Rust itd.) konfiguracje globalne lub serwisowe są także przechowywane w katalogu etc pod odpowiednimi podkatalogami, zgodnie z organizacją wersji.

Wewnętrzny katalog danych ServBay (data/servbay)

/Applications/ServBay/data/servbay

Tu znaleźć można kluczowe pliki konfiguracyjne, stan oraz ustawienia użytkownika, niezbędne do działania aplikacji ServBay, jej panelu sterowania, zarządzania pakietami, stronami oraz bazami danych.

Ważne: Regularnie twórz kopie zapasowe tego katalogu. Nie usuwaj ani nie zmieniaj ręcznie jego zawartości — może to uniemożliwić uruchomienie ServBay lub spowodować utratę konfiguracji.

Pliki wykonywalne i katalogi skryptów (bin, sbin, script)

/Applications/ServBay/bin -> package/bin
/Applications/ServBay/sbin -> package/sbin
/Applications/ServBay/script

Wszystkie narzędzia wykonywalne ServBay znajdują się w bin i sbin (oba są symlinkami do odpowiednich katalogów w package). Znajdziesz tu wiele narzędzi oraz środowisk językowych.

Po uruchomieniu ServBay automatycznie dodaje te katalogi do zmiennej PATH systemu, co pozwala na bezpośredni dostęp z terminala. Obejmuje to m.in.:

• Uniwersalne narzędzia: curl, openssl, frpc itd.
• Wersje języków programowania: php (domyślna wersja), php-5.6, php-7.4, php-8.3, node (domyślna), node-16, node-18, python3, go, java, ruby, rustc itd. Aby skorzystać z konkretnej wersji, należy użyć polecenia zawierającego wersję.
• Klienty baz danych: mysql, psql, mongosh, redis-cli itd.

Katalog script (/Applications/ServBay/script) zawiera skrypty wykorzystywane wewnętrznie przez ServBay – np. do uruchamiania i zatrzymywania usług, inicjalizacji baz czy zadań administracyjnych. Choć możesz wykonać je ręcznie, zaleca się korzystanie z polecenia servbayctl, które udostępnia wygodny interfejs.

Przykład uruchomienia usługi PHP 7.4 FPM:

servbayctl start php 7.4

servbayctl znajduje się w katalogu /Applications/ServBay/bin.

Katalog plików baz danych (db)

/Applications/ServBay/db

Tutaj ServBay zapisuje fizyczne pliki danych wszystkich zainstalowanych baz danych, uporządkowane według typu i wersji pakietu. Przykłady:

• /Applications/ServBay/db/mariadb/<major_version>: MariaDB
• /Applications/ServBay/db/mysql/<major_version>: MySQL
• /Applications/ServBay/db/postgresql/<major_version>: PostgreSQL
• /Applications/ServBay/db/mongodb: MongoDB
• /Applications/ServBay/db/redis: Redis

Pliki danych są współdzielone przez wszystkie mniejsze wersje danej dużej wersji (np. MariaDB 11.2.x korzysta z /Applications/ServBay/db/mariadb/11.2).

Ważne: Ten katalog zawiera wszystkie Twoje lokalne bazy danych. Przed każdą istotną zmianą (np. aktualizacja ServBay, przeniesienie systemu) wykonaj pełną kopię /Applications/ServBay/db. Funkcja automatycznych kopii ServBay obejmuje także ten katalog.

Katalog logów (logs)

/Applications/ServBay/logs -> package/var/log

Wszystkie logi usług pojawiają się w /Applications/ServBay/logs, będącym symlinkiem do /Applications/ServBay/package/var/log. Z tego miejsca można wygodnie odczytywać i monitorować status oraz błędy wszystkich usług.

Logi są zwykle pogrupowane według typu usługi:

• logs/caddy/ lub logs/nginx/: Logi dostępu i błędów Caddy lub Nginx, często grupowane wg domen.
• logs/php/: Logi PHP-FPM (php-fpm.log), logi błędów kodu (errors.log), wyszczególniające błędy nieprzechwycone przez frameworki lub aplikacje.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: Logi błędów, logi wolnych zapytań, itp. dla baz danych.
• Logi innych usług: Python, Go, Java, Ruby, Rust itd. — w osobnych podkatalogach.

Uwaga: Logi (szczególnie logi dostępu i błędów) mogą zajmować dużo miejsca na dysku, szczególnie przy aktywnych projektach. Zalecamy regularną kontrolę i usuwanie niepotrzebnych plików logów, by zwolnić miejsce.

Katalog pakietów (package)

/Applications/ServBay/package

To główne miejsce instalowania i zarządzania wszystkimi pakietami ServBay. Każdy pakiet umieszczony jest w osobnym podkatalogu w strukturze nazwa_pakietu/duża_wersja/pełna_wersja (np. PHP 8.3 znajdziesz w /Applications/ServBay/package/php/8.3/8.3.7).

Z panelu ServBay możesz wygodnie instalować, usuwać lub przełączać wersje pakietów.

Po aktualizacji i rezygnacji ze starszych wersji, możesz ręcznie usunąć katalogi pełnej wersji (np. /Applications/ServBay/package/php/8.2/8.2.10) by zaoszczędzić miejsce.

Ważne: W katalogu duże_wersje (np. /Applications/ServBay/package/php/8.3) zwykle znajduje się symlink current do najnowszej wersji w tej gałęzi. Nie usuwaj ani nie zmieniaj tego symlinku, bo to może uniemożliwić prawidłowe działanie usług.

Katalog certyfikatów SSL (ssl)

/Applications/ServBay/ssl

Katalog służący przechowywaniu wszelkich certyfikatów SSL/TLS:

• Certyfikaty SSL uzyskane przez ServBay automatycznie via protokół ACME (np. w ssl/caddy lub ssl/acme, zależnie od serwera WWW).
• Wygenerowane przez ServBay root CA (ServBay User CA) oraz CA publiczne (ServBay Public CA), najczęściej w ssl/private oraz ssl/public. Po zainstalowaniu CA do zaufanych certyfikatów w systemie, przeglądarki automatycznie uznają certyfikaty wystawiane przez ServBay, eliminując ostrzeżenia HTTPS.

Katalog kopii zapasowych (backup)

/Applications/ServBay/backup

Katalog na pliki kopii zapasowych tworzonych przez ServBay. Wykorzystując funkcje backupu ServBay, możesz łatwo zabezpieczyć kluczowe dane:

• backup/config: Kopie konfiguracji głównej i pakietów.
• backup/databases: Backupy baz MariaDB, MySQL, PostgreSQL, MongoDB itd.
• backup/ssl: Kopie certyfikatów SSL.
• backup/websites: Kopie projektów z katalogu /Applications/ServBay/www.

Regularnie sprawdzaj ten katalog i w razie potrzeby przenoś backupy na zewnętrzne nośniki, aby zapewnić pełne bezpieczeństwo danych.

Pliki tymczasowe (tmp)

/Applications/ServBay/tmp

Przechowywane są tu pliki tymczasowe generowane przez uruchomione usługi, najczęściej .pid oraz pliki socketów.

• Pliki .pid — identyfikatory procesów usług.
• Pliki socket — np. php-cgi.sock, mysql.sock, pgsql.sock itd. Pozwalają na szybki lokalny dostęp przez Unix Domain Socket do takich usług jak PHP-FPM czy bazy danych. Komunikacja poprzez sockety, zamiast TCP, daje większą wydajność i mniejsze opóźnienia przy procesach na tej samej maszynie.

Wspólne komponenty i biblioteki (package/common)

/Applications/ServBay/package/common

Znajdziesz tu wszystkie wspólne komponenty oraz biblioteki wymagane przez zainstalowane pakiety (np. pliki *.dylib) oraz opcjonalne biblioteki dla deweloperów.

Jeśli zainstalujesz ServBay Development Library, pojawią się tu także katalogi include (nagłówki) oraz lib (biblioteki statyczne i linkowane). Są one niezbędne do kompilowania rozszerzeń PHP od źródła lub innych programów wymagających wewnętrznych bibliotek ServBay.

Ważne: Nie usuwaj plików *.dylib z katalogu package/common/lib. Są to kluczowe biblioteki współdzielone, niezbędne do działania komponentów ServBay. Usunięcie ich może spowodować błędy lub brak uruchamiania usług.

Podsumowanie

Struktura katalogów ServBay jednoznacznie rozdziela pakiety, konfiguracje, dane, logi i pliki stron, czerpiąc z najlepszych praktyk systemów Unix. Świadome zarządzanie tymi katalogami zdecydowanie podnosi komfort pracy i efektywność programisty. Nie zapomnij regularnie wykonywać kopii zapasowych najważniejszych katalogów (data, db), by zawsze zabezpieczyć swój lokalny workflow.