Skip to content
shinsenterPublic

Latest commit

Β 

History

220 Commits

Folders and files

Repository files navigation

PHP Docker Images

πŸ“¦ (PHP) Lightweight images for PHP 5.6 to 8.6, on Debian and Alpine, ready to run

Build all Watch updates

Important

Sponsors open in 2027. The project plans to open a sponsors program in 2027. Details will be announced here before it starts. Until then you can already support the project with a donation or a GitHub sponsorship.

Table of Contents

Introduction

shinsenter/php

These images are based on the official PHP Docker images and make it easy to change PHP and PHP-FPM settings using environment variables. No image rebuild required.

They include the latest Composer and common web servers - Apache2, Nginx, RoadRunner, and FrankenPHP - so you don't need to install them separately.

Note

We slim these images down with the docker-squash project, so pulls are faster and they use less disk and memory than the official images they're based on.

New builds use zstd layer compression, which makes images smaller to pull. Pulling them needs Docker Engine 23.0 or later, or containerd 1.5 or later (Kubernetes included). On an older runtime the pull fails. A tag that has not been rebuilt yet keeps its gzip layers.

Quick start

# Check the PHP version
docker run --rm shinsenter/php:8.5-cli php -v

# Serve a project with PHP-FPM and Nginx, then open http://localhost
docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v ./myproject:/var/www/html \
    shinsenter/php:8.5-fpm-nginx
  • Your code goes in /var/www/html.
  • Change PHP settings with PHP_* variables, for example -e PHP_MEMORY_LIMIT=512M. See Environment variables.
  • Mount an empty folder and set -e INITIAL_PROJECT=laravel/laravel to create a new project on first start.
  • Test HTTPS certificates are built in. See HTTPS.

Getting Started

Docker image variants

Tags cover PHP versions from 5.6 to 8.6-rc and come in cli, zts, fpm, fpm-nginx, fpm-apache, roadrunner(1), and frankenphp(2) variants. Both Debian and Alpine builds are available.

Examples:

  • shinsenter/php:8.3-cli
  • shinsenter/php:8.4-zts
  • shinsenter/php:8.5-fpm
  • shinsenter/php:8.1-fpm-apache
  • shinsenter/php:8.2-fpm-nginx
  • shinsenter/php:8.3-roadrunner (1)
  • shinsenter/php:8.4-frankenphp (2)

(1) RoadRunner variant - requires PHP >= 8.0.
(2) FrankenPHP variant is BETA - requires PHP >= 8.2.

See all tags on our Docker Hub.

Which tag should I use?

I want to Tag Notes
Run scripts, workers or Composer cli Runs php and exits
Use thread-safe PHP zts For extensions that need ZTS
Put PHP-FPM behind my own web server or ingress fpm Listens on port 9000
Get a ready web server fpm-nginx Nginx + PHP-FPM, ports 80 and 443
Use Apache and .htaccess fpm-apache Apache + PHP-FPM, ports 80 and 443
Use a long-running app server roadrunner PHP 8.0 or newer
Use a Caddy-based app server frankenphp PHP 8.2 or newer, beta

Pick -alpine for the smallest size, or the Debian default for the widest package support. The tags of every variant are listed on Docker Hub.

Ready-made application images

Images for popular frameworks and applications install the project for you on first start (mount an empty folder). The list and examples are in docs/applications.md.

Configuration

Environment variables

You can configure PHP and PHP-FPM using environment variables instead of rebuilding images.

Naming rules:

This convention lets you map any environment variable straight back to its ini/fpm directive.

Note

By default, $PHP_* variables are applied only if set before the container starts. To allow changing PHP settings from an interactive shell inside a running container, start the container with ALLOW_RUNTIME_PHP_ENVVARS=1.

Tip

Run php-envvars inside the container to list the default $PHP_* variables.

Examples

Command Line
docker run \
    -v ./myproject:/var/www/html \
    -e PHP_DISPLAY_ERRORS='1' \
    -e PHP_POST_MAX_SIZE='100M' \
    -e PHP_UPLOAD_MAX_FILESIZE='100M' \
    -e PHP_SESSION_COOKIE_HTTPONLY='1' \
    shinsenter/php:8.5 php -i
