shinsenter/php repository overview

⁠PHP Docker Images

📦 (PHP) Lightweight images for PHP 5.6 to 8.6, on Debian and Alpine, ready to run

• Docker Hub: https://hub.docker.com/r/shinsenter/php⁠
• GitHub Packages: https://code.shin.company/php/pkgs/container/php⁠
• Pre-built images for popular PHP applications and frameworks: https://hub.docker.com/u/shinsenter⁠

⁠Table of Contents

• Introduction⁠
• Quick start⁠
• Getting Started⁠
  • Docker image variants⁠
  • Which tag should I use?⁠
  • Ready-made application images⁠
• Configuration⁠
  • Environment variables⁠
  • Customizing PHP-FPM⁠
  • Application Directory⁠
  • User and group⁠
• Extending the Images⁠
  • Pre-installed PHP extensions, hooks and autorun scripts⁠
  • Adding PHP Extensions⁠
  • Using Cron Jobs⁠
  • Supervisor command⁠
• Running in Production⁠
  • HTTPS⁠
  • Behind a proxy or load balancer⁠
  • Health checks⁠
  • Stopping and scaling⁠
• Operations⁠
  • Sending Emails⁠
  • Debug mode⁠
  • SSH access⁠
  • System settings⁠
• About This Project⁠
  • Support the project⁠
  • License⁠

⁠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.

⁠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⁽¹⁾, and frankenphp⁽²⁾ 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 ⁽¹⁾
• shinsenter/php:8.4-frankenphp ⁽²⁾

See all tags on our Docker Hub⁠.

⁠Which tag should I use?

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.
  • PHP ini directives: https://www.php.net/manual/en/ini.list.php⁠
  • PHP-FPM directives: https://www.php.net/manual/en/install.fpm.configuration.php⁠
• 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.

⁠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

⁠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:

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/

⁠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:

docker run -e TRUSTED_PROXIES='10.0.0.0/8,172.16.0.0/12,192.168.0.0/16' \
    -p 80:80 shinsenter/php:8.5-fpm-nginx

Only listed proxies can set these headers, so a client that connects directly cannot fake them. With Cloudflare in front, list your load balancer and the Cloudflare ranges.

⁠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.

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

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.

⁠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:

⁠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

⁠System settings

Environment variables for fine-tuning container behavior.

⁠General

⁠Project startup and autorun

⁠Cron

⁠Tuning and Apache

⁠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:

• ☕ Donate via PayPal⁠
• 💖 Sponsor on GitHub⁠

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.