Release 4.0: Add FrankenPHP & more Laravel optmizations

.cursor/rules

@@ -0,0 +1,24 @@
+You are a highly skilled PHP system administrator tasked with maintaining open source PHP Docker images for Laravel applications. Your goal is to assist in creating production-ready Docker images that follow best practices for security, performance, and developer experience using the guidelines below. 
+
+1. Skills you posses deep knowledge and best practices of:
+  - Docker
+  - PHP
+  - Laravel
+  - GitHub Actions
+  - Shell scripting
+  - S6 Overlay
+  - Nginx
+  - Apache
+  - NGINX Unit
+  - PHP-FPM
+
+2. Development Guidelines:
+
+  - Follow the best practices for security, performance, and developer experience.
+  - Write clean, maintainable and technically accurate code.
+  - All entrypoint scripts for the Docker images must be POSIX compliant and able to be executed with /bin/sh.
+  - Any /bin/sh scripts must be compatible with Debian and Alpine Linux.
+  - For any /bin/bash scripts, these should work with MacOS, Linux, and WSL2.
+  - Never use an approach you're not confident about. If you're unsure about something, ask for clarity.
+
+This project is open source and the code is available on GitHub, so be sure to follow best practices to make it easy for others to understand, modify, and contribute to the project.

.github/workflows/action_update-dockerhub-readme.yml

@@ -14,7 +14,7 @@ jobs:
     name: Push README to Docker Hub
     steps:
       - name: git checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: main
 

.github/workflows/scheduled-task_update-sponsors.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Generate Sponsors 💖
         uses: JamesIves/github-sponsors-readme-action@v1

.github/workflows/service_docker-build-and-publish.yml

@@ -15,10 +15,6 @@ on:
         type: string
         default: 'scripts/conf/php-versions.yml'
         description: 'The path to the PHP versions file.'
-      default-image-variation:
-        type: string
-        default: 'cli'
-        description: 'The default PHP variation to use for the Docker image.'
       registry-repositories:
         type: string
         required: true
@@ -43,7 +39,7 @@ jobs:
       php-version-map-json: ${{ steps.get-php-versions.outputs.php-version-map-json }}
     steps:
     - name: Check out code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
       with:
         ref: ${{ inputs.ref }}
 
@@ -84,12 +80,12 @@ jobs:
 
     steps:
       - name: Check out code.
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ inputs.ref }}
 
       - name: Download PHP Versions file
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           name: php-versions.yml
           path: ./artifacts
@@ -127,7 +123,6 @@ jobs:
           ./scripts/assemble-docker-tags.sh
         env:
           PHP_VERSIONS_FILE: "${{ inputs.php-versions-file }}"
-          DEFAULT_IMAGE_VARIATION: ${{ inputs.default-image-variation }}
           PHP_BUILD_VERSION: ${{ matrix.patch_version }}
           PHP_BUILD_VARIATION: ${{ matrix.php_variation }}
           PHP_BUILD_BASE_OS: ${{ matrix.base_os }}

docs/content/docs/2.getting-started/1.these-images-vs-others.md → docs/content/docs/1.getting-started/1.these-images-vs-others.md

@@ -22,7 +22,7 @@ layout: docs
 | Built-in security optimizations | ❌ | ✅ |
 | Optimized for Laravel & WordPress| ❌ | ✅ |
 | NGINX + FPM variation| ❌ | ✅ |
-| NGINX Unit variation| ❌ | ✅ |
+| FrankenPHP variation| ❌ | ✅ |
 | Native health checks | ❌ | ✅ |
 
 ## Unprivileged by Default

docs/content/docs/2.getting-started/2.installation.md → docs/content/docs/1.getting-started/2.installation.md

