FrankenPHP and Caddy: PHP inside the web server, speed, security and operations

FrankenPHP and Caddy in context: what worker mode delivers, how serious the wave of vulnerabilities is and how containers restart cleanly.

by ·

Caddy has been running for me for some years now as a proxy (a server that passes requests on to other services) and as a server for static sites, on a Linux root server of my own. Caddy is good, but it can't do PHP by itself. That's exactly what FrankenPHP adds. For me it has become a secure, high-performance and easy-to-manage solution that, together with Podman and Docker projects (containers, meaning isolated runtime environments for individual applications), provides quick solutions for all sorts of purposes, apps included. I use FrankenPHP for online and intranet apps, for a WordPress management console and for a knowledge base on Grav CMS.

So I like using it, and you still won't find advertising here. The well-known speed figures appear with their test conditions, and the security vulnerabilities of the last few weeks are discussed openly. If you've never heard of FrankenPHP: every section starts simple and then goes deeper.

The short version

Question Answer
What is it? The Caddy web server with PHP built in: one program instead of a web server plus PHP-FPM
Does PHP get faster? In classic mode roughly level with nginx and PHP-FPM. In worker mode, where the application stays in memory between requests, a factor of 1.5 to 2.9 in third-party measurements and measurements from around the project, but the application has to be suitable
WordPress and Grav? No controlled comparison found, and WordPress has no supported worker mode. With WordPress, I see the simpler operation as the argument rather than the speed
What about security? 40 published advisories (security notices), 34 of them between 4 October and 5 November 2026. Only the latest version is supported
What comes with the design? One process, one user: a crash hits everything, and PHP can reach the TLS keys (the secret keys behind HTTPS) and the admin API (Caddy's control interface)
What helps in operation? One project per container, a health check (a regular self-test) against real PHP, a restart on crashes and on hangs
Who is it not for? Classic shared hosting, and anyone who doesn't apply updates promptly

All of this refers to FrankenPHP 1.13.5 and Caddy 2.11.9, as of 9 November 2026. The wording keeps four things apart. "According to the docs" and "according to the source" mean read there. "Checked" means the example was reproduced in a throwaway container against FrankenPHP 1.13.5, purely as a functional check with no load. All performance figures come from other people's measurements, some of them from around the project, and appear with their conditions. Everything about Podman comes only from the docs and hasn't been tested.

What FrankenPHP is

A PHP website today usually runs on two programs: a web server such as Apache or nginx, which accepts requests from the network, and PHP-FPM, a separate service that executes the PHP scripts. The two talk to each other through an interface called FastCGI, and you have to set up, update and monitor both. FrankenPHP (opens in a new tab) builds PHP directly into the Caddy web server. You start a single program, and it accepts requests, takes care of HTTPS and executes PHP. According to the docs (opens in a new tab), that also works as a drop-in replacement for PHP-FPM or the Apache module mod_php, without having to rewrite your application.

Under the hood

Caddy is written in Go, PHP in C. FrankenPHP connects the two via cgo, Go's bridge to C code, and presents itself to PHP as its own SAPI, the interface PHP uses to talk to its environment. According to the internals docs (opens in a new tab), every PHP execution runs on a real operating system thread, a strand of execution inside a process: "Each PHP execution runs on a real POSIX thread (not a goroutine) because PHP's ZTS (Zend Thread Safety) model requires it."

ZTS is the build variant of PHP that can cope with several threads in the same process. Without ZTS, FrankenPHP forces a single thread and warns, according to the source (opens in a new tab). PHP 8.2 and later is supported, and the Docker images (opens in a new tab) are available for 8.2 to 8.5.

Nearly everything that matters in this article follows from this design: all requests share one process. A detail for the pros: according to the worker docs (opens in a new tab), umask() and setlocale() act process-wide, and in every mode: "in every mode they also affect requests running at the same time."

The project itself has a firm place in the PHP world. The PHP Foundation announced (opens in a new tab) its support in May 2025, and since June 2025 the code has lived in the PHP organization (opens in a new tab) on GitHub, under the MIT license. According to the May announcement (opens in a new tab), leadership stayed with the existing maintainers Kévin Dunglas, Robert Landers and Alexander Stecher: "The governance of the project remains unchanged." The Docker namespace, the name space of the images, is still called dunglas today. You'll find all the directives in the FrankenPHP cheat sheet.

Caddy as the foundation

Caddy is a web server whose best-known feature is automatic HTTPS. You write a domain name into the configuration, and Caddy obtains and renews the certificate itself. To do that it speaks ACME, the protocol through which certificate authorities such as Let's Encrypt issue certificates automatically. The configuration file is called the Caddyfile. For a PHP site, in the simplest case this is all you need, minimal form following the docs (opens in a new tab):

example.com {
	root /var/www/app/public
	php_server
}

I like that Caddy takes a lot of the HTTPS work off your hands, but there are a few settings you should check yourself. More on that in a moment. What FrankenPHP inherits from Caddy:

These are the points you should check yourself:

  • HSTS: The header that pins browsers to HTTPS for the long term doesn't come automatically. The Caddy docs (opens in a new tab) only show it as a manual example.
  • The data directory: Certificates and keys live there. "The data directory must not be treated as a cache", Caddy (opens in a new tab) writes. So in a container, /data and /config belong on a volume, storage that outlives the container.
  • The certificate authority: The docs (opens in a new tab) name two authorities as the default, but according to the source (opens in a new tab), ZeroSSL is only added with a stored email address. Without one you only get Let's Encrypt, as read from the code.
  • OCSP: This service lets you ask whether a certificate has been revoked, and with stapling the server delivers the answer along with the certificate. Let's Encrypt shut the service down in 2025 (opens in a new tab), so stapling no longer does anything for those certificates.

On raw speed, the picture is mixed. In a 2026 test (opens in a new tab), an unoptimized Caddy 2.10.2 came in at about half of an optimized nginx 1.24 for static files, measured over loopback (client and server on the same machine) without TLS. A better-controlled 2022 test (opens in a new tab) on separate machines saw a near tie for large static files and a mixed picture for small ones. As a proxy, an optimized nginx was clearly ahead, while Caddy led against nginx with default values at 10 and 200 clients. There's more on the configuration in the Caddy cheat sheet.

Performance

Classically, PHP starts from scratch on every request: the application boots, builds the page and clears everything away again. FrankenPHP's classic mode does exactly that, just in a thread instead of an FPM process. Worker mode, by contrast, loads the application once, keeps it in memory and hands it the requests one after another. That saves the repeated startup, and your application has to live with the fact that not everything gets cleaned up between requests anymore.

Classic mode: mostly a tie

On throughput, classic mode gains little, going by everything solid that's available. Tideways (opens in a new tab) tested FrankenPHP 1.9.1 against nginx 1.26.3 with PHP-FPM: a Hetzner CCX33 with 8 dedicated virtual cores (vCores), Debian 13, default configurations, Vegeta (a load generator), with 8 clients for 60 seconds. With gzip-compressed HTML the two were about 1.3% apart, with a Hello World about 0.4%, and the conclusion reads: "essentially no performance or throughput difference." With 100 clients FrankenPHP was 3.7% ahead on throughput, but clearly behind at the 99th percentile of response time (99 out of 100 requests were faster), 23.4 against 9.7 ms. That was before the work on tail latency (opens in a new tab), the slowest outliers, in 1.11.0, so today's value is probably better, but there's no figure for it.

A collaborator on the project first wrote in general terms in the discussion (opens in a new tab): "no performance difference between FrankenPHP (non-worker) and php-fpm." In a later run with wrk and PHP 8.4.14, FrankenPHP ranged from about 1% behind to 14% ahead, depending on the code sample. That isn't an independent source, but it roughly fits the picture. A Shopware measurement (opens in a new tab) from October 2026 saw PHP-FPM at 520 and classic mode at 559 requests per second, but the ranges overlapped, and according to the author the lab conditions weren't an isolated comparison (FPM on Alpine, an especially small Linux distribution, FrankenPHP on Debian, an Apple M4 VM).

One trap in any comparison: with a PDF that neither server compressed, Tideways saw PHP-FPM ahead at 7,610 against 5,369 requests per second, and with random data FrankenPHP ahead at 5,606 against 1,940, because nginx coped badly with incompressible responses. With no compression at all, FrankenPHP fell behind on HTML at 5,504 against 7,456 requests per second, so the tie isn't a fixed quantity. If you pit default values against each other, a good part of what you measure is the encoder and not PHP.

What classic mode really brings lies in operation: one process fewer, HTTP/3 and compression from the same program, and Early Hints (opens in a new tab), more on which below.

Worker mode: a real gain, with conditions

In worker mode, measurements show a real gap. With Sylius (opens in a new tab), worker mode reached 2.7 to 2.9 times PHP-FPM, measured by a developer from around the project (Les-Tilleuls.coop), though on a 2-vCPU machine, in a single run, with 36 workers against 15 FPM children (worker processes). The Shopware measurement mentioned above reached 1.75 times (911 against 520 requests per second) for write-free admin searches with gzip, and 1.5 times without compression. According to the author, that says nothing about the storefront. The author explicitly makes no production recommendation and warns: "avoiding repeated initialization makes object lifetimes part of application correctness".

The counterexample comes from Oh Dear (opens in a new tab), a service that spends a lot of time waiting on outgoing requests (360 to 470 ms, 12 hours of production traffic, 2 vCPU, around 20 requests per second). There, average CPU load stayed practically the same between FPM and Laravel Octane on FrankenPHP (21 against 22%, 25 against 22%), and only the peaks dropped noticeably (49 to 28%, 33 to 26%). Together the workers took up 600 to 670 MB, more than PHP-FPM, and the team went back to FPM. What you can conclude from that: if you mostly wait on other systems, you save little on application startup.

You need an application built for it. Symfony has supported worker mode natively since 7.4 (opens in a new tab), and Laravel does through Octane (opens in a new tab). In my view, worker mode pays off mainly when your framework officially supports it and you're prepared to watch out for state bugs. More on that in the security part.

Where the "3.5x" comes from

FrankenPHP's homepage says: "According to our benchmarks, 3.5x faster than FPM on API Platform apps." The associated test files (opens in a new tab) date from October 2022, the time before version 1.0. Testing was done with the load-testing tool k6 against localhost, with a one-second pause per iteration and no information on hardware or version. So what was measured is latency at about 10 and 100 requests per second, not a throughput limit.

100 virtual users Mean latency
PHP-FPM 9.45 ms
FrankenPHP with worker 2.53 ms
FrankenPHP without worker 12.72 ms

Recalculated, that gives a factor of 3.7 at 100 users and 2.8 at 10 users. The values without a worker aren't on the homepage. That deficit is no longer current; the more recent measurements see a tie. DevClass (opens in a new tab) also described the same benchmark as Hello World Symfony. I wouldn't hand you the 3.5x from the homepage as an argument. The test files date from 2022, and without a worker FrankenPHP was behind PHP-FPM there.

WordPress and Grav

For WordPress or Grav there's no controlled comparison between FrankenPHP in classic mode and nginx with PHP-FPM, at least none could be found. WordPress has no supported worker mode. The WordPress page of the docs (opens in a new tab) doesn't even contain the word "worker", and according to DevClass (opens in a new tab), Dunglas said in 2024 that WordPress brings "not many benefits in terms of performance". The claim "up to 4x faster than with PHP-FPM" in Caddy's docs examples (opens in a new tab) names no test conditions and doesn't fit the measurements above, which weren't taken on WordPress, though. No statement on Grav's suitability for worker mode could be found.

My impression is that WordPress and Grav run at least as well without worker mode as they do with nginx and PHP-FPM. That's explicitly a feeling and not a measured value. With WordPress, I'd recommend FrankenPHP to you for the simpler operation rather than for the speed.

That doesn't complete the picture. Issue #1737 (opens in a new tab) describes crashes with several WordPress sites caused by a race condition (two threads getting in each other's way in time) around opcache_reset, reported for 1.8.0 and open on the cutoff date. Since 1.12.5, according to PR #2364 (opens in a new tab), FrankenPHP intercepts opcache_reset() and schedules a restart of the PHP threads instead. Whether that eliminates the reported crashes isn't confirmed in the issue. Issue #2553 (opens in a new tab) reports heavily slowed sites with 1.12.x; the status on 1.13.x is unknown.

