Release 5.0: Add IP address SSL certificates, Additonal Proxy Support, web server improvements, and other fixes - #645
Open
jaydrogers wants to merge 41 commits into
Open
Conversation
…643) * Enhance trusted proxy support across configurations Updated documentation and configuration files to improve trusted proxy handling. Introduced customizable trusted proxy settings for Cloudflare, Sucuri, and local proxies, ensuring accurate IP logging. Removed hardcoded Cloudflare IPs from NGINX and Apache configurations, replacing them with a dynamic inclusion based on the TRUSTED_PROXY environment variable. * Clarify trusted proxy documentation for Cloudflare and Sucuri Updated the documentation to specify that both Cloudflare and Sucuri configurations now automatically include local Docker networks. Added a tip to inform users that they can use the `cloudflare` setting while also trusting local proxies, enhancing clarity on trusted proxy usage. * Add global Caddy configuration support in FrankenPHP Updated the Dockerfile to create a directory for global Caddy configurations and modified the Caddyfile to import additional configuration files from the new caddyfile-global.d directory, enhancing flexibility in Caddy setup. * Fix Dockerfile syntax by correcting line continuation for Caddy configuration paths
This comment was marked as outdated.
This comment was marked as outdated.
jaydrogers
changed the title
jaydrogers
changed the title
* Config checks for SSL certificate generation Add checks for DISABLE_DEFAULT_CONFIG and set default SSL file paths. * Removed comment since the code is readable --------- Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com>
…atabase connection checks (#628) * Refactor Laravel migration script to improve isolation handling and database connection checks - Removed migration isolation argument from test-db-connection script. - Introduced a helper function for running migrations per database, enhancing clarity and reusability. - Updated migration flag assembly logic to better manage isolation settings. - Improved error handling and logging for database connection issues. * Remove debug log from Laravel migration script to streamline output during migrations * Update Laravel migration script to change error message from error to warning for version check * Update PHP base opertating systems. Add Alpine 3.23 support (#638) PHP repo no longer has images available for alpine3.21 for latest minor versions, this removes 3.21 if its no longer available and adds 3.23 if available * Update PHP extension installer version to 2.9.27 * Update NGINX version to 1.28.1 * Refactor and improve security headers, file blocks, etc (#631) * Fix blocking .well-known path for FrankenPHP * Remove specific endpoint checks because the whole folder should be allowed * Enhance security configurations across Apache, NGINX, and Caddy by implementing best practices for HTTP headers and file access restrictions. Added protections against clickjacking, MIME type sniffing, and sensitive file exposure while allowing necessary access to well-known URIs as per RFC 8615. --------- Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com> Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net> * Update GitHub Actions to use actions/checkout@v6 in multiple workflows * Update GitHub Actions to use actions/upload-artifact@v6 for improved artifact handling * Update GitHub Actions to use actions/download-artifact@v7 for improved artifact handling * Upgrade FrankenPHP to v1.11.1 * Increase size of GitHub Actions Runners because of memory segmentation fault issues (Thanks Depot! 😅) * Add security measures to block PHP execution in storage directory (#641) Implemented restrictions across Apache, NGINX, and FrankenPHP configurations to prevent the execution of PHP files in the /storage directory, addressing potential vulnerabilities related to arbitrary file uploads (GHSA-29cq-5w36-x7w3). * Refactor Laravel version check and isolation mode handling in automation script - Updated the logic for enabling isolation mode based on Laravel version, ensuring it only activates for versions 9.38.0 and above. - Improved error handling and logging for Laravel version detection, providing clearer output when version determination fails. - Simplified version comparison logic to enhance readability and maintainability. * Update container info script to include automation status --------- Co-authored-by: alloylab <trevor@alloylab.com> Co-authored-by: Marcel Arns <38068686+marns93@users.noreply.github.com>
This was referenced Jan 27, 2026
* Add Nightwatch health check script * Add documentation for Laravel Nightwatch --------- Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com> Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net>
…n get-php-versions.sh - Added a retry mechanism with a maximum of 3 attempts for fetching PHP versions from the specified JSON feed. - Included validation to ensure the response is valid JSON, with error handling for invalid responses. - Enhanced error messages to provide more context in case of failures.
…andling - Modified the curl command in get-php-versions.sh to include a custom user agent string for better identification of requests. - This change aims to enhance compatibility with the PHP versions JSON feed.
… configurations (#646)
* Add import for DB facade * Move DB facade import to file scope --------- Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net>
…e/webserver-improvements-and-fixes' of github.com:serversideup/docker-php into release/webserver-improvements-and-fixes
* Enhance logging and SSL generation scripts - Updated the `LOG_OUTPUT_LEVEL` description in the documentation to clarify verbosity levels and their impact on logging behavior. - Modified the entrypoint script to remove unnecessary checks for `LOG_OUTPUT_LEVEL` when displaying container info. - Added checks in the SSL generation script to conditionally log messages based on the `LOG_OUTPUT_LEVEL`, improving debugging capabilities. * Update log level in debug Caddyfile from INFO to DEBUG for enhanced logging detail
- Replaced echo statements with debug_log calls for improved logging in the `artisan_storage_link` and automation check sections of the entrypoint script. - This change enhances the verbosity of log output, aiding in debugging and monitoring of Laravel automations.
jaydrogers
changed the title
jaydrogers
changed the title
Member
Author
|
@mbrodala: Images are available for testing here if you want to help test 😃 https://hub.docker.com/r/serversideup/php-dev/tags?name=645- |
|
Thanks for the hint, I totally missed that there is a dedicated So far it looks good: local startup/usage is fine, CI and review environment is happy. I already had the mentioned changes applied as patches on top of the 4.4.1 images so there is basically no change here. The other changes do not affect us. So from my POV 👍 |
…profiles - Added details on using Let's Encrypt short-lived certificates and the `CADDY_ACME_PROFILE` environment variable in the documentation. - Updated the Dockerfile to set the default value for `CADDY_ACME_PROFILE` to "off". - Modified the Caddyfile to include the option for selecting a Let's Encrypt ACME certificate profile. These changes improve clarity on SSL options and enhance the configuration flexibility for users.
jaydrogers
changed the title
* Update documentation and scripts for PHP version changes and migration - Added a section on dropped PHP versions in the major version migrations guide, detailing the last built dates and reasons for PHP 8.1, 8.0, and 7.4. - Updated the Docker tags documentation to reflect changes in supported OS versions and PHP patch versions. - Modified the assemble-docker-tags script to align with the new PHP versioning scheme. - Revised the PHP versions base config to remove deprecated versions and adjust supported operating systems. - Updated development scripts to reflect the new PHP versioning and OS options. - Enhanced the generate-matrix script to ensure compatibility with the updated PHP versions and OS configurations. - Adjusted the get-nginx-versions and get-php-versions scripts to accommodate the removal of older OS versions. * Add support for PHP extension overrides in Dockerfiles and scripts
* Enhance CI/CD workflows and Docker image publishing - Update Docker workflows to improve build and publish processes for production, beta, and PR images. - Introduce a new setup matrix workflow for better PHP version management. - Implement auto-retry for failed image builds to handle transient errors. - Add support for additional environment variables in the Docker build process. - Refactor PHP version validation to ensure all necessary base images are available on DockerHub. - Update documentation to reflect changes in CI/CD processes and workflows. * Fix formatting of run-name in Docker Publish workflow * Add actionlint workflow and update documentation for workflow linting * Enhance auto-retry workflow for failed builds and update documentation on transient failures * Increase MAX_FAILED_JOBS limit from 5 to 10 for better handling of transient failures * Implement docker-php-serversideup-download for reliable file downloads during builds * Refactor CI workflows: consolidate linting into service_lint.yml and update documentation for improved clarity * Fix web images failing to start with s6-overlay 3.2.3 s6-overlay 3.2.3 moved its user bundle to /etc/s6-overlay/user-bundles.d and no longer ships s6-rc.d/user/type. With our services still registered under the old s6-rc.d/user/contents.d path, rc.init tried to create that type file at startup, failed as the unprivileged www-data user, and nginx or apache never started, leaving the container unhealthy forever. Register php-fpm, nginx, and apache2 in user-bundles.d/user/contents.d instead. Verified with local fpm-nginx and fpm-apache builds on bookworm: both services start and the HEALTHCHECK reports healthy. * Lint Dockerfiles with hadolint Add a hadolint job to the lint group so Dockerfile mistakes are caught before any image builds. Rules that conflict with deliberate project decisions (unpinned apt/apk packages for weekly security rebuilds, shell-form CMD, named USER, and so on) are ignored in .hadolint.yaml with the reason recorded next to each one. Fix the two findings it raised in the fpm-nginx Dockerfile: the Alpine repository printf had five placeholders but four arguments, and egrep is replaced with grep -E. * Summarize every run in one table with image sizes Replace the per-job summary cards (68 lists of pull commands) with a single table for the whole run. Each build job now records its canonical tag and compressed size per architecture, read from the registry manifest, and uploads it as a small artifact. A new service_summary.yml merges those files with scripts/build-summary.sh into one table grouped by variation, listing images that failed to build as well. Before building, each job looks up the same tag on serversideup/php so the table shows how much every image grew compared to what users pull today. Growth over 10% is flagged. The setup card shrinks to the PHP patch versions resolved from php.net, which is the one thing only that job knows. * Add smoke tests for published images Nothing ran the images after they were built, so a broken entrypoint would only be noticed by users. scripts/smoke-test.sh runs an image and checks what a user would hit first: PHP reports the expected version, the container runs as an unprivileged user, and images with a HEALTHCHECK become healthy. On failure it prints the container logs. service_smoke-test.yml selects the newest PHP version of every variation on one Debian and one Alpine base from the run's image details and tests each on native amd64 and arm64 GitHub runners. Images that were not pushed (pull requests from forks) are skipped. The script works against any image reference, so it doubles as a local check before opening a PR that touches startup behavior. It caught the s6-overlay user bundle regression fixed earlier in this branch. * Run smoke tests and the summary table on every publish Add smoke and summary jobs to the PR, production, and beta workflows. Both run whenever the matrix was generated, even if some builds failed, so a red run still shows which images are missing and whether the rest work. The PR comment now reports the smoke test result and carries the full image table, collapsed, next to the pull commands. * Enhance documentation on CI processes, including linting and smoke testing for Docker images * Fix jq command in smoke test workflow to ensure proper JSON parsing * Update PR comment formatting to include build status headline * Refactor CI workflows for image publishing and testing - Split the image build and publish processes into separate reusable workflows: `service_build-images.yml` and `service_publish-images.yml`. - Enhance the smoke test workflow to pull images from the Depot Registry and validate them against expected behaviors. - Introduce a new script `select-smoke-images.sh` to select representative images for smoke testing based on the latest PHP versions and variations. - Update the summary generation script to reflect changes in image publishing and size reporting. - Add tests for CI helper scripts to ensure consistent behavior across environments. - Improve documentation to clarify the CI/CD process and the role of each workflow in the image publishing pipeline. * Enhance CI workflows with concurrency control, improved release tagging, and refined smoke test processes * Refactor CI workflows to unify job naming and output references for image selection and publishing * Refactor CI workflows to replace smoke tests with image tests, enhancing reliability and clarity in the publishing process * Refactor CI workflows to improve job naming for clarity and consistency across image publishing and testing processes * Enhance CI/CD workflows and image testing - Updated service_build-images.yml to handle image loading and testing for pull requests from forks, ensuring that amd64 images are tested directly on the runner. - Modified service_publish-images.yml to improve image promotion logic, including digest verification and enhanced error handling for failed image promotions. - Improved service_test-images.yml to group saved images by PHP version and base OS, allowing for more efficient testing and clearer reporting of results. - Enhanced trigger_auto-retry-failed-builds.yml to better manage transient failures, including automatic issue creation for persistent failures. - Updated AGENTS.md and contributing documentation to reflect changes in the CI/CD process and image testing. - Refined scripts/build-summary.sh to prioritize published image records and improve error visibility for failed builds. - Enhanced scripts/test-image.sh to check for loaded PHP extensions and validate web server responses for images that include a web server. - Adjusted scripts/tests/run.sh to reflect changes in image publishing status and ensure accurate testing of image details. * Refactor image testing logic to improve failure handling and remove redundant result reporting * Refactor image publishing and testing workflows to enhance logging and error handling
Images for PR #645
Try it: docker run --rm -v "$PWD:/var/www/html" -p 8080:8080 serversideup/php-dev:645-8.5-fpm-nginxEvery image is on Docker Hub as All images with sizesSizes are compressed, per architecture.
Updated on every push to this PR. |
… rule (#691) * fix: update security rules to prevent edge cases in PHP execution for storage directories Expanded the regex patterns in Apache, Nginx, and Caddy configurations to block PHP file execution more reliably by accounting for trailing slashes after `.php`. * Add storage directory and enforce PHP execution restrictions --------- Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com> Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net>
… depend on base (#689) * fix(s6): make web services wait for their config oneshots to fix root-mode startup race When a container built on the s6 images runs as root, php-fpm and the web server (nginx/apache2) are brought up in parallel with the entrypoint oneshots that configure them, because the long-running services have no dependency on those oneshots. As root this races: - php-fpm reads its pool before `5-fpm-pool-user` appends `user`/`group`, failing with "ALERT: [pool www] user has not been defined" -> "ERROR: FPM initialization failed". - the web server starts before `10-init-webserver-config` renders its config (e.g. nginx: open() "/etc/nginx/nginx.conf" failed). s6 restarts the crashed services so the container eventually recovers, which is why the failure is intermittent and hard to reproduce (see discussion #425), but it emits alarming errors, slows startup, and leaves a brief window with no service. docker-php-serversideup-s6-init now adds a dependency from each web service to the entrypoint oneshot that configures it, appending to the existing flat `dependencies` file. The oneshots are chained in alphabetical order, so depending on one transitively waits for all earlier ones (php-fpm -> 5-fpm-pool-user; nginx/apache2 -> 10-init-webserver-config). Entries are de-duplicated and appended newline-safely (nginx's shipped `dependencies` has no trailing newline). Dependencies are only added when both the service and the oneshot exist, so cli/fpm/frankenphp images and images that remove a script are unaffected. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Migrate shipped services and generated oneshots from the deprecated flat dependencies file to dependencies.d, make every user service depend on base as s6-overlay recommends, and make php-fpm, nginx, and apache2 wait for the oneshots that write their config. Fixes root-mode FPM 'user has not been defined' race (#425, #689). Co-authored-by: LorenzoRogai <1665768+LorenzoRogai@users.noreply.github.com> Co-authored-by: mbrodala <5037116+mbrodala@users.noreply.github.com> --------- Co-authored-by: Lorenzo Rogai <lorenzo@shippypro.com> Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com> Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net> Co-authored-by: LorenzoRogai <1665768+LorenzoRogai@users.noreply.github.com> Co-authored-by: mbrodala <5037116+mbrodala@users.noreply.github.com>
…and PHP_SESSION_COOKIE_HTTPONLY environment variables (#692) * Add new configureable variables * Reorganized variables and added documentation * Add validation for PHP_* environment variables in php.ini --------- Co-authored-by: Jay Rogers <3174134+jaydrogers@users.noreply.github.com> Co-authored-by: Jay Rogers <jaydrogers@users.noreply.serversideup.net>
…ile (#702) The Dockerfile declared FRANKEN_PHP_CONFIG, but the Caddyfile and the docs reference FRANKENPHP_CONFIG. Rename the ENV so the default matches the variable Caddy actually reads.
jaydrogers
changed the title
…e ranges and implement strict header processing for enhanced security. Fixes #703
This was referenced Sep 10, 2026
* Enhance OPcache configuration and documentation - Updated default OPcache settings for production mode in various documentation files, emphasizing the importance of `PHP_OPCACHE_ENABLE` and its impact on performance. - Added a new guide on PHP OPcache tuning, detailing how to measure and adjust OPcache settings for optimal application performance. - Clarified the behavior of `PHP_OPCACHE_VALIDATE_TIMESTAMPS` and its implications for development and production environments. - Adjusted Dockerfiles across multiple variations to reflect new OPcache defaults, including increased memory consumption and maximum accelerated files. - Improved scripts and entrypoint messages to provide clearer guidance on OPcache usage and best practices for deployment. * Refactor OPcache status retrieval and update production mode notice for clarity * Update migration and tuning documentation for OPcache improvements * Refactor OPcache documentation: update migration guide and add production performance tuning guide * Enhance OPcache configuration and documentation: update defaults, improve CLI handling, and clarify production settings * Update OPcache notice link for performance tuning documentation * Refine OPcache performance tuning guide: remove placeholder text and clarify custom ini file options * Clarify OPcache explanation in production performance tuning guide
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
👨🔬 How to test
You can test this image using our serversideup/php-dev repository, which automatically builds on push to this PR.
View the available testing images →
🌎 Docs Preview
You can view the latest docs for this release here:
🤩 What's new
Short-lived & IP address certificates for FrankenPHP
FrankenPHP can now request Let's Encrypt's new short-lived (~6-day) certificate profile through the new
CADDY_ACME_PROFILEvariable. Short-lived certificates skip revocation entirely, and the same profile is what lets you issue certificates for raw IP addresses — handy for services that don't have a domain in front of them.Configure short-lived & IP certificates →
Trusted proxy support for every variation (#643)
TRUSTED_PROXYnow works the same way across all variations — FrankenPHP, NGINX, and Apache — so your app sees the real client IP whether it's behind Cloudflare, a load balancer, or your own reverse proxy. FrankenPHP users also get Caddy global imports, making it easy to layer in your own global configuration.Configuring trusted proxies →
Native Laravel Nightwatch support (#572)
Added a native health check for Laravel Nightwatch, complete with documentation to wire it up.
New environment variables
This release adds new environment variables. All of them are documented in the environment variable specification.
TRUSTED_PROXYcloudflarecloudflare,sucuri,local, oroff.CADDY_ACME_PROFILEoffshortlived(~6-day certs, required for IP-address certificates),tlsserver,classic, oroff.AUTORUN_LARAVEL_SKIP_IF_NOT_FOUNDfalsetrue, Laravel automations exit gracefully if Laravel is not found inAPP_BASE_DIRinstead of failing the container. RequiresAUTORUN_ENABLED=true.PHP_FILE_UPLOADSOnOffto harden apps that never accept uploads.PHP_MAX_FILE_UPLOADS20PHP_DISABLE_FUNCTIONS""exec,shell_exec. Empty because Laravel, Composer, and Symfony Process rely onproc_open.PHP_HTML_ERRORSOnPHP_DISPLAY_ERRORSis on. Never affects logged errors, and PHP forces it off for the CLI.PHP_REALPATH_CACHE_SIZE4096Kvendor/directory may benefit from raising it.PHP_SESSION_COOKIE_HTTPONLYOnHttpOnlyflag to the native PHP session cookie so browser scripts cannot read it. See the note below.PHP_SESSION_COOKIE_HTTPONLYnow defaults toOnPHP recommends
session.cookie_httponly=Onfor production, so the images now ship it that way. Laravel, Symfony, and WordPress manage their own session cookies and are not affected. If your app callssession_start()directly and reads the session cookie from JavaScript, setPHP_SESSION_COOKIE_HTTPONLY=Offto keep the previous behavior (#692).Added a ton of CI improvements
We want to ensure we're validating everything and optimizing builds before they get published, so we spent a lot of time improving this very important process so we can have the robots do the hard work for us. Read more about how this works in #700
Debian stopped signing packages for Debian 11 (Bullseye) on 2026-09-07. Without a signed repository,
apt-get updatefails inside the build and we can't produce a patched image at all. PHP 7.4 and 8.0 only ever shipped on Bullseye and Alpine 3.16, so both go with it. PHP 8.1 has been unbuildable since 2025-12-16, when upstream removed the8.1branch.Your existing tags still work. Every
7.4,8.0, and8.1tag stays pullable, frozen at its last successful build — they just won't get security updates anymore.Our supported matrix is now PHP 8.2 – 8.5 on
bookworm,trixie,alpine3.23, andalpine3.24. We also updatedSECURITY.mdto make the rule explicit: we publish images on an EOL base only for as long as that distribution still serves a signed package repository.dependencies.d/If your Dockerfile appends lines to
/etc/s6-overlay/s6-rc.d/<service>/dependenciesforphp-fpm,nginx, orapache2, S6 now ignores that file. Create an empty file independencies.d/instead:RUN touch /etc/s6-overlay/s6-rc.d/nginx/dependencies.d/my-serviceStock images and rootless containers are not affected (#689).
👨💻 DX improvements
composer install(Improve verbosity for log output #671)🐛 Bug fixes
All variations
LARAVEL_AUTORUNon modern Laravel versions (Add import for DB facade #673, fixes Laravel autorun failing on database connection. #672)All web servers (FrankenPHP, NGINX, Apache)
DISABLE_DEFAULT_CONFIGis true (Do not generate SSL if DISABLE_DEFAULT_CONFIG is set #644)NGINX and Apache
fpm-nginxandfpm-apachefailing to start with s6-overlay 3.2.3 (Improve CI builds #700)Apache
.well-known(Apache: Change DirectoryMatch to LocationMatch in Apache security configuration #652, fixes Apache to denying requests to .well-known #649)FrankenPHP
⏫ Dependency Updates