Szczegółowy opis struktury katalogów ServBay

ServBay to lokalne środowisko programistyczne dla macOS, zaprojektowane z myślą o przejrzystej i uporządkowanej strukturze katalogów. Jeśli znasz systemy Linux/Unix, zauważysz, że organizacja plików ServBay przypomina standardowy układ systemów plików znanych z tych systemów, co pozwala łatwo zlokalizować i zarządzać różnego rodzaju plikami.

Zrozumienie struktury katalogów ServBay ma kluczowe znaczenie dla efektywnej pracy, konfiguracji środowiska, diagnozowania problemów i wykonywania kopii zapasowych. W tym artykule szczegółowo omawiamy najważniejsze katalogi i ich zastosowanie.

Przykładowa struktura katalogów instalacji ServBay wygląda następująco:

ServBay
|____backup                 # Katalog kopii zapasowych
| |____config               # Kopie zapasowe konfiguracji
| |____databases            # Kopie zapasowe baz danych
| |____ssl                  # Kopie zapasowe certyfikatów SSL
| |____websites             # Kopie zapasowe stron WWW
|____bin                    # Katalog plików wykonywalnych użytkownika (symlink do package/bin)
|____data                   # Dane wewnętrzne ServBay
| |____servbay              # Kluczowa konfiguracja 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 konfiguracji (symlink do package/etc)
|____logs                   # Katalog logów (symlink do package/var/log)
|____package                # Katalog zainstalowanych paczek
| |____bin                  # Pliki wykonywalne paczek
| |____common               # Biblioteki wspólne i deweloperskie
| | |____imap-uw
| | |____include            # Pliki nagłówkowe (ServBay Development Library)
| | |____lib                # Biblioteki współdzielone i statyczne (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Docelowa lokalizacja plików konfiguracyjnych paczek
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (inne paczki, np. Python, Go, Java, Ruby, Rust itd.)
| |____<package_name>       # Katalog główny każdej paczki
| | |____<major_version>   # Katalog główny wersji
| | | |____<full_version> # Katalog pełnej wersji (zawiera pliki paczki)
| | | |____current         # Symlink do najnowszej pełnej wersji paczki
| | |____...
| |____sbin                 # Systemowe pliki wykonywalne paczek
| |____var                  # Dane zmienne paczek (np. miejsce docelowe logów)
| | |____log                # Docelowe miejsce logów
| | |____run                # Pliki robocze (np. .pid)
|____sbin                   # Systemowe pliki wykonywalne (symlink do package/sbin)
|____script                 # Skrypty zarządzające ServBay
|____ssl                    # Katalog certyfikatów SSL
| |____acme                 # Certyfikaty SSL uzyskane przez ACME
| |____caddy                # Automatycznie wygenerowane certyfikaty Caddy
| |____import               # Importowane przez użytkownika zewnętrzne certyfikaty SSL
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Katalog plików tymczasowych i socketów
|____www                    # Katalog główny stron WWW
| |____servbay              # Przykładowy katalog strony WWW

Poniżej szczegółowo opisujemy rolę każdego katalogu.

Katalog główny ServBay

Domyślna lokalizacja katalogu głównego ServBay to /Applications/ServBay. Wszystkie komponenty, konfiguracje, dane i logi ServBay są przechowywane właśnie tutaj.

Aby zabezpieczyć lokalne środowisko i dane projektowe, zaleca się regularne wykonywanie kopii zapasowych tego katalogu. Można do tego wykorzystać Time Machine lub inne narzędzia backupowe, wykonując pełną kopię /Applications/ServBay.

Katalog główny stron WWW (www)

Główne miejsce na pliki stron WWW to /Applications/ServBay/www. Tutaj umieszczasz wszystkie swoje lokalne projekty stron i serwisów.

Dla zachowania przejrzystości i łatwego zarządzania zaleca się utworzenie osobnego podkatalogu dla każdego projektu lub wirtualnej strony (w ServBay określanej jako „strona”).

Na przykład, jeśli tworzysz strony web.servbay.demo, api.servbay.demo i new.servbay.local, zalecana struktura katalogów może wyglądać tak:

/Applications/ServBay/www
|____servbay.demo           # Pliki dla wszystkich domen *.servbay.demo
| |____web               # Pliki web.servbay.demo
| |____api               # Pliki api.servbay.demo
|____servbay.local          # Pliki dla domen *.servbay.local
| |____new               # Pliki new.servbay.local
|____myproject              # Pliki innych, niezależnych projektów, np. myproject.local