Tuning knobs

  • Threads: Without a worker, FrankenPHP starts with 2 threads per CPU according to the source (opens in a new tab), and without max_threads set it doesn't scale up. The docs (opens in a new tab) advise changing the defaults ("We strongly recommend changing these values.") and determining them by load test, and give max_threads x memory_limit < available_memory as a rule of thumb. Since 1.13.0 (opens in a new tab), num_threads only counts threads outside the workers, so existing configurations may behave differently.
  • glibc instead of musl: The docs recommend glibc for production. Alpine images and the standard binaries use musl, a different C library under which ZTS is especially costly. The Debian images are therefore the recommended choice, and static -gnu binaries are available too.
  • ZTS: On the PHP development list, Marc Henderkes estimates (opens in a new tab) the worst-case cost at around 5% for PHP 8.5 and 1.5% for 8.6. No setup for this has been published.
  • OPcache: According to the Dockerfiles of the base images (opens in a new tab), the bytecode cache, which stores compiled PHP code, is active; tuning it is up to you. If the cache has to rebuild its memory, that can crash the process under ZTS, according to the metrics docs (opens in a new tab): "The counter should stay at zero". Watch frankenphp_opcache_restarts and increase opcache.memory_consumption if needed.
  • php_server convenience: The file checks cost a little. The docs name a narrowed try_files or file_server off as levers, without giving a magnitude.
  • The Go runtime's memory limit: According to the source (opens in a new tab), Caddy sets GOMEMLIMIT automatically, so with the default factor of 0.9 (opens in a new tab) of the automemlimit library to 90% of available memory, and that doesn't count C memory (opens in a new tab), so not the memory PHP takes up either. With tight container limits, an OOM kill (the kernel ending the process for lack of memory) is therefore conceivable, which is a conclusion.

