PHP Docker Images
📦 (PHP) Lightweight images for PHP 5.6 to 8.6, on Debian and Alpine, ready to run
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

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.6-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.6-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 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.6-cli
shinsenter/php:8.6-zts
shinsenter/php:8.6-fpm
shinsenter/php:8.6-fpm-apache
shinsenter/php:8.6-fpm-nginx
shinsenter/php:8.6-roadrunner (1)
shinsenter/php:8.5-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:
- Variables start with
PHP_ to avoid conflicts.
- The remainder matches the php.ini or php-fpm.conf directive name.
- Directive names are converted to CONSTANT_CASE (uppercase with underscores replacing dots or dashes).
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.6 php -i
With docker-compose.yml
services:
web:
image: shinsenter/php:8.6-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:
custom-*.conf files in /usr/local/etc/php-fpm.d/.
PHP_* variables you pass to the container.
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.
- 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.6-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.6-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.6-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.6-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/
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.6
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.6-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.6-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.6-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.6-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.6-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.6-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.