Taki układ pozwala łatwo rozróżnić projekty i domeny, co zdecydowanie ułatwia zarządzanie.

Katalog konfiguracji (etc)

Katalog konfiguracji /Applications/ServBay/etc to naprawdę symlink do /Applications/ServBay/package/etc. Znajdują się tutaj główne pliki konfiguracyjne wszystkich paczek zainstalowanych przez ServBay – m.in. PHP, MariaDB, Nginx, Caddy i innych.

Na co dzień możesz wprost modyfikować pliki w /Applications/ServBay/etc. Po najczęściej wprowadzonych zmianach konieczny jest restart odpowiedniej usługi, by nowe ustawienia zaczęły obowiązywać.

Przykładowe lokalizacje plików konfiguracyjnych popularnych paczek:

PHP (etc/php)

Pliki konfiguracyjne PHP są podzielone na katalogi odpowiadające głównym wersjom języka. Przykładowo, w etc/php znajdziesz katalogi 5.6, 7.4, 8.3 – każdy dla odpowiedniej „dużej” wersji PHP. Typowa struktura:

php
|____5.6                    # Konfiguracja PHP 5.6
| |____conf.d               # Dodatkowe pliki konfiguracyjne rozszerzeń
| |____php.ini              # Główny plik konfiguracyjny PHP
|____7.4                    # Konfiguracja PHP 7.4
| |____conf.d               # Dodatkowe pliki konfiguracyjne rozszerzeń
| |____php-fpm.d            # Konfiguracja puli PHP-FPM
| |____php-fpm.conf         # Główny plik konfiguracyjny PHP-FPM
| |____php.ini              # Główny plik konfiguracyjny PHP
|____8.3                    # Konfiguracja PHP 8.3
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (inne wersje PHP)

Każdy katalog wersji zawiera co najmniej php.ini (główny plik konfiguracyjny PHP), php-fpm.conf (jeśli PHP-FPM jest wspierane dla tej wersji), pear.conf i inne. Po modyfikacji tych plików należy zrestartować odpowiedni serwis PHP-FPM z panelu ServBay lub poleceniem servbayctl.

Katalog conf.d służy do konfiguracji dodatków PHP – np. plików xdebug.ini, opcache.ini, redis.ini i innych. Edytując je, możesz włączać/wyłączać lub konfigurować konkretne rozszerzenia. Po zmianach także wymagany jest restart PHP-FPM.

Uwaga: ServBay projektuje konfiguracje tak, by wszystkie drobne wersje (np. 8.3.3 i 8.3.5) współdzieliły pliki konfiguracyjne w katalogu dla danego „dużego” wydania, np. etc/php/8.3.

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

Konfiguracje baz danych też są pogrupowane wg wersji, np. etc/mariadb/11.2, gdzie znajdziesz główne pliki konfiguracyjne (my.cnf dla MariaDB/MySQL, postgresql.conf dla PostgreSQL). Po zmianach – konieczny restart bazy. Wszystkie drobne wersje z tej samej „dużej” wersji korzystają ze wspólnej konfiguracji.

Zmiana hasła użytkownika root w MariaDB, MySQL czy PostgreSQL odbywa się poprzez dedykowane narzędzia CLI lub funkcje panelu ServBay, nie przez edycję plików konfiguracyjnych.

Caddy (etc/caddy)

Konfiguracja Caddy (Caddyfile) znajduje się w etc/caddy.

Ważna uwaga: ServBay automatycznie generuje i aktualizuje Caddyfile na bazie ustawień stron w panelu zarządzania. Nie edytuj ręcznie tego pliku, bo zmiany zostaną nadpisane przy kolejnym wygenerowaniu konfiguracji. Aby dodać własny fragment do wybranej strony, używaj odpowiednich pól panelu ServBay.

Nginx (etc/nginx)

Główny plik konfiguracyjny nginx.conf znajdziesz w katalogu etc/nginx. Podobnie jak przy Caddy, konfiguracje stron są automatycznie generowane przez ServBay – manualna edycja powinna być wykonywana rozważnie; zwykle wystarczy zarządzać stronami przez panel.

dnsmasq (etc/dnsmasq)

Katalog z plikami dla dnsmasq zawiera dnsmasq.conf (podstawowa konfiguracja) oraz domains.conf (generowany automatycznie dla lokalnych domen przez ServBay).

