Az elmúlt hetekben egy évek óta cPanelen futó PHP alkalmazást költöztettünk konténerekbe. A cél az volt, hogy a fejlesztői, a teszt- és az éles környezet ugyanabból a leírásból álljon elő, és hogy egy git push után emberi beavatkozás nélkül kikerüljön az új verzió. Ebben a cikkben azt írom le, hogyan épül fel a megoldás, és milyen buktatókba futottunk bele, mert ezekből tanultunk a legtöbbet.

Miből áll a rendszer

  • Alkalmazás: PHP-FPM és Nginx külön konténerben, mellettük Redis a munkameneteknek és Solr a keresésnek.
  • Infrastruktúra-repó: a Dockerfile-ok, a compose fájlok és a pipeline egy külön Git repóban élnek, nem az alkalmazás kódja mellett.
  • Build: GitLab CI építi az image-eket, és a GitLab Container Registrybe tölti fel őket.
  • Futtatás: Docker Compose stackek, amelyeket Portainer kezel.
  • Forgalom: Traefik fogadja a kéréseket, és Let’s Encrypt tanúsítványt intéz minden környezetnek.
  • Adatbázis: külön kiszolgálón fut, a stack csak csatlakozik hozzá.

Külön repó az infrastruktúrának

A Docker- és CI-leírásokat szándékosan nem tettük az alkalmazás repójába. Ennek fő oka a felelősség szétválasztása: az alkalmazás repójának a fejlesztőcsapat a gazdája, az infrastruktúra-repónak pedig mi, az üzemeltetők. Mindenki a saját repójában dönt és hagy jóvá változtatást. A fejlesztőknek nem kell az üzemeltetési beállításokkal foglalkozniuk, mi pedig nem nyúlunk az alkalmazás kódjához.

A szétválasztásnak gyakorlati haszna is van. Az alkalmazás repója tiszta kód marad, az üzemeltetési változtatásoknak pedig saját története van: minden módosítás egy commit, amelyet vissza lehet nézni és vissza lehet vonni.

Ez azért működik, mert a Dockerfile-nak és a build kontextusnak nem kell egy helyen lennie. A pipeline letölti az alkalmazás kódját, azt adja meg kontextusnak, a Dockerfile-t pedig az infrastruktúra-repóból veszi. A php.ini és az Nginx konfiguráció egy második, névvel ellátott kontextusból érkezik:

docker build \
  --build-context infra=. \
  -f docker/php-fpm/Dockerfile \
  -t registry.example.com/app/php-fpm:dev-1a2b3c4 \
  app

A Dockerfile-ban ezekre a fájlokra COPY --from=infra hivatkozik.

Pipeline: a pushtól a futó konténerig

Az alkalmazás GitHubon van, a build GitLabon fut. Egy sima GitHub webhook erre nem elég, mert a két rendszer más formátumot vár. Ezért az alkalmazás repójában egyetlen apró workflow hívja meg a GitLab trigger API-ját, és átadja a pontos commit azonosítót meg az ág nevét. A pipeline így biztosan azt a commitot építi, amelyet feltoltak.

Minden image két címkét kap:

  • az ág nevét (dev, test, prod), amely mindig a legfrissebb buildre mutat;
  • az ág nevét és a commit rövid azonosítóját (dev-1a2b3c4), amely soha nem változik.

A build után a deploy lépés meghívja a környezet Portainer webhookját, és paraméterként átadja a commit azonosítót:

curl --request POST "$WEBHOOK?APP_SHA=$APP_SHA"

A compose fájl ebből rakja össze az image címkéjét:

image: registry.example.com/app/php-fpm:${ENVIRONMENT}${APP_SHA:+-${APP_SHA}}

Eleinte csak az ág nevét használtuk címkének. Ez kényelmes, de nem derül ki belőle, pontosan melyik verzió fut, és a visszaállás is körülményes. A commit azonosítóval a futó verzió egyértelmű, a visszaállás pedig egy újratelepítés egy korábbi azonosítóval.

A webhook címe környezetenként más. Ezt a GitLab környezethez kötött változói oldják meg: a deploy job megadja, melyik környezetbe telepít, a GitLab pedig az ahhoz tartozó WEBHOOK értéket adja át. A pipeline-ban így egyetlen változónév szerepel.