With Early Hints (HTTP status 103), the server tells the browser what it can load ahead of time, before the page is finished. FrankenPHP provides its own function for this, in both modes:

<?php
header('Link: </style.css>; rel=preload; as=style');
headers_send(103);

It's checked that the 103 also gets through a Caddy in front, over HTTP/1.1 and HTTP/2. The "30%" from the docs comes without test conditions.

Security

An advisory is a published security notice about a piece of software. Lots of these notices have appeared for FrankenPHP lately, and at first the numbers sound threatening. Here they are with some context.

The wave in numbers

On the cutoff date the repository lists (opens in a new tab) 40 published advisories: 1 critical, 10 high, 20 medium, 9 low. 34 of them were published between 4 October and 5 November 2026, spread across releases 1.13.0, 1.13.2, 1.13.4 and 1.13.5. 1.13.5 (opens in a new tab) alone closed 17.

Putting that in context takes more than the total:

  • The only critical advisory, GHSA-x9p2 (opens in a new tab), doesn't concern a flaw in the code but the delayed propagation of fixes from the base images, and has been fixed since February.
  • The recurring class with the most severe consequence is path splitting, the question of which part of a URL is the script to execute. Five advisories from February to November concern it, most recently GHSA-j99q (opens in a new tab): "/uploads/photos.php.php/avatar.jpg ran avatar.jpg as PHP." There, one trigger arose from the fix for an earlier report.
  • Many reports concern the boundary between Go and C, or only worker mode. But some can be reached from outside without logging in: GHSA-5359 (opens in a new tab) crashed the entire process, and according to the advisory: "A few dozen requests on two connections were enough in testing." PHP default values such as display_errors=1, meaning Docker without a php.ini of your own, helped make that possible. Fixed in 1.13.5.
  • Severity ratings aren't a fixed quantity. With Caddy, GitHub and the US vulnerability database NVD sometimes diverge widely, "medium" against 9.1 out of 10 points on the CVSS scale.