@@ -13,6 +13,42 @@ layout: docs
 All images are hosted on [DockerHub](https://hub.docker.com/r/serversideup/php) and [GitHub Packages](https://github.com/serversideup/docker-php/pkgs/container/php)  for free. Containers default to running Debian, but Alpine images are also available.
 ::
 
+## What's Docker?
+[Docker](https://www.docker.com/) is an open source utility for building, shipping, and running applications in containers. Containers are isolated environments that can run on any host. 
+
+![Docker Layers with Laravel Application](/images/docs/docker-layers.png)
+
+### Why containerize with Docker?
+Going through the efforts of containerizing your application gives you one extremely powerful capability:
+
+👉 **You can run your application anywhere**
+
+Once you're at this level, you unlock a ton of new possibilities:
+
+- **Your application runs the same, everywhere** - no more "it works on my machine". Run 100% of your application on any operating system. All they need is Docker installed.
+- **Ship with more confidence** - all infrastructure configurations are *centrally managed* in Git, so you can change, test and rollback with ease
+- **No more vendor lock-in** - if a host raises their prices on you, you can migrate with very little effort
+- **Scaling is a breeze** - once you get your application in one container, it's so easy to scale up to any number of containers
+- **Improved security** - containerized apps are more secure than traditional apps because they are isolated from the host
+- **Better uptime** - if something fails during deployment, you can roll back your application to a previous version with ease
+
+The even crazier part is you don't need a Platform as a Service (PaaS) to get all these benefits. Everything can be done with 100% free and open source tools.
+
+## How to get started with Docker
+At first, Docker may seem a little intimidating, but don't let that stop you. Docker is one of the most powerful skill-sets that we've learned in our career.
+
+Although teaching you how to use Docker is beyond the scope of serversideup/php, we've actually created another open source project called [Spin](https://serversideup.net/open-source/spin/) that dramatically reduces the learning curve for getting started with Docker.
+
+Here's a quick demo of Spin of what an app looks like when we use Docker from development to production:
+
+::video-embed
+---
+src: https://www.youtube.com/watch?v=5z2JoEt5XIk
+---
+::
+
+[Learn more about Spin →](https://serversideup.net/open-source/spin/)
+
 ## Our most popular images
 All images are intelligently tagged with the PHP version and variation. This allows you to easily select the right image for your use case. 
 
@@ -28,28 +64,53 @@ Our most popular tags include:
 | unit         | <span class="font-bold text-white">Debian Based</span><span class="not-prose mb-1 block">[![serversideup/php:8.4-unit](https://img.shields.io/docker/image-size/serversideup/php/8.4-unit?label=serversideup%2Fphp%3A8.4-unit)](https://hub.docker.com/r/serversideup/php/tags?name=8.4-unit&page=1&ordering=-name)</span><span class="not-prose mb-1 block">[![serversideup/php:8.3-unit](https://img.shields.io/docker/image-size/serversideup/php/8.3-unit?label=serversideup%2Fphp%3A8.3-unit)](https://hub.docker.com/r/serversideup/php/tags?name=8.3-unit&page=1&ordering=-name)</span><span class="not-prose mb-1 block">[![serversideup/php:8.2-unit](https://img.shields.io/docker/image-size/serversideup/php/8.2-unit?label=serversideup%2Fphp%3A8.2-unit)](https://hub.docker.com/r/serversideup/php/tags?name=8.2-unit&page=1&ordering=-name)</span><span class="not-prose mb-1 block">[![serversideup/php:8.1-unit](https://img.shields.io/docker/image-size/serversideup/php/8.1-unit?label=serversideup%2Fphp%3A8.1-unit)](https://hub.docker.com/r/serversideup/php/tags?name=8.1-unit&page=1&ordering=-name)</span><span class="not-prose mb-1 block">[![serversideup/php:8.0-unit](https://img.shields.io/docker/image-size/serversideup/php/8.0-unit?label=serversideup%2Fphp%3A8.0-unit)](https://hub.docker.com/r/serversideup/php/tags?name=8.0-unit&page=1&ordering=-name)</span><span class="not-prose mb-1 block">[![serversideup/php:7.4-unit](https://img.shields.io/docker/image-size/serversideup/php/7.4-unit?label=serversideup%2Fphp%3A7.4-unit)](https://hub.docker.com/r/serversideup/php/tags?name=7.4-unit&page=1&ordering=-name)</span> |
 
 ## Selecting the right variation
-There are 4 main variations.
+We offer a number of different variations to suit your needs. Each variation is optimized for specific use cases.
 
 ### CLI
-If you need to run a quick command with something like `composer` or use PHP to run a CLI program only, this might be a great option for you.
+The CLI variation is a minimal image designed for running PHP from the command line only. It does not include a web server.
+
+Use this variation for running commands like Composer, running scheduled tasks, or executing PHP scripts that don't require a web server.
+
+[Learn more about CLI →](/docs/image-variations/cli)
 
 ### FPM
-The `fpm` variation is great for people who need to run a PHP "backend" if they already have a proxy serving static content. If you're using FPM only, that means you're probably at a larger scale.
+The FPM (Fast Process Manager) variation runs PHP-FPM without a web server. This variation is ideal for microservices architectures where you need a dedicated PHP backend.
+
+Use this variation when you already have a separate proxy or load balancer handling static content and routing PHP requests to your FPM container. This is commonly used in larger-scale deployments.
+
+[Learn more about FPM →](/docs/image-variations/fpm)
 
 ### FPM-Apache
-The `fpm-apache` variation is meant for users who want to run something like WordPress with Docker. Apache is configured to be a "reverse proxy", which will serve any static content with Apache and serve any PHP requests with PHP-FPM. Since there are two processes required to run this variation, we use [S6 Overlay](/docs/guide/using-s6-overlay) to ensure the container health is accurate.
+The FPM-Apache variation combines PHP-FPM with Apache as a reverse proxy. Apache serves static content directly and forwards PHP requests to PHP-FPM for processing.
+
+Use this variation for applications like WordPress that benefit from Apache's .htaccess support and mod_rewrite functionality. This is a production-ready setup using S6 Overlay to manage both processes reliably.
 
-[Learn more about using Docker with WordPress →](/docs/guide/using-wordpress-with-docker)
+[Learn more about FPM-Apache →](/docs/image-variations/fpm-apache) | [Using Docker with WordPress →](/docs/guide/using-wordpress-with-docker)
 
 ### FPM-NGINX
-The `fpm-nginx` variation is great for people who want to run Laravel applications or similar. This allows you to serve static content quickly with NGINX but also pass PHP requests to PHP-FPM. Similar to PHP-Apache, there are two processes required to run this variation. We use S6 Overlay to ensure the container health is accurate.
+The FPM-NGINX variation combines PHP-FPM with NGINX as a reverse proxy. This is the traditional setup that has been widely adopted for modern PHP applications, including many Laravel deployments.
+
+Use this variation for production Laravel applications and other PHP frameworks that require a stable, battle-tested web server configuration. We use S6 Overlay to ensure both processes run reliably in a single container.
+
+[Learn more about FPM-NGINX →](/docs/image-variations/fpm-nginx)
+
+### Unit (deprecated)
+::note
+In October 2025, NGINX stopped supporting NGINX Unit and archived the project. NGINX Unit will eventually be removed from our project. [See the official announcement →](https://github.com/nginx/unit?tab=readme-ov-file#nginx-unit)
+::
+
+The Unit variation uses NGINX Unit as a modern application server that runs everything in a single process.
+
+While this variation is being deprecated, it can still be used for existing applications. Consider migrating to FrankenPHP for a modern single-process alternative.
+
+[Learn more about Unit →](/docs/image-variations/unit)
 
-[Learn more about S6 Overlay →](/docs/guide/using-s6-overlay)
+### FrankenPHP
+The FrankenPHP variation is a modern application server built on top of the Caddy web server. It runs everything in a single process, eliminating the complexity of managing PHP-FPM and a separate web server.
 
-### Unit
-The `unit` variation is for NGINX Unit, which is a modern approach to delivering containerized web applications. Instead of relying on the complexities of two processes running NGINX + PHP-FPM, Unit replaces both the NGINX Web Server and PHP-FPM to run everything under one process. Unit is open source and maintained by the NGINX Unit team. 
+Use this variation for Laravel or Symfony applications that can benefit from worker mode, automatic HTTPS, and modern protocols like HTTP/2 and HTTP/3. This is the recommended variation for new projects seeking cutting-edge performance.
 
-[Learn more about Unit →](https://unit.nginx.org/)
+[Learn more about FrankenPHP →](/docs/image-variations/frankenphp)
 
 ## Selecting the version of PHP
 Selecting the best version of PHP is highly dependent on your use case. In a perfect world, running the latest version of PHP will give you the latest and greatest, but it all depends on the libraries that your application uses.

docs/content/docs/2.getting-started/3.default-configurations.md → docs/content/docs/1.getting-started/3.default-configurations.md

@@ -28,6 +28,7 @@ Since these images are not privileged, that means they are not running on ports
 | fpm-nginx | HTTP: 8080, HTTPS: 8443 |
 | fpm-apache | HTTP: 8080, HTTPS: 8443 |
 | unit | HTTP: 8080, HTTPS: 8443 |
+| frankenphp | HTTP: 8080, HTTPS: 8443 |
 
 ### How do I run these services on ports 80 and/or 443?
 Almost everyone will want to run these services on ports 80 and 443. If you have an advanced setup, you can use a reverse proxy like Caddy or Traefik to handle the SSL termination and forward the traffic to the container on the non-privileged port.
@@ -85,9 +86,11 @@ The following packages are installed by default:
 |-------------|-----------------|----------------------|------------------------|
 | `libfcgi-bin`<br/>(Debian)<br/>`fcgi`<br/>(Alpine) | FastCGI is a protocol for interfacing interactive programs with a web server. | *-fpm <br/> *-fpm-nginx <br/> *-fpm-apache | This is required for the webserver to interface with PHP-FPM and the [`php-fpm-healthcheck`](https://github.com/renatomefi/php-fpm-healthcheck) project.  |
 | `gettext-base` (Debian) <br/> `gettext` (Alpine) | GNU gettext is a framework for translating user interfaces. | *-fpm-nginx <br/> *-fpm-apache | This is required for the `envsubst` command. We use this command to process templates on container initialization. |
-| `procps` (Debian) | The procps package contains programs for monitoring your system and its processes. | * (Debian images) | This is required for `pgrep` so we can use that for our native health checks. |
+| `libstdc++6`<br/>(Debian)<br/>`libstdc++` (Alpine) | The GNU Standard C++ Library is a C++ standard library. | *-frankenphp | This is [required for the watcher to run](https://github.com/php/frankenphp/blob/e917ab79742c9e4703023861fdc7a86cdb59da1e/Dockerfile#L135-L138) with FrankenPHP. |
+| `procps` | The procps package contains programs for monitoring your system and its processes. | * (only Debian images) | This is required for `pgrep` so we can use that for our native health checks. |
 | `shadow` | Shadow is required for the `usermod` command. | *-alpine | This is required to change the UID and GID of the `www-data` user in `docker-php-serversideup-set-id`. |
 
+
 ## Health Checks
 By default, all health checks for web servers (Apache, Unit, NGINX, etc.) are located at `/healthcheck`. You should receive an `OK` response if the container is healthy.
 

docs/content/docs/2.getting-started/7.contributing.md → docs/content/docs/1.getting-started/7.contributing.md

@@ -117,16 +117,25 @@ label: "Update NGINX versions"
 
 Compute the Alpine key hash when updating:
 
+::code-panel
+---
+label: "Compute the Alpine key hash"
+---
 ```bash
 curl -sS https://nginx.org/keys/nginx_signing.rsa.pub -o /tmp/nginx_signing.rsa.pub
 # macOS
 openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -outform DER 2>/dev/null | shasum -a 256 | awk '{print $1}'
 # Linux
 openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -outform DER 2>/dev/null | sha256sum | awk '{print $1}'
 ```
+::
 
 Then build with the new hash (optionally include the old hash during rotation):
 
+::code-panel
+---
+label: "Build with the new hash"
+---
 ```bash
 docker build \
   --build-arg SIGNING_ALPINE_RSA_PUB_SHA256="<new-hash>,<old-hash>" \