Több környezet egy kiszolgálón

A stack minden nevében szerepel a környezet: a projekt, a konténerek, a hálózat és a Traefik útvonalak nevében is. Ezért a dev és a test gond nélkül fut egymás mellett ugyanazon a gépen, ugyanazon Traefik mögött. Környezetenként csak néhány érték tér el, például a domain és a kifelé nyitott portok.

A Solr és az adatbázis nem érhető el az internetről. Ezekhez környezetenként egy WireGuard VPN ad hozzáférést: a kliens csak a szükséges címeket éri el az alagúton át, minden más forgalma a megszokott úton megy.

Amibe belefutottunk

Az Nginx el sem indult. Egy rewrite szabály reguláris kifejezésében {2} szerepelt. Az Nginx a kapcsos zárójelet blokk kezdetének értelmezi, ezért az ilyen kifejezést idézőjelbe kell tenni.

Az állapotellenőrzés mindig hibát jelzett. Alpine alapú image-ben a localhost IPv6 címre oldódott fel, az Nginx viszont csak IPv4-en figyelt. A megoldás: 127.0.0.1 a localhost helyett.

Az ütemezett feladatok nem futottak volna. A cron feladatokat egy külön konténer futtatja ugyanabból az image-ből, saját CPU- és memóriakorláttal, hogy ne a látogatók elől vegye el az erőforrást. Az ütemező viszont proc_open hívással indítja a feladatokat, amit a php.ini biztonsági okból tilt. A cron konténer ezért egy kiegészítő beállítást kap, amely csak ott engedélyezi ezt a függvényt, a webes oldalon a tiltás megmarad.

A health végpont akkor is 200-at adott, ha az adatbázis nem volt elérhető. A hibát csak a válasz szövege jelezte. Most 503-at ad, így a konténer állapota és a külső figyelés is észreveszi a bajt.

A konténernaplók korlát nélkül nőttek. A Docker magától nem forgatja a naplókat. Minden szolgáltatás méretkorlátot kapott, mielőtt megtelt volna a lemez.

A feltöltési korlát két helyen él. A PHP-ban megemelt érték mit sem ért, amíg az Nginx alacsonyabb korlátja előbb visszautasította a kérést. A két értéket együtt kell állítani.

Egy könyvtár rossz tulajdonoshoz került. Az adatokat a kiszolgáló /data/<környezet>/ könyvtáraiban tároljuk, hogy egyszerű legyen a mentés, és egy elgépelt docker compose down -v ne törölhesse őket. Közben derült ki, hogy az üres kötet tulajdonosát minden image átállítja, amelyik felcsatolja, akkor is, ha csak olvasásra teszi. A később induló Nginx így root tulajdonba vette a feltöltések egyik könyvtárát, és a PHP nem tudott bele írni. A megoldás a nocopy beállítás a csak olvasó csatolásokon.

A Traefik biztonsági figyelmeztetést írt a naplóba. Egy friss sérülékenység (CVE-2026-88011) miatt az X.Forwarded.For formájú fejléceket a PHP ugyanannak olvassa, mint az X-Forwarded-For fejlécet, így a kliens meghamisíthatná a proxy által beállított értékeket. Nálunk az Nginx alapbeállítása eleve eldobta ezeket, de a Traefikben is bekapcsoltuk a szűrést, hogy a védelem ne egyetlen alapértelmezésen múljon.

Mit vittünk haza ebből

  • Érdemes mindent kipróbálni, mielőtt élesbe kerül. A fenti hibák többsége nem a dokumentációból derült ki, hanem abból, hogy a változtatást valódi konténereken futtattuk le.
  • A hallgatólagos alapértelmezések a legveszélyesebbek. A naplóforgatás hiánya, a kötetek tulajdonosa és a mozgó image címke mind addig működik, amíg egyszer nem.
  • A költöztetés leltár is. A régi környezet sok mindent csendben megoldott, például a levélküldést és a mentést. Konténerben ezekről külön gondoskodni kell, ezért ezeket a hiányokat időben fel kell térképezni.

A rendszer ma úgy működik, hogy egy feltolt commit néhány perc múlva fut a megfelelő környezetben, és bármikor megmondható, pontosan melyik verzió van kint. Ha hasonló költöztetés előtt áll, és segítségre van szüksége, keressen minket.