Where does the wave come from? For the latest surge, the release notes for 1.13.5 name the source: "Most of these vulnerabilities were found by Anthropic's OSS Scanner". I have to disclose that, because I work with AI from Anthropic as well: Claude supports me with creation, correction and verification, while the direction and the editorial responsibility are mine. There's more on that on the AI transparency page. All 17 advisories of this release list the scanner as the finder, two of them naming further reporters alongside it. In the 17 advisories from 1.13.0, 1.13.2 and 1.13.4, by contrast, Anthropic's scanner doesn't appear. Caddy sees the same situation from the other side. The notes for 2.11.4 (opens in a new tab) attribute the wave of patches to AI models and say more than 75% of the security reports had to be rejected because they were "AI slop spam" or wrong. Caddy's list (opens in a new tab) has 23 entries, all from 2026. PHP/FastCGI is among the most frequently affected areas there, alongside the request matchers (the Caddy rules that select requests), and 2.11.9 calls its fixes "mostly in FastCGI". So the wave doesn't only hit FrankenPHP.

I take the wave of advisories seriously, and you should too. For me, though, it speaks more for the fact that thorough searching and fixing is going on right now than against the project.

How fast the projects respond

What I value about this ecosystem is the close and very active cooperation between the PHP, FrankenPHP and Caddy communities, which respond quickly to problems like these. Here's what backs that up: FrankenPHP lives in the PHP organization and is supported by the PHP Foundation, fixes to Caddy partly come from Dunglas himself (opens in a new tab), and Caddy 2.11.9 arrived in FrankenPHP 1.13.5 on the same day.

The gap between a PHP security release and the first surviving Docker tag (opens in a new tab), the version name of an image, has recently looked like this:

PHP release Gap (at most)
8.5.6, 7 May 2026 7 days
8.5.8, 2 July 2026 18 days
8.5.9, 30 July 2026 8 days
8.5.11, 24 September 2026 1 day
8.5.12, 21 October 2026 same day

Docker Hub only knows the last push of a tag, so the values of 7, 18 and 8 days can come out too high because of later re-pushes. For catching up with Caddy there are only the two most recent cases, around one day each, and there's no written commitment on this. I give the project a lot of credit for how quickly the patched images appeared lately. I wouldn't rely on it, though, so you should keep an eye on it yourself.

PHP2Shell and FrankenPHP

The vulnerabilities that became known under the name PHP2Shell are described in detail in a separate article. FrankenPHP is among the vulnerable SAPIs: the PHP advisory (opens in a new tab) names it in a source analysis alongside mod_php; no demonstrated exploit against FrankenPHP is available. PHP 8.5.12 and the parallel versions came out on 21 October, and 1.13.2 (opens in a new tab) names the fix as the first release. The practical minimum today is 1.13.5.

The fix itself has a side effect that hits FrankenPHP in particular: memory_limit has been soft since then, and above a hard limit (by default double the limit, and from 1 GiB upward memory_limit plus 1 GiB) the process ends. The Known Issues (opens in a new tab) say about this: "every in-flight request is lost and the server stops until it is restarted." With PHP-FPM, only one child process dies in this case. That's why the section on restarts further down is mandatory.

Only the latest version

The project says it briefly in its security policy (opens in a new tab): "Only the latest version is supported." With Caddy, the same applies (opens in a new tab) to the latest 2.x. For me, FrankenPHP only belongs where you really do apply updates promptly. Only the latest version is supported, and older tags stay where they are.

According to the build script (opens in a new tab), daily rebuilds only target the latest release. What reaches you therefore depends on how you installed it:

Route What happens What you have to watch
Docker, current release Rebuilt on every release and daily at 04:00 UTC if the PHP base has changed A pull alone isn't enough for derived images, your own images that build on the official one with FROM. Rebuild yours
Docker, older tags Frozen. 1.12.7-php8.4 was last pushed on 25 September, without the PHP2Shell fix Don't leave old lines lying around
Linux packages (deb, rpm, apk) A maintainer's repository. PHP is packaged separately Plan for normal package updates
Static binaries Rebuilt nightly, PHP 8.5 only Checksums you've pinned can break; verify the signed provenance attestations
Your own build with xcaddy, the tool that compiles plugins into a custom binary Nothing arrives by itself Rebuild on every security release

The rule about derived images comes from GHSA-cj57 (opens in a new tab): "pulling alone is not enough for images you have already derived." A pinned tag like 1.13.5 stops moving with the next release at the latest, and then you have to raise it yourself.

One process for everything

With PHP-FPM, the individual sites are separated by pools, meaning separate groups of processes with their own user. FrankenPHP works differently, and that has consequences. The security model (opens in a new tab) says it openly: PHP application code counts there as "Trusted by provenance", meaning deployed by the operator. Once foreign code is running, such as an uploaded web shell (a script attackers use to run commands), this model no longer protects you.

Topic PHP-FPM with pools FrankenPHP
Crash Hits one child process Hits all requests and sites of the process
User per site A separate user per pool One user per deployment
PHP settings per site php_admin_value per pool Only globally via php_ini
TLS keys Not readable with Caddy under a different user Readable by PHP, checked also as non-root
Admin API Can be separated via a Unix socket (a local connection through a file whose permissions you can set) Reachable by PHP without authentication

Here's how that was checked: a PHP script read the private keys in the data directory in both runs, also with --user 1000:1000, because it has the same user ID (UID) as Caddy. php_ini inside php_server leads to a configuration error; only the global frankenphp block knows it. In addition, according to a maintainer's statement (opens in a new tab), threads can't run under a different user than their process. open_basedir, which restricts PHP file access to certain directories, isn't a security boundary anyway, according to the PHP manual (opens in a new tab).