Ważna uwaga: Oba te pliki – dnsmasq.conf i domains.conf – są tworzone i nadpisywane przez ServBay. Nie edytuj ich ręcznie, bo może to uniemożliwić poprawną obsługę lokalnych nazw domenowych.

Inne konfiguracje paczek

Inne wspierane środowiska, np. Node.js, Python, Go, Java, Ruby, Rust, również mają swoje pliki globalnej lub usługowej konfiguracji w odpowiednich podkatalogach etc, z zachowaniem organizacji wg wersji.

Katalog danych wewnętrznych ServBay (data/servbay)

/Applications/ServBay/data/servbay

To miejsce przechowuje kluczowe pliki konfiguracyjne, statusy oraz ustawienia użytkownika niezbędne do działania samego programu, zarządzania usługami oraz działaniem panelu zarządzania.

Ważna uwaga: Regularnie wykonuj kopie tego katalogu. Nie usuwaj i nie zmieniaj ręcznie żadnych plików w tym miejscu – naruszenie zawartości może uniemożliwić uruchomienie ServBay lub spowodować utratę konfiguracji.

Katalogi plików wykonywalnych i skryptów (bin, sbin, script)

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

Wszystkie pliki wykonywalne są zorganizowane w katalogach bin i sbin (symlinki odpowiednio do package/bin i package/sbin). Znajdziesz tu narzędzia i środowiska uruchomieniowe:

• Popularne narzędzia typu curl, openssl, frpc itd.
• Wersjonowane środowiska językowe: php (domyślny), php-5.6, php-7.4, php-8.3, node i inne; można wywoływać konkretną wersję, podając jej oznaczenie, np. php-8.3.
• Klienty baz danych: mysql, psql, mongosh, redis-cli itd.

Dzięki temu, a także dodaniu katalogów do zmiennej systemowej PATH (przez ServBay przy starcie), możesz łatwo uruchamiać narzędzia i interpretery w terminalu.

Katalog script (/Applications/ServBay/script) przechowuje wewnętrzne skrypty narzędziowe ServBay – do startu/stopu usług, inicjalizacji baz, zadań serwisowych itd. Zazwyczaj nie ma potrzeby uruchamiać ich bezpośrednio – lepszym rozwiązaniem jest użycie narzędzia servbayctl (obecne w /Applications/ServBay/bin), które opakowuje działania skryptów.

Przykład uruchomienia PHP-FPM 7.4:

servbayctl start php 7.4

Katalog plików baz danych (db)

/Applications/ServBay/db

Ten katalog przechowuje faktyczne pliki danych dla każdej zainstalowanej bazy danych. Struktura organizacji jest analogiczna do katalogów konfiguracji – podział wg typu i wersji bazy:

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

Podobnie jak w przypadku konfiguracji: dla każdego „dużego” wydania bazy danych korzysta się ze wspólnej lokalizacji – np. cała seria MariaDB 11.2.x używa tego samego katalogu.

Ważna uwaga: Tutaj trzymane są Twoje wszystkie lokalne bazy danych! Zanim wykonasz krytyczne akcje (upgrade ServBay, migracja systemu) – koniecznie skopiuj cały katalog /Applications/ServBay/db. Funkcja automatycznego backupu ServBay obejmuje również ten katalog.

Katalog logów (logs)

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

Logi wszystkich zintegrowanych usług są agregowane w /Applications/ServBay/logs (symlink do /Applications/ServBay/package/var/log). Taki układ pozwala wygodnie monitorować działanie i błędy poszczególnych komponentów.

Logi są zorganizowane według usług, np.:

• logs/caddy/ lub logs/nginx/: logi dostępu i błędów dla serwerów Caddy/Nginx, często podzielone na katalogi wg domen stron.
• logs/php/: logi PHP-FPM (php-fpm.log), logi błędów uruchomieniowych PHP (errors.log) – te drugie rejestrują krytyczne błędy, których aplikacja sama nie obsłużyła.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: logi błędów, wolnych zapytań i inne dotyczące baz danych.
• Logi innych usług (Python, Go, Java, Ruby, Rust itd.) w odpowiednich podkatalogach.

Uwaga: Logi, szczególnie dzienniki dostępu i błędów, mogą szybko zajmować dużo miejsca – zwłaszcza przy intensywnie rozwijanych projektach. Zalecane jest regularne sprawdzanie i czyszczenie zbędnych logów, aby nie marnować przestrzeni dyskowej.

Katalog paczek (package)

