Sign inSign up
php logo

shinsenter/php

Sponsored OSS

By SHIN Company

•Updated about 7 hours ago

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

Image
Languages & frameworks
Developer tools
Web servers
34

1M+

shinsenter/php repository overview

⁠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](#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](https://code.shin.company/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 toTagNotes
Run scripts, workers or ComposercliRuns php and exits
Use thread-safe PHPztsFor extensions that need ZTS
Put PHP-FPM behind my own web server or ingressfpmListens on port 9000
Get a ready web serverfpm-nginxNginx + PHP-FPM, ports 80 and 443
Use Apache and .htaccessfpm-apacheApache + PHP-FPM, ports 80 and 443
Use a long-running app serverroadrunnerPHP 8.0 or newer
Use a Caddy-based app serverfrankenphpPHP 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 VariableWhat it doesEquivalent php.ini / fpm setting
PHP_DISPLAY_ERRORS=1Show errors during developmentdisplay_errors = 1
PHP_POST_MAX_SIZE=100MSet max POST size (default 8M)post_max_size = 100M
PHP_UPLOAD_MAX_FILESIZE=100MSet max upload file size (default 2M)upload_max_filesize = 100M
PHP_SESSION_COOKIE_HTTPONLY=1Enable HttpOnly on session cookiessession.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 VariableDescriptionDefault
APP_USERUsername inside the containerwww-data
APP_GROUPGroup name inside the containerwww-data
APP_UIDNumeric UID for the userUID in container
APP_GIDNumeric GID for the groupGID 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`](https://github.com/mlocati/docker-php-extension-installer), which handles compiling and enabling extensions.

Tip

See the supported extensions in their documentation: https://github.com/mlocati/docker-php-extension-installer/blob/master/README.md#supported-php-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.

ImageLivenessReadiness
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
VariableDefaultEffect
SHUTDOWN_DELAY0Seconds to wait after the stop signal, so the load balancer can remove the replica
S6_SERVICES_GRACETIME, S6_KILL_GRACETIME25000Milliseconds that servers get to finish running requests. Keep it below terminationGracePeriodSeconds (30 s by default)
CADDY_GRACE_PERIOD20sFrankenPHP: 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:

VariableValueEffect
PHP_OPCACHE_VALIDATE_TIMESTAMPS0PHP stops checking files for changes. Restart the container after a deploy, because a changed file is not picked up
ENABLE_TUNING_FPM1Sets the pm.* values of PHP-FPM from the CPU limit of the container (see Customizing PHP-FPM⁠)
COMPOSER_OPTIMIZE_AUTOLOADER1Builds 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 VariableDescriptionExample Value
SMTP_HOSTSMTP server hostname or IPsmtp.gmail.com
SMTP_PORTSMTP port587
SMTP_LOGPath to SMTP log file/path/to/email.log
SMTP_FROMSender email address[email protected]
SMTP_USERSMTP usernameYour smtp username
SMTP_PASSWORDSMTP passwordYour smtp password
SMTP_AUTHEnable SMTP authentication (on/off)on
SMTP_TLSUse 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](https://dockerhub-mirror.hs.vc/r/axllent/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⁠.

VariableEffect
TZTimezone of the container (default UTC)
DEBUG1 turns on verbose logging
INITIAL_PROJECTCreates a project in an empty app directory: a .zip, .tar.gz or .git URL, or vendor/package for Composer
ENABLE_CRONTAB1 runs the jobs in $CRONTAB_DIR
ENABLE_TUNING_FPM1 sets the pm.* values from the CPU limit
DISABLE_AUTORUN_SCRIPTS1 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.

Tag summary

Content type

Image

Digest

sha256:315bd38fe…

Size

80.5 MB

Last updated

about 7 hours ago

docker pull shinsenter/php:dev-8.3-fpm-nginx

This week's pulls

Pulls:

37,300

Last week