NKSDeploy

Nasazení nové verze webu v Nette vypadá často takhle: na serveru se pustí git pull, pak composer install, sestaví se styly a skripty, smaže cache. Celou tu dobu běží web nad napůl novými soubory. Návštěvník dostane chybu 500, protože knihovny ještě nedojely, nebo stránku se starou šablonou a novým kódem. A když se nová verze nepovede, vrátit tu starou znamená stejný postup pozpátku, ve spěchu a pod tlakem. NKSDeploy je nástroj pro příkazovou řádku, který nasazuje aplikace v Nette Framework bez výpadku a v případě potřeby vrátí předchozí verzi jedním příkazem.

Proč ne FTP ani git pull na serveru

Nahrávání přes FTP a git pull na produkci mají stejnou vadu: mění soubory, ze kterých web právě běží. Obecné nasazovací nástroje tohle řeší, jenže o Nette nic nevědí. Nevědí, že se má před spuštěním zkompilovat DI kontejner a šablony Latte, že se po změně entit generují proxy třídy Doctrine ani že se po přepnutí musí vyčistit OPcache. Tyhle kroky si pak každý projekt dopisuje sám a v každém trochu jinak.

NKSDeploy je má v sobě. Konfigurace je v souboru NEON, tedy ve formátu, který vývojář v Nette zná, a nástroj ji před použitím zkontroluje proti schématu.

Nová verze vedle staré, přepnutí najednou

Každé nasazení vznikne v samostatném adresáři vedle té současné. Stáhne se kód, nainstalují se závislosti, sestaví se front-end, připraví se cache a databáze. Web mezitím dál běží ze staré verze a nic z toho nevidí. Teprve když je nová verze úplně hotová, přepne se na ni web jedinou operací souborového systému. Neexistuje okamžik, kdy by web běžel nad rozdělanou kopií.

Data, která mají přežít nasazení, leží ve sdíleném adresáři a do každé verze se jen připojí: lokální konfigurace, logy, sessions a nahrané soubory. Uživatel tak po nasazení nepřijde o přihlášení a nahrané obrázky nezmizí.

Co nástroj udělá za vývojáře

• Kontroly před nasazením. Ještě před prvním krokem ověří, že v repozitáři nejsou necommitnuté změny, že změněné PHP soubory projdou syntaktickou kontrolou, že se zkompiluje DI kontejner, že schéma Doctrine sedí a že existuje manifest Vite. Když něco neprojde, nasazení se vůbec nespustí.
• Kroky pro Nette a Doctrine. Vyčištění cache, generování proxy tříd, migrace databáze, předkompilace DI kontejneru a šablon Latte proběhnou ještě před přepnutím. První návštěvník po nasazení tak nečeká, až se cache postaví.
• Přeskakování zbytečné práce. Když se nezměnil composer.lock, závislosti se nestahují znovu, ale převezmou se z předchozí verze přes pevné odkazy. Sestavení front-endu se pustí jen tehdy, když se změnily styly, skripty nebo jejich konfigurace. Běžné nasazení drobné opravy tak nestahuje celý svět.
• Po přepnutí. Nástroj šetrně restartuje PHP-FPM, vyčistí OPcache a staré verze nad nastavený počet smaže.
• Zámek. Dvě nasazení na tentýž server najednou neproběhnou, druhé narazí na zámek.

Návrat zpátky automaticky i ručně

Po přepnutí se nástroj zeptá aplikace, jestli žije: zavolá nastavenou adresu kontroly stavu, až třikrát s dvousekundovým odstupem. Když aplikace neodpoví, vrátí web na předchozí verzi, restartuje PHP-FPM, zapíše návrat do historie a nahlásí ho do Sentry, je-li nastavené.

Ručně jde vrátit předchozí verzi, nebo kteroukoli z ponechaných verzí podle jejího označení. Návrat je stejné přepnutí jako nasazení, takže trvá okamžik a nepotřebuje znovu stahovat ani sestavovat. Příkaz status ukáže, která verze běží a které jsou k dispozici, history vypíše historii nasazení.

Háčky pro vlastní kroky

Do pěti míst průběhu jde vložit vlastní PHP kód: před nasazením, před přepnutím, po přepnutí, po dokončení a při návratu. Háček může na serveru spustit příkaz, zapsat do logu nebo sáhnout na konfiguraci. Typicky zapíná a vypíná stránku údržby, posílá zprávu do týmového chatu po úspěšném nasazení, aktualizuje databázová schémata více zákazníků jedné aplikace nebo ohlásí návrat verze. Výsledek nasazení umí nástroj poslat i e-mailem.

Bezpečný nanečisto a v jednom souboru

• Režim --dry-run vypíše kroky, které by proběhly, a u každého, jestli by se spustil, nebo přeskočil.
• Spojení se serverem jde přes SSH s klíčem a SFTP, napsané celé v PHP, takže nepotřebuje žádné rozšíření PHP navíc.
• Nasazovat jde i na stejný stroj, kde nástroj běží.
• Kód se na server dostane jako klon s historií gitu, nebo jako archiv bez ní.
• Monorepo s více aplikacemi zvládne volba, která určí podadresář aplikace.
• Nástroj se dodává jako jeden spustitelný soubor PHAR a umí doplňovat názvy serverů v příkazové řádce.

Začátek ve čtyřech příkazech

Příkaz init vygeneruje šablonu konfigurace, validate ji zkontroluje, setup připraví na serveru adresáře a deploy nasadí. Pro web server stačí jednou namířit kořen webu do adresáře aktuální verze; o zbytek se stará nástroj.

Pro koho to je

• Pro vývojáře a firmy, které provozují aplikace v Nette na vlastních linuxových serverech s PHP-FPM.
• Pro projekty s Doctrine a migracemi, kde nasazení znamená víc než nakopírovat soubory.
• Pro aplikace, u kterých si provozovatel nemůže dovolit chybové stránky během nasazení, třeba e-shopy a rezervační systémy.
• Pro týmy, které chtějí nasazovat stejným postupem na testovací i produkční server, včetně vícero serverů v jedné konfiguraci.

Stav projektu

NKSDeploy je v provozu, první vydání nese označení 0.1.0 a studio jím nasazuje vlastní aplikace v Nette. Vyžaduje PHP 8.3 nebo novější, Composer a přístup na server přes SSH klíčem. Kód kontroluje PHPStan na úrovni 8 a pokrývají ho testy PHPUnit. Nástroj je stavěný na Nette a server s PHP-FPM a přístupem přes SSH; sdílený hosting bez SSH mu nestačí.

Zájem o nasazení

Chcete NKSDeploy pro svůj projekt v Nette, nebo s ním pomoct nastavit nasazování? Napište přes poptávkový formulář nebo na dev@nks-hub.cz.