With docker-compose.yml
services:
  web:
    image: shinsenter/php:8.5-fpm-nginx
    environment:
      PHP_DISPLAY_ERRORS: "1"
      PHP_POST_MAX_SIZE: "100M"
      PHP_UPLOAD_MAX_FILESIZE: "100M"
      PHP_SESSION_COOKIE_HTTPONLY: "1"
Explanation
Environment Variable What it does Equivalent php.ini / fpm setting
PHP_DISPLAY_ERRORS=1 Show errors during development display_errors = 1
PHP_POST_MAX_SIZE=100M Set max POST size (default 8M) post_max_size = 100M
PHP_UPLOAD_MAX_FILESIZE=100M Set max upload file size (default 2M) upload_max_filesize = 100M
PHP_SESSION_COOKIE_HTTPONLY=1 Enable HttpOnly on session cookies session.cookie_httponly = 1

Customizing PHP-FPM

The images start PHP-FPM with one generated file, /usr/local/etc/php-fpm.d/zz-docker-shinsenter-php.conf. They do not load php-fpm.conf or the other files in /usr/local/etc/php-fpm.d/, so a mounted www.conf has no effect. These sources apply, and the first one wins:

  1. custom-*.conf files in /usr/local/etc/php-fpm.d/.
  2. PHP_* variables you pass to the container.
  3. ENABLE_TUNING_FPM=1, which sets the pm.* values from the CPU limit of the container. A PHP_PM* variable you pass replaces the matching tuned value, and the other tuned values follow PHP_PM_MAX_CHILDREN.
  4. The defaults of the image.

PHP_* variables are the main way to configure PHP-FPM. If you prefer a file, mount it with a name that matches custom-*.conf. The container looks for these files when it starts, so restart it after you add one. A pool with the same name as the generated one ([www]) is merged, and your values win:

docker run -v ./custom-www.conf:/usr/local/etc/php-fpm.d/custom-www.conf:ro \
    shinsenter/php:8.3-fpm
[www]
pm = static
pm.max_children = 10
slowlog = /var/log/php-slow.log

Application Directory

Default application directory: /var/www/html. Change it with $APP_PATH:

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v "$PWD":/app \
    -e APP_PATH=/app \
    shinsenter/php:8.5-fpm-nginx

To change the document root (a path inside $APP_PATH that contains index.php), set $DOCUMENT_ROOT:

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v "$PWD":/app \
    -e APP_PATH=/app \
    -e DOCUMENT_ROOT=public \
    shinsenter/php:8.5-fpm-nginx

This example sets the document root to /app/public.

User and group

Override the default user and group with environment variables:

Environment Variable Description Default
APP_USER Username inside the container www-data
APP_GROUP Group name inside the container www-data
APP_UID Numeric UID for the user UID in container
APP_GID Numeric GID for the group GID in container

Example (run as user myapp with UID 5000):

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -e APP_USER=myapp \
    -e APP_UID=5000 \
    shinsenter/php:8.5-fpm-nginx

Extending the Images

Pre-installed PHP extensions, hooks and autorun scripts

The list of pre-installed extensions, the hooks and the autorun scripts are in docs/extending.md.

Adding PHP Extensions

Use the phpaddmod helper to install and configure extensions in one step - no need for docker-php-ext-install or manual php.ini edits.

Example Dockerfile:

FROM shinsenter/php:8.5-fpm-nginx

# Install imagick, swoole and xdebug
RUN phpaddmod imagick swoole xdebug

# Add your instructions here
# For example:
# ADD --chown=$APP_USER:$APP_GROUP ./myproject/ /var/www/html/

Note

phpaddmod is a wrapper around the mlocati/docker-php-extension-installer, which handles compiling and enabling extensions.

Using Cron Jobs

Jobs load from $CRONTAB_DIR when ENABLE_CRONTAB=1. Setup and examples are in docs/extending.md.

Supervisor command

Set SUPERVISOR_PHP_COMMAND to override the default command used by the supervisor process. This lets you run a different command to serve your app.

docker run \
    -e SUPERVISOR_PHP_COMMAND='php -S localhost:80 index.php' \
    shinsenter/php:8.5

Running in Production

These notes apply to the web images (fpm-nginx, fpm-apache, roadrunner, frankenphp) on Docker, Kubernetes, AWS, GCP or behind Traefik.