With one container per project, I consider the shared process acceptable, because that keeps your blast radius small, meaning what a single crash takes down with it. In my view, you should consciously plan for PHP's proximity to the admin API and the keys, for example with admin off or a Caddy in front. As a conclusion from this, static sites are better off on a plain Caddy than in the FrankenPHP process.

Webroot and uploads

The webroot is the directory the server puts on the network, and a typical stumbling block there is unspectacular. php_server sends .php files to PHP and hands everything else to a file server. A Caddyfile with only root and php_server delivered /.env, /.git/config and /.htaccess with their contents in the test. Backups such as wp-config.php.bak came through as source code, credentials included. Every .php file in the webroot runs, also in wp-content/uploads, also as .PHP.

Caddy's own WordPress rule (opens in a new tab) with /wp-content/uploads/*.php only reaches one level deep. Under /wp-content/uploads/2026/11/x.php the script kept running, and /xmlrpc.php/foo gets around the exact path /xmlrpc.php. That's checked on php_server. FrankenPHP doesn't evaluate .user.ini, also checked, and Apache rules from .htaccess don't apply under Caddy. The Docker quick start (opens in a new tab) with COPY . /app/public also copies the entire build context into the webroot. So separate public/ from everything else.

Risks in worker mode

In worker mode the PHP process stays alive between requests, and with it, state survives too. According to the release notes for 1.13.5 (opens in a new tab), only "superglobals (except $_ENV), the request body, response headers and output, the session and the URL rewriter" get reset. Everything else stays, including static variables and global objects. Frameworks soften this, according to the worker docs (opens in a new tab): "Frameworks like Symfony and Laravel Octane take care of resetting most state for you, but you may still need to reset your own services."

Even the state FrankenPHP does intend to reset has slipped through before. GHSA-8qcf (opens in a new tab) describes: "A client without any cookie could receive the body output and Set-Cookie headers emitted by the previous user's session objects." And 1.13.5 deliberately took back two published fixes: error_get_last(), http_get_last_response_headers() and libxml errors persist in the worker again. The advisories still count as patched, so a scanner reports "fixed", and you have to clean up in the application yourself (error_clear_last(), libxml_clear_errors(), http_clear_last_response_headers()).

Securing and running Caddy

A web server can be controlled while it's running, and Caddy offers an interface for that: the admin API. It's convenient and at the same time the most important point in hardening, because every PHP script on the same machine can reach it.

The admin API

By default it listens on localhost:2019 according to the Caddy docs (opens in a new tab), with no authentication. The result is checked: file_get_contents('http://localhost:2019/config/') from PHP returned the entire configuration, and a POST /load from PHP replaced it. After that the site only answered with the text that had been loaded, and PHP no longer ran. The docs recommend a permissioned Unix socket, but that doesn't help against PHP with the same UID: as checked, PHP also got at the configuration via the socket, HTTP 200.

That leaves admin off. It has costs: frankenphp reload no longer works, the endpoints for restarting workers and for /frankenphp/threads go away, the HEALTHCHECK built into the image fails (checked: permanently unhealthy, so you need a check of your own), and metrics need the global metrics option plus a metrics block (opens in a new tab) of your own in a site. A reload still works via the SIGUSR1 signal, checked, although one request in the reload window can fail.

Limits, proxies and headers

The checked final version, with the address :8080 in the test:

caddyfile
{
	admin off
	servers {
		trusted_proxies static 172.30.0.2/32
		trusted_proxies_strict
	}
	frankenphp {
		php_ini memory_limit 256M
		php_ini expose_php Off
		php_ini post_max_size 32M
		php_ini upload_max_filesize 32M
	}
}

example.com {
	root /var/www/app/public
	request_body {
		max_size 32MB
	}
	php_server
}

What this block does, and what it doesn't:

  • request_body: Caddy has no limit of its own. With max_size and a post_max_size that isn't lower, the check got a 413, with Content-Length as well as with chunked, meaning data of no length known in advance. If post_max_size stayed at the default of 8 MB, the 413 almost always failed to appear with chunked, and at 33 MB a 200 came back with a PHP warning. Without the directive, an oversized body also got a 200 and a PHP warning in the text, and $_POST stayed empty. But post_max_size doesn't limit php://input: in the test it was only empty when the client sent Expect: 100-continue, as curl does with large bodies with Content-Length. Without that header the whole body arrived, and likewise with chunked. So don't set post_max_size below max_size, and for uploads that also goes for upload_max_filesize.
  • Timeouts: read_header has been at 1 minute since 2.9.0, and 1 minute of idle each for reading and writing was added, announced in the notes for 2.11.6 (opens in a new tab). php_server additionally sets a 60-second timeout on body reads. In 1.13.0 to 1.13.4 Caddy defeated it, and only 1.13.5 (opens in a new tab) fixes that. According to the advisory, that doesn't yet fully cover bodies PHP doesn't read at the start of the request, such as with PUT.
  • trusted_proxies: Without this option, Caddy trusts no one. Enter your proxy's real address. That changes {client_ip} and the logs, while $_SERVER['REMOTE_ADDR'] stays the proxy, according to the test. So your application has to evaluate X-Forwarded-For, the header with the original client address, by itself, and the HTTPS detection also depends on the TLS state of the connection (opens in a new tab). In the test, the client_ip matcher hit the forged address as soon as the sender was trusted as a proxy.
  • Not covered: admin off takes away the API risk, not PHP's ability to read the keys.

