MoonDocs

Motyw

Pierwsze kroki ​

Wymagania ​

  • PHP 8.4 i Composer.
  • Działający serwer MySQL lub MariaDB i użytkownik z niepustym hasłem oraz prawem tworzenia baz. Instalator nie przyjmuje pustego hasła.
  • Node.js 24 (także dla instalacji i builda panelu).
  • Klucz SSH z dostępem do repozytoriów Moonbite na Bitbuckecie — instalator pobiera panel przez SSH.
  • Interaktywny terminal — instalator zadaje pytania.

Nowy projekt ​

Projekt powstaje jako klon bazowego repozytorium, w którym origin zostaje zamieniony na upstream:

bash
git clone --branch main git@bitbucket.org:moonbite/mooncms-monolit.git {folder-projektu}
cd {folder-projektu}
git remote rename origin upstream
git remote add origin git@bitbucket.org:moonbite/{nazwa-nowego-repozytorium}.git
git push -u origin main

Repozytorium projektu utwórz na Bitbuckecie bez domyślnego .gitignore.

Aktualizacje z bazowego repozytorium ​

bash
bash scripts/merge-upstream.sh

Skrypt pobiera upstream/main i scala go z bieżącą gałęzią, zachowując lokalną wersję panelu w resources/js/cms. Wymaga czystego drzewa roboczego. Jeśli zostaną konflikty, wypisze je i zostawi merge do ręcznego dokończenia.

Instalacja ​

bash
composer app:install

Instalator kolejno:

  1. instaluje zależności PHP, tworzy .env z .env.example (jeśli go nie ma) i generuje klucz aplikacji,
  2. pyta o nazwę aplikacji, jej adres, języki witryny i dane bazy,
  3. wykonuje migracje i synchronizuje uprawnienia,
  4. pyta, czy wgrać dane demo,
  5. pobiera panel z mooncms-frontend do resources/js/cms (mb:install-cms),
  6. instaluje zależności Node i buduje motyw.

Na co uważać przy pytaniach instalatora:

  • Adres aplikacji. Podpowiedź jest wyliczana z nazwy aplikacji (np. http://cms.lh) i zakłada lokalną domenę. Jeśli pracujesz na php artisan serve, wpisz http://127.0.0.1:8000.
  • Baza. Bazy nie trzeba zakładać wcześniej — migracje zaproponują jej utworzenie.
  • Panel. Bez klucza SSH do Bitbucketa mb:install-cms kończy się błędem, a instalator przerywa pracę przed instalacją zależności Node i buildem motywu. Po naprawieniu dostępu uruchom instalator ponownie.

Po instalacji uruchom projekt przez composer dev — zob. Praca lokalna. Bez builda motywu (npm run build) strona główna zwraca błąd 500 (Vite manifest not found), a bez zbudowanego panelu to samo dzieje się pod /cms.

Instalacja ręczna ​

Te same kroki bez pytań instalatora; .env uzupełnij samodzielnie przed migracjami.

bash
cp .env.example .env
composer install
php artisan key:generate
php artisan migrate
php artisan mb:update-permissions
npm install
npm run build
php artisan mb:install-cms

Co robi mb:install-cms ​

Komenda klonuje mooncms-frontend do resources/js/cms, instaluje jego zależności, generuje pliki .env.* panelu z adresem API /api (panel działa pod tą samą domeną co API) i buduje panel do public/cms.

Domyślnie usuwa też katalog .git panelu oraz wpis resources/js/cms z .gitignore, więc w projekcie panel staje się zwykłym katalogiem śledzonym razem z resztą kodu. Opcja --keep-git zostawia panel jako osobne repozytorium.

Konfiguracja .env ​

Instalator ustawia nazwę, adres, języki i bazę. Zmienne specyficzne dla monolitu:

ZmiennaDziałanie
APP_URLAdres aplikacji; domyślnie http://127.0.0.1:8000.
APP_FRONT_URLAdres dev servera panelu; domyślnie http://127.0.0.1:8080. mb:install-cms bierze z niego host do plików .env panelu.
DB_*Połączenie z bazą MySQL/MariaDB.
SITE_LOCALESJęzyki witryny po przecinku, np. pl,en. Zob. Języki i adresy.
SITE_DEFAULT_LOCALEJęzyk bez prefiksu w adresie. Puste oznacza APP_LOCALE.
SITE_STRUCTURED_DATAWłącza dane strukturalne JSON-LD; domyślnie true.
QUEUE_CONNECTIONSterownik kolejki; domyślnie database.
INERTIA_SSR_*Renderowanie serwerowe, domyślnie wyłączone. Zob. SSR i scheduler.

Pozostałe zmienne to standardowa konfiguracja Laravela.

Testy i kontrola jakości ​

bash
php artisan test      # testy Pest
npm run check         # lint i formatowanie motywu
npm run types:check   # typy TypeScript
npm run build:ssr     # build klienta i SSR

Testy korzystają z serwera MySQL z .env i bazy o nazwie testing (ustawienie w phpunit.xml). Baza powstaje sama, jeśli użytkownik ma prawo tworzenia baz.

Przed oddaniem zmiany uruchom php artisan test dla zmian backendu, a dla zmian motywu npm run build:ssr, npm run types:check i npm run check. Po zmianach panelu zbuduj go z katalogu resources/js/cms.

Made by Moonbite