diff --git a/README.md b/README.md index b6e9223..e8a0351 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,125 @@ +# 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í, nebo `DEPLOY_ENV=sqlite`), 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, cron/supervisor) | +| `APACHE_DOCUMENT_ROOT` | `${APP_ROOT}/public` | document root (jen apache) | +| `APP_DEBUG` | nenastaveno (alpine: `false`) | řídí opcache a typ `composer install` | +| `PHP_OPCACHE_VALIDATE_TIMESTAMPS` | apache `1`, alpine `0` | 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`, `DEPLOY_ENV` | nenastaveno | spouští přípravu sqlite (`27-sqlite.sh`) | +| `APP_ENV` | alpine `production` | | + +### Rozdíly mezi `v2-latest` (apache) a `alpine-v2-latest` + +- Alpine je PHP-FPM bez web serveru, před něj musí přijít vlastní web server (např. nginx). +- Alpine nastavuje `APP_ENV=production` a `APP_DEBUG=false`, takže `10-opcache.sh` ponechá opcache zapnutou a `15-composer.sh` použije `--no-dev`. +- Alpine používá `docker-php-entrypoint` a nemá `mod_rewrite`. +- 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 -``` \ No newline at end of file +``` diff --git a/v2-fmp-alpine/Dockerfile b/v2-fmp-alpine/Dockerfile index 4b7c15a..be7cafb 100644 --- a/v2-fmp-alpine/Dockerfile +++ b/v2-fmp-alpine/Dockerfile @@ -4,16 +4,12 @@ FROM php:8.4-fpm-alpine ENV APP_ROOT="/var/www/html" ENV TZ="Europe/Prague" \ + PHP_INI_FILE="$PHP_INI_DIR/php.ini" \ COMPOSER_ALLOW_SUPERUSER=1 \ - PHP_OPCACHE_ENABLE=1 \ - PHP_OPCACHE_VALIDATE_TIMESTAMPS=0 \ - PHP_OPCACHE_REVALIDATE_FREQ=0 \ - PHP_OPCACHE_MEMORY_CONSUMPTION=192 \ - PHP_OPCACHE_MAX_ACCELERATED_FILES=20000 \ - PHP_OPCACHE_MAX_WASTED_PERCENTAGE=10 \ - PHP_OPCACHE_INTERNED_STRINGS_BUFFER=16 \ - APP_ENV=production \ - APP_DEBUG=false + PHP_OPCACHE_VALIDATE_TIMESTAMPS="1" \ + PHP_OPCACHE_MAX_ACCELERATED_FILES="10000" \ + PHP_OPCACHE_MEMORY_CONSUMPTION="192" \ + PHP_OPCACHE_MAX_WASTED_PERCENTAGE="10" RUN apk add --no-cache \ tzdata \ @@ -81,29 +77,25 @@ RUN php -r 'if (!in_array("JPEG", Imagick::queryFormats())) { fwrite(STDERR, "ER # Composer COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer -RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \ - && echo "date.timezone=${TZ}" > "$PHP_INI_DIR/conf.d/99-timezone.ini" - -RUN { \ - echo "memory_limit=256M"; \ - echo "upload_max_filesize=100M"; \ - echo "post_max_size=100M"; \ - echo "realpath_cache_size=4096K"; \ - echo "realpath_cache_ttl=600"; \ -} > "$PHP_INI_DIR/conf.d/99-laravel.ini" +# PHP +RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_FILE" && \ + sed -i "s|memory_limit = 128M|memory_limit = 256M |g" "$PHP_INI_FILE" && \ + sed -i "s|upload_max_filesize = 2M|upload_max_filesize = 100M |g" "$PHP_INI_FILE" && \ + sed -i "s|post_max_size = 8M|post_max_size = 100M |g" "$PHP_INI_FILE" && \ + printf '[Date]\ndate.timezone="%s"\n' "$TZ" > "$PHP_INI_DIR/conf.d/tzone.ini" +#OPCACHE RUN { \ echo "[opcache]"; \ - echo "opcache.enable=${PHP_OPCACHE_ENABLE}"; \ - echo "opcache.enable_cli=0"; \ + echo "opcache.enable=1"; \ + echo "opcache.revalidate_freq=0"; \ echo "opcache.validate_timestamps=${PHP_OPCACHE_VALIDATE_TIMESTAMPS}"; \ - echo "opcache.revalidate_freq=${PHP_OPCACHE_REVALIDATE_FREQ}"; \ - echo "opcache.memory_consumption=${PHP_OPCACHE_MEMORY_CONSUMPTION}"; \ - echo "opcache.interned_strings_buffer=${PHP_OPCACHE_INTERNED_STRINGS_BUFFER}"; \ echo "opcache.max_accelerated_files=${PHP_OPCACHE_MAX_ACCELERATED_FILES}"; \ + echo "opcache.memory_consumption=${PHP_OPCACHE_MEMORY_CONSUMPTION}"; \ echo "opcache.max_wasted_percentage=${PHP_OPCACHE_MAX_WASTED_PERCENTAGE}"; \ - echo "opcache.save_comments=1"; \ -} > "$PHP_INI_DIR/conf.d/10-opcache.ini" + echo "opcache.interned_strings_buffer=16"; \ + echo "opcache.fast_shutdown=1"; \ +} > "$PHP_INI_DIR/conf.d/opcache.ini" # Supervisor (queue workers + scheduler, started from entrypoint.d/90-supervisord.sh) RUN mkdir -p /var/log/supervisor