Three more points. In the official Docker builds (opens in a new tab), the Server header gives away FrankenPHP Caddy. expose_php Off only removes X-Powered-By. And HTTP/3 allows 0-RTT, requests sent already during connection setup, which can be replayed according to the docs (opens in a new tab). According to the source, PHP learns nothing of this. The docs give @early_data tls early_data plus respond @early_data 425 "Too Early". With that order, however, Caddy answers with 500 instead of 425, checked on a path matcher, because the first argument counts as the body. The correct form is respond @early_data "Too Early" 425. A real 0-RTT request hasn't been tested. The practical exploitability hasn't been assessed.

Plugins cost updates

If you want rate limiting (limiting requests per client), a web application firewall or DNS modules, you need a custom build. Besides Caddy, the standard build only contains the Brotli, Mercure and Vulcain (opens in a new tab) modules. Additional plugins are built in via xcaddy, which compiles them into a custom binary, with the builder image (opens in a new tab).

That has a price that packages and images otherwise spare you. As a conclusion: every security release demands a rebuild, and every plugin has to match the Caddy version. The web application firewall coraza-caddy (opens in a new tab) and the CrowdSec bouncer (opens in a new tab), which connects Caddy to the CrowdSec blocklist system, are active, and their go.mod named Caddy 2.11.7 on the cutoff date. That isn't necessarily a lag, since Caddy asks plugin authors to raise the dependency only for API changes. caddy-ratelimit (opens in a new tab) has no releases and says of itself: "This is not an official repository of the Caddy Web Server organization." For the caddy-security plugin for single sign-on (SSO), Trail of Bits (opens in a new tab) reported ten vulnerabilities in 2023; the current state hasn't been checked.

Caddy in front or FrankenPHP alone

The docs' default (opens in a new tab) is FrankenPHP as the sole server with ports 80, 443 and 443/udp. That's simple, and your certificates are where PHP runs too. A separate Caddy in front keeps the keys out of the PHP container and leaves static sites outside the blast radius. No primary measurement of the cost of the extra layer could be found. On the outside, this is enough:

example.com {
	reverse_proxy frankenphp:8080
}

On the inside, with no HTTPS of its own and the outer Caddy as a trusted proxy:

caddyfile
{
	auto_https off
	servers {
		trusted_proxies static 172.30.0.2/32
		trusted_proxies_strict
	}
}

:8080 {
	root /app/public
	php_server
}

The outer block is checked via validate, and the setup of both ran in the test, with the test network's addresses. In it, the outer Caddy discarded a forged X-Forwarded-For, and on the inside client_ip was correct.

HTTPS in the intranet

Internal services often have no public domain. Caddy solves that with its own local certificate authority. skip_install_trust makes sure its root certificate doesn't automatically end up in the trust store, the system's list of trusted certificates:

caddyfile
{
	skip_install_trust
}

intranet.internal {
	tls internal
	root /var/www/app/public
	php_server
}

Checked: without the root certificate, curl fails with exit 60, and with --cacert root.crt you get HTTP 200 over HTTP/2. The leaf certificate, the certificate of the site itself, lives for 12 hours (opens in a new tab), the root for around 3,600 days. For .internal, Caddy chose the local issuer in the test even without tls internal. Caddy generates the root certificate in the data directory on first start, so in a container at /data/caddy/pki/authorities/local/root.crt. Distributing it (opens in a new tab) is your job: "it is the system administrator's responsibility".

For internal services I find tls internal handy, as long as you plan for distributing the root CA. For public names in the intranet, that leaves DNS-01, the ACME validation via a DNS record with no open ports. For that, Caddy needs a module for your DNS provider (opens in a new tab), which the standard build lacks, so you need xcaddy. With acme_server (opens in a new tab), Caddy can also issue certificates itself for other internal servers.

Practical building blocks

The following examples are excerpts. Each comes with what it doesn't do.

WordPress

The WordPress core (opens in a new tab) recognizes FrankenPHP, so permalinks work without .htaccess. You still need the rules. This block is checked via validate and for behavior, with :8080 as the address:

caddyfile
example.com {
	root /var/www/wordpress
	encode zstd br gzip

	@uploads_php path_regexp (?i)^/wp-content/uploads/.*\.php
	respond @uploads_php 403

	@uploads_dir path_regexp (?i)^/wp-content/uploads(/.*)?/$
	respond @uploads_dir 403

	@hidden {
		path_regexp (^|/)\.
		not path_regexp ^/\.well-known(/[^./][^/]*)+$
	}
	respond @hidden 403

	@private path_regexp (?i)^/(wp-config\.|xmlrpc\.php)|\.sql$
	respond @private 403

	php_server
}

The rules need path_regexp because .*, unlike path, also crosses slashes. @uploads_php deliberately has no $ anchor, so that /x.php/extra is covered too. @uploads_dir is needed because php_server runs the index.php inside a directory URL, and that URL doesn't contain .php at all. Without this rule, an uploaded index.php under /wp-content/uploads/evil/ ran in the test. As checked, //wp-content/…, x%2ephp, dot segments and /XMLRPC.php also stayed blocked, while ACME paths under /.well-known/ stayed open. The order in the text doesn't matter outside route, because Caddy's fixed directive order puts respond before php_server.

The block only blocks paths. PHP outside uploads keeps running, including a file a plugin has dropped somewhere. Blocking xmlrpc.php can hit apps and plugins. Backups other than *.sql and wp-config.* get delivered. .phtml and .phar don't run, but come through as text. It was tested on fake files, not on a real installation.

