# docker_php_base Základní Docker image pro Laravel aplikace (PHP 8.4). Registr: `git.steelants.cz/steelants/docker_php_base`. Všechny image se buildují pro `linux/amd64` a `linux/arm64` (multi-arch manifest) workflow [`.gitea/workflows/docker-build.yaml`](.gitea/workflows/docker-build.yaml) při push do `main`, každou noc v 1:00 a ručně. ## Přehled image | Tag | Zdrojová složka | Základ | Web server | Stav | |---|---|---|---|---| | `latest` | [`apache/`](apache/) | `php:8.4-apache` | Apache (`mod_rewrite`) | původní verze (v1), beze změny | | `v2-latest` | [`v2-apache/`](v2-apache/) | `php:8.4-apache` | Apache (`mod_rewrite`) | nová verze (v2) | | `alpine-v2-latest` | [`v2-fmp-alpine/`](v2-fmp-alpine/) | `php:8.4-fpm-alpine` | žádný (jen PHP-FPM) | nová verze (v2), v produkci se nepoužívá | Společné pro všechny image: - PHP rozšíření: `pdo_mysql`, `pgsql`, `pdo_pgsql`, `zip`, `opcache`, `pcntl`, `sockets`, `bcmath`, `soap`, `gd` (freetype, jpeg, webp), `intl`, `calendar`, `imagick` (s rsvg). Build selže, když `imagick` nebo `gd` nemají podporu JPEG. - Nástroje: `composer`, `git`, `node` + `npm`, `supervisor`, klienti `mysql` a `psql`. - Časová zóna `Europe/Prague`, `COMPOSER_ALLOW_SUPERUSER=1`. - Kořen aplikace `APP_ROOT=/var/www/html`. - `memory_limit=256M`, `upload_max_filesize` a `post_max_size` `100M`, opcache (`PHP_OPCACHE_*`). - Apache image: document root `APACHE_DOCUMENT_ROOT=${APP_ROOT}/public` (jde přepsat přes `-e`). ## v1: `latest` (složka `apache/`) Původní chování, nic se nemění: - Supervisor konfigurace je statická: `supervisor/supervisord.conf` (`nodaemon=true`, `include conf.d/*.conf`) a `supervisor/conf.d/laravel-queues.conf` (queue workery `default,importstatistics`, `statistics`, `detections`). - Scheduler běží přes **cron**: `* * * * * www-data cd /var/www/html && php artisan schedule:run`, cron se spouští v `apache2-foreground`. - Supervisor se sám **nespouští**. Aplikace ho spouští ze svého `start.sh` (`supervisord -n &`). - Žádné skripty při startu. Veškeré nastavení (`.env`, composer, migrace, cache) dělá `start.sh` aplikace. ## v2: `v2-latest` a `alpine-v2-latest` V2 přesouvá obecné kroky ze `start.sh` aplikace do základního image. Obě v2 varianty mají stejnou strukturu i stejné skripty (`entrypoint.d/`, `supervisor.d/`). ### Jak se spouští 1. Původní příkaz kontejneru (`apache2-foreground`, resp. `docker-php-entrypoint php-fpm`) je upravený: těsně před `exec` volá [`entrypoint-runner.sh`](v2-apache/entrypoint-runner.sh). 2. Runner spustí **v abecedním pořadí všechny spustitelné `/etc/entrypoint.d/*.sh`**. Každý běží jako samostatný proces (proměnné se mezi skripty nepředávají). 3. **Selže-li skript, start se zastaví** (`entrypoint script failed: `, kontejner skončí). Ostatní skripty ani web server se nespustí. 4. **Zpětná kompatibilita:** pokud v kořeni aplikace existuje `start.sh` (`$APP_ROOT/start.sh`), runner se přeskočí a `entrypoint.d` se nespustí. Image se starým `start.sh` tak nedostane nové skripty. 5. Pro alpine image platí totéž, jen runner běží ze stock `docker-php-entrypoint`, takže projde každý příkaz (i `docker run image php -v`). Skripty v kontejneru bez aplikace (bez `artisan`, `composer.json`) proto končí kódem 0. ### Skripty v `/etc/entrypoint.d/` (pořadí spouštění) | Skript | Co dělá | Poznámka | |---|---|---| | `05-permissions.sh` | `chown -R www-data:www-data` na `storage` a `bootstrap/cache`, jen když je vlastník horní složky jiný | namountované volume bývá root-owned | | `10-opcache.sh` | `APP_DEBUG=false` → nastaví `opcache.validate_timestamps=${PHP_OPCACHE_VALIDATE_TIMESTAMPS:-1}`; jinak (i když `APP_DEBUG` není nastavené) → `opcache.enable=0` | upravuje `*opcache.ini` v `$PHP_INI_DIR/conf.d` | | `15-composer.sh` | bez `composer.json` nic; jinak `composer install --prefer-dist --optimize-autoloader` (s dev závislostmi při `APP_DEBUG=true`), jinak s `--no-dev` | běží při **každém** startu, vyžaduje síť. `$init` se nepředává, rozhoduje jen `APP_DEBUG` | | `20-env.sh` | existuje `/config/.env` → zkopíruje ho do `.env`; jinak, chybí-li `.env` a je `.env.example`, vytvoří `.env` z příkladu a uloží do `/config/.env` | jen s `artisan`, `/config` je vždy volume | | `25-key.sh` | `php artisan key:generate --force --no-interaction` jen když `APP_KEY` není v prostředí ani v `.env`; vygenerovaný `.env` uloží do `/config/.env` | existující klíč nikdy nepřepíše | | `26-cache.sh` | `cache:clear`, `config:clear`, `route:clear`, `view:clear` | jen s `artisan`. Při `CACHE_STORE=database` běží před migracemi | | `27-sqlite.sh` | je-li sqlite (`DB_CONNECTION=sqlite` v `.env` i v prostředí), vytvoří prázdný `database/database.sqlite` | složka `database/` musí existovat | | `30-storage.sh` | `php artisan storage:link` | jen s `artisan` | | `35-migrate.sh` | `php artisan migrate --force --no-interaction` | běží při **každém** startu každého kontejneru, tedy i workerů a replik | | `90-supervisord.sh` | zapíše `/etc/supervisor/supervisord.conf` (`nodaemon=true`, `include /etc/supervisor/conf.d/*.conf`) a spustí `supervisord` na pozadí | | Vlastní skript aplikace přidáš do `/etc/entrypoint.d/` s vhodným číslem (soubor musí končit `.sh`, být spustitelný a používat `#!/bin/sh`). Chceš-li skript vypnout, smaž ho (`RUN rm /etc/entrypoint.d/35-migrate.sh`). ### Supervisor (`/etc/supervisor/conf.d/`) Soubory ze složky `supervisor.d/` se kopírují do `/etc/supervisor/conf.d/` a supervisor načte všechny `*.conf`: - `laravel-queues.conf`: tři queue workery (`default,importstatistics`, `statistics`, `detections`), `user=www-data`, `autorestart`. - `laravel-scheduler.conf`: `php artisan schedule:work` (vyžaduje Laravel 8+). **Nahrazuje cron**, ten v2 neobsahuje. - `reverb.conf.example`: příklad programu `reverb:start --host=0.0.0.0 --no-interaction --debug`. Nenačítá se (přípona `.example`). Zapneš ho tak, že ho zkopíruješ jako `reverb.conf`. Cesty ke `artisan` se berou z `%(ENV_APP_ROOT)s`. Programy lze přidat nebo přepsat vlastními soubory v `conf.d`. ### Volume - `/config`: perzistentní `.env` a `APP_KEY` (viz `20-env.sh`, `25-key.sh`). Bez připojeného volume se `.env` a vygenerovaný klíč ztratí při novém kontejneru. Spolehlivější je nastavit `APP_KEY` jako proměnnou prostředí. - `storage/app` volume si deklaruje aplikace sama. ### Proměnné prostředí | Proměnná | Výchozí | Význam | |---|---|---| | `APP_ROOT` | `/var/www/html` | kořen aplikace (skripty, supervisor) | | `APACHE_DOCUMENT_ROOT` | `${APP_ROOT}/public` | document root (jen apache) | | `APP_DEBUG` | nenastaveno | řídí opcache a typ `composer install` | | `PHP_OPCACHE_VALIDATE_TIMESTAMPS` | `1` | použije se při `APP_DEBUG=false` | | `PHP_OPCACHE_*` | viz Dockerfile | velikosti opcache | | `APP_KEY` | nenastaveno | je-li nastavená, klíč se negeneruje | | `DB_CONNECTION` | nenastaveno | spouští přípravu sqlite (`27-sqlite.sh`) | ### Rozdíly mezi `v2-latest` (apache) a `alpine-v2-latest` Chování je záměrně stejné: stejné výchozí proměnné prostředí, stejné `php.ini` (`memory_limit=256M`, `upload_max_filesize=100M`, `post_max_size=100M`, časová zóna), stejný `opcache.ini`, stejné skripty v `entrypoint.d/` a stejné supervisor programy. Liší se jen to, co vyplývá z technologie: - Alpine je PHP-FPM bez web serveru, před něj musí přijít vlastní web server (např. nginx). Nemá `mod_rewrite` ani `APACHE_DOCUMENT_ROOT`. - Runner běží z jiného místa: apache v `apache2-foreground`, alpine ve stock `docker-php-entrypoint` (projde tedy každý příkaz, i `docker run image php -v`). - Alpine je postavený na musl a `apk`, apache na Debianu a `apt`. Verze `node`, `git` a klientů se mohou lišit. Composer se do alpine kopíruje z image `composer:2`. - Apache image navíc zapisuje `printenv` do `/etc/environment` (zbytek po cronu z v1, ve v2 není potřeba). - Alpine image se v produkci nepoužívá, byl ověřen jen testy na atrapě `artisan`. ## Migrace aplikace na v2 (podklad pro AI) Postup pro aplikaci, která dnes dědí z `docker_php_base:latest` a má vlastní `start.sh` s `CMD ["/var/www/html/start.sh"]`: 1. V `Dockerfile` změň `FROM` na `git.steelants.cz/steelants/docker_php_base:v2-latest`. 2. Smaž `start.sh` a řádky `RUN chmod +x /var/www/html/start.sh` a `CMD ["/var/www/html/start.sh"]`. Výchozí příkaz `apache2-foreground` už spouští `entrypoint.d`. Dokud `start.sh` v `APP_ROOT` existuje, v2 skripty se nespustí. 3. Smaž z `Dockerfile` to, co už je v základu: `RUN mkdir -p /config`, `VOLUME /config` a `docker-php-ext-install calendar` (`calendar` je v základu). `VOLUME` pro `storage/app` nech v aplikaci. 4. Z původního `start.sh` už jsou v základu: příprava `.env` z `/config`, generování `APP_KEY`, sqlite, `composer install`, `storage:link`, `migrate`, `*:clear`, úprava opcache a spuštění supervisoru. 5. V základu **není**: `config:cache`, `route:cache`, `view:cache` pro produkci, a `init` (rozlišení prvního startu pro composer). Pokud je aplikace potřebuje, přidej vlastní skript, např. `entrypoint.d/50-optimize.sh` (běží po `26-cache.sh`), a zkopíruj ho `COPY --chmod=755 entrypoint.d/ /etc/entrypoint.d/`. 6. Reverb (`php artisan reverb:start ... &` v `start.sh`) nahraď souborem `/etc/supervisor/conf.d/reverb.conf` (zkopíruj z `reverb.conf.example`). Řádek se `&` ze `start.sh` odstraň, jinak poběží dvakrát. 7. Odstraň ze `start.sh`/Dockeru vlastní spouštění `supervisord`. `90-supervisord.sh` ho spouští sám, dva supervisory by znamenaly duplicitní workery i scheduler. 8. Cron už v základu není a scheduler běží přes supervisor (`schedule:work`, Laravel 8+). Aplikace, která dřív spoléhala na cron z `latest` a nespouštěla supervisor, scheduler při přechodu ztratí. Na co si dát při migraci pozor: - Skripty jsou **fail-fast**. Chyba migrace, composeru nebo `cache:clear` zastaví start kontejneru. - Migrace běží při každém startu každého kontejneru. U více replik se mohou přetahovat o zámek. - `composer install` běží při každém startu a potřebuje síť. Pokud je `vendor` hotový v buildu, zvaž smazání `15-composer.sh`. - `10-opcache.sh` vypíná opcache i tehdy, když `APP_DEBUG` není nastavené. Nastav `APP_DEBUG=false`, chceš-li opcache v produkci. - Skripty byly ověřeny na atrapě `artisan` a prázdném projektu, ne na plné Laravel aplikaci. ## Ruční build ```bash docker build --platform linux/arm/v7,linux/arm64/v8,linux/amd64 -t git.steelants.cz/steelants/docker_php_base:latest ./apache docker build -t git.steelants.cz/steelants/docker_php_base:v2-latest ./v2-apache docker build -t git.steelants.cz/steelants/docker_php_base:alpine-v2-latest ./v2-fmp-alpine docker push git.steelants.cz/steelants/docker_php_base:latest ```