HTTPS

The images ship a self-signed certificate for local tests:

  • /etc/ssl/site/server.crt
  • /etc/ssl/site/server.key

For production, mount your own files over them, or copy them in your Dockerfile:

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v ./myproject:/var/www/html \
    -v ./my_domain.crt:/etc/ssl/site/server.crt \
    -v ./my_domain.key:/etc/ssl/site/server.key \
    shinsenter/php:8.5-fpm-nginx

If a proxy or load balancer ends TLS for you, see the next section.

Behind a proxy or load balancer

By default no proxy is trusted. REMOTE_ADDR stays the address of the connection, and your app reads X-Forwarded-For itself.

Set TRUSTED_PROXIES (CIDRs, separated by comma or space) to let the server use the client address from X-Forwarded-For and honor X-Forwarded-Proto (it then sets $_SERVER['HTTPS']). It works on Nginx, Apache, FrankenPHP and RoadRunner. The word private stands for the private ranges 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and fd00::/8, where Docker networks, Kubernetes pods and most proxies live:

docker run -e TRUSTED_PROXIES=private \
    -p 80:80 shinsenter/php:8.5-fpm-nginx

You can mix both forms, for example private,203.0.113.0/24. Only listed proxies can set these headers, so a client that connects directly cannot fake them. Use private only when nothing outside your private network can reach the container directly. With Cloudflare in front, list your load balancer and the Cloudflare ranges.

Traefik: see docs/traefik.md for a working Compose file and the settings that avoid 502 errors during deploys.

Health checks

Each web image answers health checks on a separate port, HEALTH_PORT (default 2020). The port is not published by default and does not depend on the Host header, HTTPS redirects or your app.

Image Liveness Readiness
fpm-nginx, fpm-apache /healthz (web server only) /readyz (PHP-FPM ping, path set by PHP_PING_PATH)
frankenphp /healthz /readyz
roadrunner /health?plugin=http /ready?plugin=http

HEALTH_CHECK_URL holds the full liveness address inside the container. The images define no HEALTHCHECK, because a first start can clone a project or run composer install, and nothing answers until it ends. Set a long start_period (Docker) or a startupProbe (Kubernetes).

Docker Compose:

services:
  web:
    image: shinsenter/php:8.5-fpm-nginx
    healthcheck:
      test: ["CMD-SHELL", "with-env sh -c 'curl -sf \"$$HEALTH_CHECK_URL\" >/dev/null'"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 120s

Kubernetes:

startupProbe:
  httpGet: { path: /healthz, port: 2020 }
  periodSeconds: 10
  failureThreshold: 30
livenessProbe:
  httpGet: { path: /healthz, port: 2020 }
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /readyz, port: 2020 }
  periodSeconds: 5

For load balancers, send traffic to port 80 and point the health check at port 2020, path /readyz (AWS ALB target group port override, GCP BackendConfig, Traefik loadbalancer.healthcheck.port).

Stopping and scaling

Variable Default Effect
SHUTDOWN_DELAY 0 Seconds to wait after the stop signal, so the load balancer can remove the replica
S6_SERVICES_GRACETIME, S6_KILL_GRACETIME 25000 Milliseconds that servers get to finish running requests. Keep it below terminationGracePeriodSeconds (30 s by default)
CADDY_GRACE_PERIOD 20s FrankenPHP: time for running requests on stop

On SIGTERM the container waits SHUTDOWN_DELAY, then stops the servers gracefully: running requests finish and new connections are refused.

To scale out:

  • Keep sessions, uploads and cache outside the container (Redis, a database, object storage or a shared volume), so every replica can answer any request.
  • Put the source and vendor/ in the image at build time, and set DISABLE_AUTORUN_CREATING_PROJECT=1 and DISABLE_AUTORUN_COMPOSER_INSTALL=1. Replicas then start fast and with the same package versions.

Performance

The defaults suit development as well as production, so a code change shows up right away. For production, set these variables:

