Merge pull request #90 from jkaninda/dev

Upgrade images to PHP 8.5 and fix php-fpm not starting as root
2026-11-13 16:47:15 +00:00 · 2026-10-21 20:53:47 +02:00
1 parent 033c6b213f
commit 7799d2fbc2
@@ -20,8 +20,10 @@ This Docker image comes with **PHP-FPM**, offering a robust foundation for your
  - **Database**: MySQL and PostgreSQL.  
  - **Caching**: Redis and Memcached.  
  - **Messaging**: Kafka for event-driven architecture.  
-  - **Task Scheduling**: Laravel Scheduler and Cron jobs support.  
- **Custom Configuration**: Pre-configured with sensible defaults, allowing seamless customization.  
+  - **Task Scheduling**: Laravel Scheduler and Queue Worker started automatically (Supervisord).  
+- **Custom Configuration**: Pre-configured with sensible defaults, tunable through environment variables.  
+- **Debian and Alpine variants**, multi-arch (`linux/amd64`, `linux/arm64`).  
+- **Production-ready**: healthcheck, graceful shutdown, OPcache, `supervisorctl` support.  
 - **Event Handling**: Support for advanced event-driven processes.  
 - **Optimized for Microservices**: Built with modern PHP microservices in mind.  

@@ -33,39 +35,48 @@ This image is ideal for developers looking for a streamlined, high-performance s
 - [Github](https://github.com/jkaninda/laravel-php-fpm)
 ---

-## **Supported PHP Versions**
- 8.4  
- 8.3  
- 8.2  
- 8.1  
- 8.0  
- 7.4  
- 7.2  
+## **Supported PHP Versions & Tags**
+
+| PHP | Debian tag | Alpine tag |
+|-----|------------|------------|
+| 8.5 | `8.5`, `latest` | `8.5-alpine`, `alpine` |
+| 8.4 | `8.4` | `8.4-alpine` |
+| 8.3 | `8.3` | `8.3-alpine` |
+| 8.2 | `8.2` | `8.2-alpine` |
+| 8.1 | `8.1` | `8.1-alpine` |
+
+Legacy images (no longer rebuilt automatically, PHP is end-of-life): `8.0`, `7.4`, `7.3`, `7.2`.
+
+> [!NOTE]
+> PHP 8.1 is end-of-life upstream. The image is still built, but please plan an upgrade.

 ---

 ## **Specifications**

 ### **PHP Extensions**
- Composer  
+- Composer 2  
 - OpenSSL  
 - XML  
- PDO (MySQL and PostgreSQL)  
+- PDO (MySQL, PostgreSQL and SQLite)  
 - Rdkafka  
 - Redis  
 - Mbstring  
+- Intl  
+- Exif  
 - PCNTL  
 - ZIP  
- GD  
+- GD (FreeType, JPEG, PNG, WebP)  
 - BCMath  
 - Memcached  
 - Opcache  

 ### **Additional Features**
- Laravel Cron Jobs  
 - Laravel Scheduler  
+- Laravel Queue Worker  
 - Supervisord  
- Node.js and NPM  
+- Node.js 24 LTS and NPM  
+- Git, Zip/Unzip, SQLite CLI  

 ---

@@ -122,7 +133,7 @@ services:

 - **Fix Permissions**  
  ```sh
-  docker compose exec php-fpm chmod -R 777 storage bootstrap/cache
+  docker compose exec -u root php-fpm chown -R www-data:www-data storage bootstrap/cache
  ```

 - **Run Laravel Migrations**  
@@ -135,6 +146,82 @@ services:
  docker exec -it php-fpm bash
  ```

+- **Run a one-off command** (the default supervisor stack is not started)  
+  ```sh
+  docker run --rm -v "$PWD:/var/www/html" jkaninda/laravel-php-fpm composer install
+  ```
+
+- **Restart the queue workers after a deployment**  
+  ```sh
+  docker compose exec php-fpm supervisorctl restart all
+  ```
+
+---
+
+## **Environment Variables**
+
+### Laravel
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LARAVEL_SCHEDULER_ENABLED` | `true` | Run `php artisan schedule:run` every minute |
+| `LARAVEL_QUEUE_WORKER_ENABLED` | `true` | Run `php artisan queue:work` |
+| `LARAVEL_QUEUE_OPTIONS` | `--sleep=3 --tries=3` | Options passed to `queue:work` (e.g. `redis --queue=high,default`) |
+| `LARAVEL_PROCS_NUMBER` | `1` | Number of queue worker processes |
+| `APP_DIR` | `/var/www/html` | Application directory (where `artisan` is looked up) |
+
+The scheduler and queue worker are only started when an `artisan` file is found in `APP_DIR`.
+
+### PHP
+
+| Variable | Default |
+|----------|---------|
+| `PHP_MEMORY_LIMIT` | `256M` |
+| `PHP_UPLOAD_MAX_FILESIZE` | `30M` |
+| `PHP_POST_MAX_SIZE` | `30M` |
+| `PHP_MAX_EXECUTION_TIME` | `30` |
+| `PHP_DATE_TIMEZONE` | `UTC` |
+| `PHP_DISPLAY_ERRORS` | `Off` |
+
+### OPcache
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PHP_OPCACHE_ENABLE` | `1` | |
+| `PHP_OPCACHE_ENABLE_CLI` | `0` | |
+| `PHP_OPCACHE_MEMORY_CONSUMPTION` | `512` | MB |
+| `PHP_OPCACHE_MAX_ACCELERATED_FILES` | `50000` | |
+| `PHP_OPCACHE_VALIDATE_TIMESTAMPS` | `0` | Set to `1` in development so code changes are picked up |
+| `PHP_OPCACHE_REVALIDATE_FREQ` | `0` | |
+
+### PHP-FPM
+
+| Variable | Default |
+|----------|---------|
+| `PHP_FPM_PM` | `dynamic` |
+| `PHP_FPM_PM_MAX_CHILDREN` | `20` |
+| `PHP_FPM_PM_START_SERVERS` | `2` |
+| `PHP_FPM_PM_MIN_SPARE_SERVERS` | `1` |
+| `PHP_FPM_PM_MAX_SPARE_SERVERS` | `3` |
+| `PHP_FPM_PM_MAX_REQUESTS` | `500` |
+
+Container environment variables (e.g. `DB_HOST`, `APP_KEY`) are passed to PHP-FPM workers (`clear_env = no`).
+
+### Development example
+
+```yaml
+services:
+  php-fpm:
+    image: jkaninda/laravel-php-fpm:8.5
+    environment:
+      PHP_OPCACHE_VALIDATE_TIMESTAMPS: 1
+      PHP_DISPLAY_ERRORS: "On"
+      LARAVEL_QUEUE_OPTIONS: "redis --sleep=3 --tries=3"
+      LARAVEL_PROCS_NUMBER: 2
+    volumes:
+      - ./:/var/www/html
+```
+
 ---

 ## **Advanced Usage with Nginx**
@@ -143,7 +230,6 @@ services:
 Example of using a custom nginx config:

 ```yaml
-version: '3'
 services:
  php-fpm:
    image: jkaninda/laravel-php-fpm
@@ -206,7 +292,7 @@ server {

 ### **Dockerfile Example**
 ```Dockerfile
-FROM jkaninda/laravel-php-fpm:8.3
+FROM jkaninda/laravel-php-fpm:8.5
 # Copy Laravel project files
 COPY . /var/www/html
 VOLUME /var/www/html/storage
@@ -240,20 +326,32 @@ stdout_logfile=/var/www/html/storage/logs/kafka.log
 ---

 ## **Custom PHP Configurations**
-Place your custom `php.ini` file at:  
-```
-/usr/local/etc/php/conf.d/
-```
+Most common settings can be changed with [environment variables](#environment-variables).
+For anything else, either:
+
+- mount or copy your own `.ini` file into `/usr/local/etc/php/conf.d/`, or
+- place a `php.ini` file at `conf/php/php.ini` in your project; it is copied into `conf.d` at startup.

 ---

 ## **Storage Permissions Fix**
-If you encounter permission issues, run:  
+`www-data` has UID/GID `1000` in both Debian and Alpine variants. If you encounter permission issues, run:  

 ```sh
-docker compose exec php-fpm /bin/bash
-chown -R www-data:www-data /var/www/html
-chmod -R 775 /var/www/html/storage
+docker compose exec -u root php-fpm chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
+docker compose exec -u root php-fpm chmod -R 775 /var/www/html/storage
+```
+
+To match your host user, rebuild with `--build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g)`.
+
+---
+
+## **Building & Testing Locally**
+
+```sh
+make build-8.5          # Debian image
+make build-8.5-alpine   # Alpine image
+make test               # Integration test (Laravel + MySQL + Nginx)
 ```
 ---