/Applications/ServBay/package

W tym katalogu ServBay instaluje i zarządza wszystkimi paczkami programistycznymi. Każda paczka posiada osobny podkatalog, a strukturę budują poziomy „nazwa_paczki/duża_wersja/pełna_wersja” – np. konkretny PHP w /Applications/ServBay/package/php/8.3/8.3.7.

Przez panel ServBay możesz łatwo instalować, usuwać czy przełączać wersje oprogramowania.

Stare, nieużywane już podwersje można usunąć ręcznie, kasując odpowiedni katalog pełnej wersji (np. /Applications/ServBay/package/php/8.2/8.2.10), by zwolnić miejsce.

Ważna uwaga: W każdym katalogu „dużej” wersji paczki (np. /Applications/ServBay/package/php/8.3) jest symlink o nazwie current – wskazuje na obecnie aktywną (najświeższą) wersję. Nie usuwaj ani nie zmieniaj tego symlinka! W przeciwnym razie ServBay nie znajdzie odpowiednich plików i usługa może się nie uruchomić.

Katalog certyfikatów SSL (ssl)

/Applications/ServBay/ssl

Tutaj przechowywane są wszystkie certyfikaty SSL/TLS:

• Certyfikaty zarejestrowane automatycznie przez ServBay za pośrednictwem protokołu ACME (zwykle w ssl/caddy lub ssl/acme, zależnie od użytego serwera WWW).
• Lokalne certyfikaty CA (ServBay User CA) i certyfikaty publiczne (ServBay Public CA), zazwyczaj w ssl/private oraz ssl/public. Po instalacji tych CA w zaufanych certyfikatach systemu, przeglądarki nie będą ostrzegały przy korzystaniu z HTTPS lokalnie.

Katalog kopii zapasowych (backup)

/Applications/ServBay/backup

W tym miejscu SerbBay zapisuje automatyczne kopie zapasowe. Backup obejmuje kluczowe dane i konfiguracje, w tym:

• backup/config: Kopie plików konfiguracyjnych rdzenia ServBay i konfiguracji paczek.
• backup/databases: Backup danych baz MariaDB, MySQL, PostgreSQL, MongoDB itd.
• backup/ssl: Kopie certyfikatów SSL.
• backup/websites: Backup plików stron z /Applications/ServBay/www.

Warto regularnie przeglądać ten katalog i przenosić istotne archiwa na zewnętrzny dysk, by dodatkowo zabezpieczyć się przed utratą danych.

Katalog tymczasowy (tmp)

/Applications/ServBay/tmp

To miejsce na pliki tymczasowe generowane przez usługi, głównie pliki .pid oraz pliki gniazd (socketów).

• Pliki .pid przechowują PID-y uruchomionych procesów usług.
• Pliki socketów, jak php-cgi.sock, mysql.sock, pgsql.sock, służą do komunikacji procesów (np. php-fpm, baza danych) przez Unix Domain Socket – typowo wydajniejsze i mniej opóźnione niż komunikacja przez porty TCP, szczególnie gdy procesy działają na tym samym komputerze.

Komponenty wspólne i biblioteki developerskie (package/common)

/Applications/ServBay/package/common

Tu znajdziesz biblioteki współdzielone (*.dylib), komponenty wspólne i – opcjonalnie – biblioteki developerskie.

Po zainstalowaniu ServBay Development Library (opcjonalny pakiet z zależnościami kompilacyjnymi) znajdziesz tu katalogi include (nagłówki) i lib (biblioteki statyczne *.a oraz linkingowe *.la). Są one niezbędne m.in. do kompilacji rozszerzeń PHP ze źródła lub buildowania projektów korzystających z bibliotek ServBay.

Ważna uwaga: Nie usuwaj plików *.dylib z katalogu package/common/lib – są one niezbędne do działania zintegrowanego oprogramowania. Ich brak uniemożliwi uruchomienie wielu usług.

Podsumowanie

Struktura katalogów ServBay przejrzyście rozdziela paczki, konfiguracje, dane, logi i pliki stron WWW, nawiązując do konwencji systemów Unix. Takie podejście pozwala zarządzać środowiskiem lokalnym w sposób wygodny i intuicyjny. Znajomość tych katalogów znacząco podniesie efektywność i komfort pracy przy projektach webowych na ServBay. Regularne kopiowanie istotnych katalogów (szczególnie data i db) to podstawa zabezpieczenia rezultatów Twojej pracy przed utratą danych.