Variable Value Effect
PHP_OPCACHE_VALIDATE_TIMESTAMPS 0 PHP stops checking files for changes. Restart the container after a deploy, because a changed file is not picked up
ENABLE_TUNING_FPM 1 Sets the pm.* values of PHP-FPM from the CPU limit of the container (see Customizing PHP-FPM)
COMPOSER_OPTIMIZE_AUTOLOADER 1 Builds an optimized class map at startup. With vendor/ in the image, run composer dump-autoload --optimize at build time instead
docker run -p 80:80 \
    -e PHP_OPCACHE_VALIDATE_TIMESTAMPS=0 \
    -e ENABLE_TUNING_FPM=1 \
    shinsenter/php:8.5-fpm-nginx

Other settings that matter:

  • PHP_OPCACHE_MEMORY_CONSUMPTION (default 256, in MB) and PHP_OPCACHE_MAX_ACCELERATED_FILES (default 130987) are enough for most projects. Raise them when opcache_get_status() shows a full cache.
  • PHP_OPCACHE_JIT and PHP_OPCACHE_JIT_BUFFER_SIZE turn on the JIT. It helps CPU-bound code and does little for a typical web request, so measure before you keep it.
  • Nginx and FrankenPHP compress responses (brotli and gzip). Do not compress again in your app.

Operations

Sending Emails

We use msmtp as a lightweight sendmail replacement, so libraries like PHPMailer work out of the box.

To use PHP's mail() function, configure SMTP via these environment variables:

Environment Variable Description Example Value
SMTP_HOST SMTP server hostname or IP smtp.gmail.com
SMTP_PORT SMTP port 587
SMTP_LOG Path to SMTP log file /path/to/email.log
SMTP_FROM Sender email address admin@example.com
SMTP_USER SMTP username Your smtp username
SMTP_PASSWORD SMTP password Your smtp password
SMTP_AUTH Enable SMTP authentication (on/off) on
SMTP_TLS Use TLS for the connection (on/off). Not set by default, so msmtp decides (empty)

Tip

If you don't have an SMTP server, try using a local SMTP container like Mailpit. With Mailpit, set SMTP_HOST=mailpit and SMTP_PORT=1025 in your container.

Debug mode

Set DEBUG=1 to turn on verbose logging and to see which hooks run:

docker run -e DEBUG=1 shinsenter/php:8.5-fpm-nginx

SSH access

Set ENABLE_SSHD=1 and publish port 22 to log in over SSH or SFTP. Key login is the default:

docker run -p 2222:22 -e ENABLE_SSHD=1 \
    -e SSHD_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
    shinsenter/php:8.5-fpm-nginx
ssh -p 2222 www-data@localhost

Main variables: SSHD_AUTHORIZED_KEYS (public keys, one per line), SSHD_USER (default $APP_USER), SSHD_PORT (default 22). Password login stays off unless SSHD_PASSWORD_AUTH and SSHD_PASSWORD are set. The full list is in docs/settings.md.

System settings

The most used variables are below. Every other setting, with its default, is in docs/settings.md.

Variable Effect
TZ Timezone of the container (default UTC)
DEBUG 1 turns on verbose logging
INITIAL_PROJECT Creates a project in an empty app directory: a .zip, .tar.gz or .git URL, or vendor/package for Composer
ENABLE_CRONTAB 1 runs the jobs in $CRONTAB_DIR
ENABLE_TUNING_FPM 1 sets the pm.* values from the CPU limit
DISABLE_AUTORUN_SCRIPTS 1 skips the autorun scripts

Deploy to your own server

muken is a command-line tool, in its own repository, that puts these images on a VPS: it installs Docker and a proxy, deploys with no downtime, rolls back on a failed health check, and can create the server and the DNS records for you (DigitalOcean, Hetzner, Cloudflare). Start with muken init. A short page is in docs/muken.md, and the guide is in the muken repository.

About This Project

The platforms, stable tags, update process and security updates are in docs/project.md.

Support the project

Keeping these images rebuilt for every PHP release takes ongoing work. If they save you time, you can help keep them going:

Plan for 2027: the project plans to open a sponsors program in 2027. Details will be announced in this README before it starts.

Bug reports, fixes and docs are welcome too. See CONTRIBUTING.md or open an issue.

License

This project is licensed under the GNU General Public License v3.0.

Please respect the work that went into these images. If you reuse ideas from this project, credit is appreciated.


From Vietnam πŸ‡»πŸ‡³ with love.

Releases

Sponsor this project

Packages

Used by

Contributors

Languages