For a page cache you need an application-level solution, because the standard build has no (opens in a new tab) counterpart to nginx fastcgi_cache. Behind a Caddy that accepts HTTPS and passes it on unencrypted, the X-Forwarded-Proto handling (opens in a new tab) belongs in wp-config.php.

Grav

Grav ships its own Caddy configuration (opens in a new tab). Checked on Grav 2.2.28: you keep the matchers, php_server replaces the end with try_files, php_fastcgi and file_server, and the route block goes away. One more rule is needed, because under php_server, /file.php/whatever runs too, and Grav's rules ending in $ let that through in the literal translation:

@path_info path_regexp (?i)\.php/
respond @path_info 403

The Docker image also doesn't include everything Grav requires. Without gd and zip it reports a 500:

FROM dunglas/frankenphp:1.13.5
RUN install-php-extensions gd zip

In the test, the Grav files were added via COPY as well. Only Grav core without the admin plugin is checked, in classic mode and sequentially. system/ and vendor/ are blocked by file extension, not across the board.

Containers in general

According to the docs (opens in a new tab), the Debian images are the recommended choice. They don't come with a php.ini of their own, so the built-in defaults apply, including display_errors=1, which helped make GHSA-5359 possible. So copy php.ini-production, as the production docs (opens in a new tab) say. By default the container runs as root; non-root is opt-in and doesn't protect the keys from PHP. Under Podman, a rootless container, one running without root privileges, can't bind below port 1024, according to the docs (opens in a new tab). net.ipv4.ip_unprivileged_port_start only loosens that host-wide; the basics are in the Podman cheat sheet.

Servers sometimes go down. With FrankenPHP, a single fault takes the entire process with it, and that's why something should restart it automatically. My containers use health checks. The route below is the general recommendation, checked under Docker, and for Podman only according to the docs.

There are two different failures here, and they need different remedies:

  • The process dies, for example through a segfault or a panic (hard program crashes in C and Go respectively) or through a hard memory limit. The container ends, and a restart policy starts it again. Checked: a crash (exit 2) and an OOM kill (exit 137) come back with unless-stopped. No health check is needed for this.
  • The process is alive but doesn't answer, for example because all PHP threads are blocking. Only a health check can detect that, a regular self-test of the container, and it has to be one that really talks to PHP.

I'd advise you to really talk to PHP in the health check and not just to a static file. As checked, a static file and the HEALTHCHECK built into the image against /metrics on port 2019 stayed green while all PHP threads were blocked.

Docker: kill -QUIT 1 with your own counter

Signals are messages to a process: SIGTERM asks it to end in an orderly way, SIGKILL ends it immediately, SIGQUIT makes Caddy abort immediately with an error code. Under Docker, unhealthy alone doesn't trigger a restart, checked, and the docs on restart policies (opens in a new tab) don't even mention health checks. The obvious form curl … || kill 1 is wrong for four reasons. SIGTERM ends with exit 0, so on-failure doesn't apply. The process waits for exactly the threads that are hanging, also checked with grace_period 3s. The first failure triggers it, so retries has no effect. And because kill itself returns 0, the check reports success. kill -9 1 from inside stays ineffective, because PID 1, the main process in the container, gets no SIGKILL from inside its own namespace (opens in a new tab).

What works: kill -QUIT 1 after several consecutive failures. That ends Caddy immediately (opens in a new tab) with exit 2, and the restart policy takes over. Checked with Docker Compose. Save the following script as healthcheck.sh next to the compose.yaml and make it executable with chmod +x healthcheck.sh, otherwise the check fails with permission denied and nothing ever restarts:

Terminal
#!/bin/sh
# Probe a real PHP script. After three consecutive failures, quit PID 1 so that
# the restart policy takes over. SIGQUIT, because SIGTERM waits for busy PHP
# threads and exits with 0.
state=/tmp/healthcheck.failures

if curl -fsS --max-time 5 -o /dev/null http://127.0.0.1:8081/health.php; then
	rm -f "$state"
	exit 0
fi

n=$(( $(cat "$state" 2>/dev/null || echo 0) + 1 ))
echo "$n" > "$state"

if [ "$n" -ge 3 ]; then
	rm -f "$state"
	kill -QUIT 1
fi
exit 1

On top of that, an internal site block in the Caddyfile, in addition to your actual site, and a health.php that only prints ok:

http://127.0.0.1:8081 {
	bind 127.0.0.1
	root * /srv/health
	php_server
}
<?php
echo "ok\n";

And the compose.yaml:

yaml
services:
  app:
    image: dunglas/frankenphp:1.13.5
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./public:/app/public:ro
      - ./health:/srv/health:ro
      - ./Caddyfile:/etc/frankenphp/Caddyfile:ro
      - ./healthcheck.sh:/usr/local/bin/healthcheck.sh:ro
      - caddy_data:/data
      - caddy_config:/config
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "/usr/local/bin/healthcheck.sh"]
      interval: 10s
      timeout: 8s
      retries: 3

volumes:
  caddy_data:
  caddy_config:

In the test, port mapping, TLS and named volumes were replaced by a local port. The key points from the test runs:

  • start_period doesn't protect you. Docker doesn't count the failures during it, but the command still runs and sends the signal. The startup allowance comes from threshold times interval, so here 30 seconds. A worker with a 15-second boot time got through at an interval of 10 s. At an interval of 2 s it went into a restart loop, because the three failures are reached after only about 6 seconds: in the test, eight restarts in 70 seconds, never healthy.
  • Docker's timeout has to be greater than curl --max-time, otherwise Docker ends the check before the script can count.
  • Check against an unencrypted internal port. With the default Caddyfile, curl -fsS http://localhost/missing.php returns a redirect with exit 0, and PHP never sees the request.
  • In worker mode, check through the worker. A classic health.php returned 200 while the worker was hanging.
  • Keep the check dumb. Database and APIs don't belong in it, otherwise a database outage restarts your web server.
  • Plan for the price. SIGQUIT aborts all running requests. According to the test, a sleep resolves itself after max_execution_time anyway; whether that also applies to hangs in C code or during database queries isn't checked.

stop_grace_period is set to 30 seconds here because the default of 10 seconds cuts off planned stops. An autoheal sidecar, a helper container that restarts other containers, with the Docker socket mounted isn't recommended, because the socket practically means root privileges on the host. The Compose specification (opens in a new tab) itself has no action on failure. Swarm (opens in a new tab) and other orchestrators that control many containers across several servers replace a failed task themselves.

Podman: built in, according to the docs

According to the docs, Podman solves this directly: --health-on-failure, or in Quadlet HealthOnFailure=. Quadlet is Podman's way of describing containers as services of systemd, the service manager on Linux. This example hasn't been tested and only follows the docs (opens in a new tab):

ini
[Unit]
Description=FrankenPHP app

[Container]
Image=docker.io/dunglas/frankenphp:1.13.5
PublishPort=8080:8080
Volume=%h/app/public:/app/public:ro
Volume=%h/app/health:/srv/health:ro
Volume=%h/app/Caddyfile:/etc/frankenphp/Caddyfile:ro
Volume=%h/app/data:/data
Volume=%h/app/config:/config
HealthCmd=curl -fsS --max-time 5 -o /dev/null http://127.0.0.1:8081/health.php
HealthInterval=10s
HealthTimeout=8s
HealthRetries=3
HealthStartPeriod=30s
HealthOnFailure=kill

[Service]
Restart=always
RestartSec=3s

[Install]
WantedBy=default.target

For this, the site in the Caddyfile has to listen on :8080, in addition to the internal block on 8081. According to the docs (opens in a new tab), kill fits systemd, because systemd handles the restart. From that you can conclude that you need neither a script nor SIGQUIT here, since the action comes from outside, and retries and the startup allowance work as intended. The checks hang off systemd timers (opens in a new tab). The Compose specification has no key for an action on failure, so stick with Quadlet or podman run for this.

Bridging the restart

During a restart the service is briefly gone. A Caddy in front can bridge that for new requests:

caddyfile
example.com {
	reverse_proxy app:8080 {
		lb_try_duration 20s
		lb_try_interval 250ms
	}
}

Checked with an artificial startup delay: without retry, 24 of 30 requests got a 502, and with lb_try_duration all 30 got a 200. Running requests don't survive the restart, though. A running POST ended with a 502, and a running GET ran a second time after the restart. So a GET with side effects can run twice, and you can restrict that with lb_retry_match if needed.

Migration traps

If you move from Apache or nginx with PHP-FPM, you'll usually run into the same points. When moving from Apache, in my view you should check early what .htaccess has been blocking for you so far. None of that has any effect under Caddy, and the migration guide (opens in a new tab) puts it like this: "check any request filtering that was done by the web server before PHP-FPM received the request".

  • According to the PHP manual (opens in a new tab), max_execution_time counts wall-clock time on Linux with ZTS. Under FPM it counts CPU time. sleep and I/O use up the limit, so imports or slow API calls suddenly run into it.
  • .user.ini has no effect, which also affects security plugins using auto_prepend_file.
  • Per-pool values are gone. The guide maps php_admin_value to php_ini, but doesn't mention that it applies globally.
  • request_terminate_timeout, slowlog and FPM status: The guide names no counterpart for these.
  • Incompatible extensions: According to the Known Issues (opens in a new tab), imap, newrelic and pcov aren't supported, and datadog, blackfire and imagick count as problematic. For imagick, the docs name instability and crashes caused by ImageMagick's OpenMP threads. As a remedy, you limit ImageMagick to one thread or build it without OpenMP. According to the docs, only the Docker images and Homebrew installations are affected; OpenMP is already switched off in the static binaries and the official packages.

Who it suits and who it doesn't

FrankenPHP is a good fit if you already use Caddy or want to, if your framework officially supports worker mode, if projects run in their own containers and if someone really keeps an eye on updates. It can also suit internal apps, because tls internal simplifies HTTPS, as long as you plan for distributing the root CA.

For classic shared hosting, I think PHP-FPM with separate pools is usually the better choice for you. If your setup runs cleanly with nginx and PHP-FPM and your application can't do worker mode, I wouldn't move for more speed alone.

Conclusion

For me, FrankenPHP solves the problem this text began with: Caddy can now do PHP too, in one program that's easy to run. Speed comes mainly in worker mode, and there only with an application built for it. The security situation demands attention, because one process shares everything and the update cadence is high. If you plan for that, meaning one project per container, quick updates, health checks against real PHP and your own rules for the webroot, you can do well with it. For me it has become a secure, high-performance and easy-to-manage solution.

Further reading

The directives at a glance are in the cheat sheets for FrankenPHP, Caddy and Podman. What to do about PHP2Shell is explained in the article on it. Why texts like this one get checked separately from the writing is shown in Who Checks the Checker?.