Wdrożenie

Zasada

Frontendy buduj lokalnie i wysyłaj gotowe katalogi. Nie buduj ich na hostingu współdzielonym: przy limicie procesów @tailwindcss/oxide i lightningcss kończą się błędem The global thread pool has not been initialized (EAGAIN), a build panelu Quasar wywraca się na braku bitu +x w node_modules/.bin/.

Wdrożenie

composer prod && phploy --server <nazwa-serwera>

<nazwa-serwera> to nazwa sekcji w phploy.ini. phploy instaluje się globalnie — nie ma go w zależnościach repozytorium.

composer prod buduje oba frontendy po kolei i przerywa na pierwszym błędzie:

npm ci
npm run build:ssr
npm ci --prefix resources/js/cms
npm run build --prefix resources/js/cms

Nie dotyka bazy ani cache'u Laravela.

Najpierw build, potem phploy

phploy układa listę wysyłanych plików na samym początku. Build uruchomiony z hooka pre-deploy[] wysłałby więc poprzednie assety. Z tego samego powodu samo phploy bez composer prod wysyła build, który akurat leży na dysku.

Konfiguracja phploy.ini

Wzór jest w phploy.ini.example. Właściwy phploy.ini zawiera dane serwera i nie trafia do repozytorium.

[dev]
    scheme = sftp
    host = <host>
    user = <użytkownik>
    pass = ""
    path = <katalog-aplikacji-na-serwerze>
    port = 22
    branch = main

    include[] = "public/build"
    include[] = "bootstrap/ssr"
    include[] = "public/cms"

    post-deploy-remote[] = "<php> <composer> install --no-dev --optimize-autoloader"
    post-deploy-remote[] = "<php> artisan storage:link --force"
    post-deploy-remote[] = "<php> artisan migrate --force"
    post-deploy-remote[] = "<php> artisan mb:update-permissions"
    post-deploy-remote[] = "<php> artisan optimize:clear"
    post-deploy-remote[] = "<php> artisan inertia:stop-ssr"
    post-deploy-remote[] = "<php> artisan ssr:ensure"
    post-deploy-remote[] = "bash scripts/prune-assets.sh"

Co dzieje się przy wdrożeniu:

Krok	Wpis	Efekt
phploy	—	wysyłka plików śledzonych przez gita
include[]	public/build, bootstrap/ssr, public/cms	wysyłka całych katalogów buildu przy każdym wdrożeniu (są w .gitignore)
post-deploy-remote[]	composer install --no-dev --optimize-autoloader	zależności PHP
post-deploy-remote[]	artisan storage:link --force	symlink public/storage, przez który serwer HTTP wydaje oryginały plików (/storage/...); --force odtwarza go bez błędu, gdy już istnieje
post-deploy-remote[]	artisan migrate --force	migracje
post-deploy-remote[]	artisan mb:update-permissions	uprawnienia nowych modułów
post-deploy-remote[]	artisan optimize:clear	czyszczenie cache'u
post-deploy-remote[]	artisan inertia:stop-ssr, artisan ssr:ensure	restart serwera SSR
post-deploy-remote[]	bash scripts/prune-assets.sh	usunięcie starych assetów

• post-deploy-remote[] wymaga scheme = sftp; komendy wykonują się w katalogu path.
• Binarkę PHP (8.4) i ścieżkę Composera wpisuj pod konkretny serwer — różnią się między hostingami.
• Nie używaj purge[] ani purge-before[] na katalogach buildu. Pierwszy kasuje świeżo wysłane pliki, drugi usuwa manifest.json przed wysyłką i strona zwraca błąd do końca uploadu.

ssr:ensure nic nie robi przy wyłączonym SSR. Włączanie SSR na serwerze i cron opisuje SSR i scheduler.

Obrazki i cache miniatur

Warianty obrazków (/media/...) Laravel generuje przy pierwszym żądaniu i zapisuje w public/media, a kolejne serwuje już serwer HTTP. Układ adresów opisuje Media: adresy plików i cache miniatur.

• public/media jest w .gitignore, więc phploy go nie wysyła ani nie kasuje. Katalog musi być zapisywalny dla PHP.
• Pierwsze żądanie wariantu musi dotrzeć do index.php. Na testmoonbite.pl zapewnia to szablon vhosta Mooncms Monolit — opisuje go sekcja Serwer HTTP.

Sprzątanie starych assetów

phploy nie usuwa plików wysyłanych przez include[], więc assety z hashem w nazwie zostają na serwerze po każdym buildzie. scripts/prune-assets.sh usuwa z public/build/assets, public/cms/assets i bootstrap/ssr/assets pliki starsze niż 14 dni i wypisuje każdy z nich.

• Bieżący build jest bezpieczny, bo phploy nadpisuje wszystkie jego pliki przy każdym wdrożeniu. 14 dni zostawia stare chunki dla kart otwartych w przeglądarkach.
• Katalog jest sprzątany tylko wtedy, gdy jego plik-znacznik (public/build/manifest.json, public/cms/index.html, bootstrap/ssr/ssr-manifest.json) został wgrany w ciągu ostatniej doby. Uruchomiony bez świeżego wdrożenia skrypt pomija katalog i wypisuje powód, więc nie usunie jedynego builda.
• Nie trzymaj w tych katalogach niczego spoza buildu.

Podgląd bez usuwania:

bash scripts/prune-assets.sh --dry-run