bfren/nginx-php repository overview

⁠Nginx + PHP

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

An image for PHP websites: nginx⁠ and PHP-FPM in one container, with PHP 7.4 to 8.5. Baïkal⁠, FreshRSS⁠ and WordPress⁠ are built on it.

It is Nginx⁠ with:

• PHP and PHP-FPM from Alpine's packages, with the session and OPcache extensions
• the official php.ini, plus sensible defaults for security, uploads, sessions and OPcache - each one easy to override
• nginx set up to run PHP, with "pretty" URLs routed to index.php
• hourly cleaning of old sessions

The PHP set-up comes from the PHP image⁠ (its bf-php module is copied in when this image is built). There is no SSL support - it is designed to run behind a reverse proxy such as Caddy⁠.

⁠Quickstart

Serve the PHP site in ./site on port 8080:

docker run -d --name web -p 8080:80 -v ./site:/www/public quay.io/bfren/nginx-php:php8.5

Or with Docker Compose:

services:
  web:
    image: quay.io/bfren/nginx-php:php8.5-9.0
    environment:
      - BF_PHP_EXT=mbstring pdo_mysql
    ports:
      - "8080:80"
    volumes:
      - ./site:/www/public

Open http://localhost:8080. Requests for files that don't exist are sent to /index.php, so front-controller frameworks work without changes.

⁠Features

• 🐘 PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 and 8.5 - choose with the image tag
• ⚡ PHP-FPM, with OPcache (and the JIT compiler on PHP 8) turned on
• ⚙️ Override php.ini and PHP-FPM's www.conf with small JSON files
• 🔒 Secure defaults: allow_url_fopen off, phpinfo() disabled, HTTP-only secure session cookies, and the environment hidden from PHP unless you choose otherwise
• 🧹 Expired sessions cleaned every hour
• 🗜️ Everything from Nginx⁠: compression, helper files, logs, daily reload and a health check

⁠Tags

Images are published to Docker Hub (bfren/nginx-php) and Quay.io (quay.io/bfren/nginx-php) for linux/amd64, linux/arm/v7 and linux/arm64. Tags start with the PHP version.

There is no latest tag - always choose a PHP version.

PHP 8.1 and older no longer receive security fixes, and nor do the Alpine releases they are built on - use them only for legacy sites. Source: php.net⁠

⁠Configuration

⁠Ports

⁠Volumes

⁠Environment Variables

Nginx⁠ adds the nginx variables (access log, health check URI, …), and Alpine + S6⁠ adds timezone and cron.

⁠How It Works

⁠Starting

When the container starts, Nginx⁠ sets up nginx, then this image's initialisation scripts run:

Then S6 starts nginx and php-fpm. php-fpm checks its configuration (php-fpm -t) first, and if it fails, or PHP-FPM stops unexpectedly, the container stops.

⁠nginx and PHP

nginx passes requests to PHP-FPM on 127.0.0.1:9000 (the php-fpm upstream). The default site uses index.php as the index page, plus two helper files you can use in your own sites:

Include them with include helpers/php-try-all.conf; - see Nginx⁠ for how sites and helpers work.

⁠php.ini

The official php.ini is downloaded when the image is built (see PHP⁠). At every start, the JSON files in /etc/bf/php.d are read in name order, later files replacing earlier values, and each value is set in php.ini. The image's defaults are:

To change or add settings, add your own file - e.g. mount ./php.json to /etc/bf/php.d/10-site.json:

{
    "memory_limit": "512M",
    "upload_max_filesize": "256M",
    "post_max_size": "256M"
}

The PHP image's /php-ini.json is not used here - use /etc/bf/php.d instead.

⁠PHP-FPM settings (www.conf)

The same works for PHP-FPM: at every start, the JSON files in /etc/bf/php-fpm.d are applied to www.conf. PHP-FPM runs as the www user, and the defaults are catch_workers_output = yes, decorate_workers_output = no and clear_env = yes. For example, to allow more PHP processes:

{
    "pm.max_children": "20"
}

⁠Environment variables in PHP

clear_env = yes means PHP can't see the container's environment variables - so secrets passed to the container aren't readable by every script. To pass some through, name them BF_PHP_… and set BF_PHP_LOAD_ENV=1. Every BF_PHP_* variable is then available to PHP by the same name:

$host = getenv('BF_PHP_DB_HOST');

This includes the image's own BF_PHP_* variables (e.g. BF_PHP_DIR), which are harmless.

⁠Extensions

BF_PHP_EXT installs extensions as Alpine packages at every start, so the container needs internet access and starts more slowly. That's convenient for trying things out, but for anything you deploy, install them when you build your own image instead (see Building on this image⁠ and PHP⁠).

⁠Sessions

Every hour, a cron job runs PHP's session clean-up as the www user, removing sessions older than session.gc_maxlifetime (1 day by default, or your override).

⁠Health check, logs and reloading

These come from Nginx⁠. The health check loads http://localhost, so with the default site it checks PHP-FPM too.

⁠The bf-nginx-php module

The bf-php module⁠ is also available.

⁠Building on this image

FROM quay.io/bfren/nginx-php:php8.5-9.0

COPY ./overlay /
RUN bf-install

overlay/tmp/install:

#!/usr/bin/nu

use bf
use bf-php

# Install my-site
def main [] {
    bf-php ext install [mbstring pdo_mysql]
}

Put your site in overlay/www/public (or mount it), nginx configuration in overlay/etc/nginx/sites or custom, and php.ini settings in overlay/etc/bf/php.d. See Nginx⁠ for the rest.

⁠Testing

./test.nu        # builds the PHP 8.5 image and runs /test
./test.nu 8.2    # the same for PHP 8.2
./test.nu --all  # every version, in parallel
./run.sh         # builds the PHP 8.5 image and opens a shell (port 3000)

/test runs this image's tests alongside the base images' tests, and fails if tests don't execute. As well as the PHP image's tests⁠, they check that php-fpm links to the versioned executable, the session and OPcache extensions are loaded, the PHP-FPM configuration is valid, override files merge in the right order, and BF_PHP_LOAD_ENV writes the right lines to www.conf.

⁠Troubleshooting

⁠Logins or sessions don't work over HTTP

Session cookies are secure by default, so browsers only send them over HTTPS. Use HTTPS (e.g. through your proxy), or for local testing add {"session.cookie_secure": "0"} to a file in /etc/bf/php.d.

⁠The container stops at start-up

PHP-FPM's configuration test failed - often a bad value in a /etc/bf/php-fpm.d file. Run with BF_DEBUG=1 and check docker logs.

⁠"Call to undefined function"

The function's extension isn't installed - add it with BF_PHP_EXT or in your own image. Package names are at pkgs.alpinelinux.org⁠.

⁠getenv() returns nothing

PHP can't see the container's environment - see Environment variables in PHP⁠.

⁠file_get_contents('https://…') fails

allow_url_fopen is off by default. Use curl (BF_PHP_EXT=curl), or turn it on in a /etc/bf/php.d file.

⁠FAQs

⁠Why nginx and PHP-FPM in one container?

One container per site is simpler to run and back up, and S6 supervises both processes - if either fails, the container stops so Docker can restart it.

⁠Licence

⁠Copyright