dirtsimple/php-server repository overview

⁠ghcr.io/dirtsimple/php-server

⁠Overview

This is a docker image for an alpine nginx + php-fpm combo container, with support for:

• Cloning a git repo at container start (and running composer install if applicable)
• Running scheduled jobs (cron), on-file-change jobs (cortesi/modd⁠), webhooks (adnanh/webhook⁠), or other supervisord-controlled tasks
• Build arguments to allow adding extra packages and PHP extensions
• Environment-based templating of any configuration file in the container at startup
• Running any user-supplied startup scripts
• 100% automated HTTPS certificate management via certbot and Let's Encrypt
• Robust privilege separation and defense-in-depth for a variety of development and production use cases

Inspired by richarvey/nginx-php-fpm⁠, this image supports most of that image's configuration flags⁠, plus many, many enhancements and bug fixes like these:

• Configuration files are generated using dockerize templates⁠ instead of sed, and boolean environment variables can be set to true or false , not just 1 or 0
• Your code can provide additional configuration files to be processed w/dockerize at container start time (or you can mount replacements for this image's configuration templates under /tpl)
• Ready-to-use support for most PHP "front controllers" (as used by Wordpress, Laravel, Drupal, Symfony, etc.): just set PHP_CONTROLLER to true and PUBLIC_DIR to the subdirectory that contains the relevant index.php (if any). (PATH_INFO support is also available, for e.g. Moodle.)
• HTTPS is as simple as setting a DOMAIN and LETS_ENCRYPT=my@email: registration and renewals are immediate, painless, and 100% automatic. The certs are saved in a volume by default, and renewals happen on container restart, as well as monthly if you enable cron.
• cron jobs are supported by setting USE_CRON=true and putting the job data in /etc/crontabs/nginx, or an executable file in one of the /etc/periodic/ subdirectories (via volume mount, startup script, or template files)
• You can add .ini files to /etc/supervisor.d/ to add additional processes to the base supervisor configuration, or to override the default supervisor configurations for nginx, php-fpm, etc.
• php-fpm pool parameters can be set with environment vars (FPM_PM, FPM_MAX_CHILDREN, FPM_START_SERVERS, FPM_MIN_SPARE_SERVERS, FPM_MAX_SPARE_SERVERS, FPM_MAX_REQUESTS)
• nginx's set_real_ip_from is recursive, and supports Cloudflare (via REAL_IP_CLOUDFLARE=true) as well as your own load balancers/proxies (via REAL_IP_FROM -- which can include multiple addresses, separated by spaces.)
• Additional alpine APKs, PHP core extensions, and pecl extensions can be installed by setting EXTRA_APKS, EXTRA_EXTS, and EXTRA_PECL as environment variables or build-time arguments.
• sendfile is turned on for optimal static file performance, unless you set VIRTUALBOX_DEV=true
• Configuration files don't grow on each container restart
• Developer and server priviliges are kept separate: git and composer are run as a developer user rather than as root, and files are owned by that user. To be written to by PHP and the web server, files or directories must be explicitly listed in NGINX_WRITABLE. (The whole codebase is NGINX_READABLE by default, but can be made more restrictive by listing specific directories.)
• You can mount your code anywhere, not just /var/www/html (just set CODE_BASE to whatever directory you like)
• If any supervised process (nginx, php-fpm, cron, etc.) enters a FATAL state, the entire container is shut down, so that configuration or other errors don't produce a silently unresponsive container.
• Command-line PHP scripts run with a file-based opcache under /tmp, speeding start times for large PHP command line tools such as wp-cli, artisan, etc. (For compatibility reasons, this cache is disabled when ENABLE_XDEBUG is true.) Command-line scripts run without a memory limit, unless you set PHP_CLI_MEMORY to a memory value like 512M.

Note: there are a few configuration options that must be specified in a different way than the richarvey image, or which have different defaults: see Backward-Compatibility Settings⁠, below, for more info.

⁠Contents

• Adding Your Code⁠
  • Pulling Updates and Pushing Changes⁠
  • Permissions and the developer User⁠
  • Composer Configuration, PATH, and Tools⁠
• Configuration Templating⁠
• Nginx Configuration⁠
  • Config Files⁠
  • Environment⁠
  • Backward-Compatibility Settings⁠
  • PHP Front Controllers and PATH_INFO⁠
  • File Permissions⁠
  • HTTPS and Let's Encrypt Support⁠
• Adding Extensions⁠
• Supervised Tasks⁠
  • Scheduled Jobs (cron)⁠
  • Changed-File Jobs (modd)⁠
  • Webhooks (adnanh/webhook)⁠
• Version Info⁠

⁠Version Info

Builds of this image are tagged with multiple aliases to make it easy to pin specific revisions or to float by PHP version. For example, a PHP 7.3.13 image with release 2.1.1 of this container could be accessed via any of the following tags (if 2.1.1 were the latest release of this image):

• 7.3
• 7.3-2.x
• 7.3-2.1.x
• 7.3-2.1.1
• 7.3.13
• 7.3.13-2.x
• 7.3.13-2.1.x
• 7.3.13-2.1.1

Note that there is no latest tag for this image; you must explicitly select at least a PHP version such as 7.3 to get the latest version of this image for that PHP version.

Also note that although you can just specify a PHP version, major releases of this container may be incompatble with older releases due to e.g. changes in OS versions or other factors, so you should probably at least target a specific major release of this container, e.g. 7.3-2.x or 7.4-3.x.

⁠Major Versions

• 3.1.x - Added 8.3 and newer versions of 7.4-8.2, added -alpine3.x tags so you can distinguish by OS version (e.g. 8.0-alpine3.16 vs 8.0-alpine3.18).
• 3.x - Alpine 3.10-3.16, Composer 2, PHP 7.1 through 8.2, dropped prestissimo from default GLOBAL_REQUIRE, added --optimize-autoloader to default COMPOSER_OPTIONS
• 2.x - Alpine 3.9, Composer 1, PHP 7.1 through 7.3, build extensions using mlocati/docker-php-extension-installer⁠
• 1.4.x - Alpine 3.9, Composer 1, PHP 7.1 and 7.2, image based on Docker php-fpm-alpine, scripted extension builds
• 1.3.x and older - Alpine 3.6, PHP 7.1 only, implemented as an overlay on the nginx-php-fpm image

⁠Version Details