FrankenPHP

The FrankenPHP variation is a modern application server built on top of the Caddy web server. It runs PHP and the web server in a single process, eliminating the complexity of managing PHP-FPM and a separate web server.

This is the cutting-edge variation that offers worker mode, automatic HTTPS, and modern protocols like HTTP/2 and HTTP/3. It's the recommended variation for new Laravel projects seeking maximum performance.

When to Use FrankenPHP

Use the FrankenPHP variation when you need to:

• Run Laravel Octane with maximum performance
• Use worker mode to keep your application in memory
• Get automatic HTTPS with zero configuration
• Support modern protocols like HTTP/2 and HTTP/3
• Simplify your container architecture (single process)
• Deploy Symfony applications with the Runtime component

Perfect for

• Laravel Octane applications
• Symfony applications using the Runtime component
• Modern PHP applications that can benefit from worker mode
• Projects requiring automatic HTTPS
• High-performance APIs that benefit from persistent connections
• Teams wanting the latest and greatest in PHP application servers
• Apps that need PHP 8.3 or newer

Comparing FrankenPHP to Other Variations

Octane replaces PHP-FPM, so it cannot run inside the FPM variations at all. The NGINX and Apache in those images are PHP-FPM front ends, not reverse proxies. If you want Octane without FrankenPHP, run Octane's Swoole or RoadRunner server from our CLI image instead. See Running Octane Without FrankenPHP.

Known Issues

FrankenPHP is cutting edge and is a very active project. Be sure to understand FrankenPHP's known issues before using it in production. If you're looking for better compatibility, consider using the FPM-NGINX image.

Differences from Official FrankenPHP Images

Our FrankenPHP images are built with production deployments and enterprise security in mind. While the official FrankenPHP images are great for getting started, we've made several enhancements that make these images more suitable for production environments, especially when deploying at scale with orchestrators like Kubernetes, Docker Swarm, or managed container platforms.

Security-First Design: Unprivileged by Default

Unlike the official FrankenPHP images that run as root, our images run as the unprivileged www-data user by default. This dramatically reduces your security footprint in production environments.

What this means for you:

• Containers run with minimal privileges, following security best practices
• HTTP listens on port 8080 (instead of 80)
• HTTPS listens on port 8443 (instead of 443)
• Consistent with our other image variations for a unified experience

Native Health Checks with Laravel Integration

Health checks are critical for zero-downtime deployments, but the official images don't include them. Our images come with intelligent health check endpoints that work out of the box.

Built-in features:

• Default /healthcheck endpoint configured in Caddy
• Configurable via HEALTHCHECK_PATH environment variable
• Works with Laravel's native /up health check endpoint
• Ensures your application is truly ready before accepting traffic

services:
  php:
    image: serversideup/php:8.5-frankenphp
    environment:
      # Use Laravel's built-in health check
      HEALTHCHECK_PATH: /up

Production-Grade Caddyfile Configuration

The official FrankenPHP Dockerfile provides a basic Caddyfile to get started. We've spent considerable time crafting a production-ready configuration that includes security hardening, performance optimizations, and enterprise features.

What's included:

• CloudFlare integration - Trusted IP addresses configured automatically
• Security headers - Best-practice headers included by default
• Performance rules - Smart caching and compression configured
• Flexible logging - Configurable output formats and levels
• Self-signed certificates - Automatic generation for development environments
• Let's Encrypt support - Easy configuration for automatic SSL certificates

Designed for Orchestrator Deployments

FrankenPHP's tight integration with Caddy enables amazing features like automatic Let's Encrypt SSL certificates. However, in most production deployments, you're likely using a load balancer or reverse proxy for SSL termination, making Caddy's automatic SSL less useful and potentially problematic at scale.

Our orchestrator-first approach:

• Assumes SSL/TLS termination happens at the load balancer level
• Optimized for zero-downtime rolling deployments
• Works seamlessly with Kubernetes, Docker Swarm, and managed platforms
• Simplifies scaling from one container to hundreds

Consistent Environment Variable Experience

Just like all our other PHP variations, the FrankenPHP images support the same environment variables and helper scripts you're already familiar with.

Unified configuration across all variations:

• SSL_MODE - Control SSL behavior (off, mixed, full)
• LOG_OUTPUT_LEVEL - Adjust logging verbosity
• PHP INI settings via environment variables
• Helper scripts for permissions management
• Consistent startup script behavior

This means you can switch between variations (FrankenPHP, FPM-NGINX, FPM-Apache) with minimal configuration changes.

More Operating System Variations

We compile FrankenPHP from source, which allows us to support multiple operating systems for maximum flexibility.

Available platforms:

• Debian Bookworm (12)
• Debian Trixie (13)
• Alpine 3.23
• Alpine 3.24

This gives you the freedom to choose the base OS that best fits your infrastructure and security requirements.

What's Inside

Classic Mode vs Worker Mode

Unlike traditional setups that require a separate web server and PHP-FPM, FrankenPHP runs everything in a single process. It also operates in two modes:

Classic Mode (Default)

• FrankenPHP functions like a traditional PHP server (similar to PHP-FPM)
• Each request bootstraps your application fresh
• No additional configuration needed
• Safe for any existing PHP applications

Worker Mode (Advanced)

Worker mode is FrankenPHP's killer feature. Instead of bootstrapping your application for every request, it stays loaded in memory:

• Traditional: Bootstrap app → Handle request → Teardown → Repeat
• Worker Mode: Bootstrap app once → Handle requests indefinitely

This can result in dramatic performance improvements for Laravel applications.

How FrankenPHP Works

Quick Start

Here are a few examples to help you get started with the FrankenPHP variation.

Docker CLI

docker run -p 80:8080 -v $(pwd):/var/www/html/public serversideup/php:8.5-frankenphp

Your application will be available at http://localhost. The default webroot is /var/www/html/public.

Docker Compose

Here's a basic example getting FrankenPHP up and running with Docker Compose.

services:
  php:
    # Choose our PHP version and variation
    image: serversideup/php:8.5-frankenphp
    # Expose and map HTTP and HTTPS ports
    ports:
      - 80:8080
      - 443:8443
    # Mount current directory to /var/www/html
    volumes:
      - ./:/var/www/html
    # Support both HTTP and HTTPS
    environment:
      SSL_MODE: mixed

Laravel Octane

Laravel Octane natively supports FrankenPHP. Pass --caddyfile=/etc/frankenphp/Caddyfile to octane:start and our Caddyfile switches into worker mode while keeping the same production configuration as classic mode. Use our guide below to learn more.

Health Check

The FrankenPHP variation includes a built-in health check that verifies the server is responding:

If you are using Laravel, you can use the /up route to validate that Laravel is running and healthy.

Automatic HTTPS

One of FrankenPHP's standout features is automatic HTTPS powered by Caddy. It can automatically obtain and renew SSL certificates from Let's Encrypt.

Enabling Automatic HTTPS

services:
  php:
    image: serversideup/php:8.5-frankenphp
    ports:
      - "80:8080"
      - "443:8443"
    volumes:
      - ./:/var/www/html
    environment:
      CADDY_AUTO_HTTPS: "on"
      # Your domain for automatic certificate
      SERVER_NAME: "example.com"
      SSL_MODE: "full"

Need Let's Encrypt short-lived certificates or IP-address certificates? Set CADDY_ACME_PROFILE: "shortlived". See Short-lived & IP-address certificates for the trade-offs and the default_sni setup for SNI-less access.

SSL Modes for Development

For local development, use the SSL_MODE environment variable:

services:
  php:
    image: serversideup/php:8.5-frankenphp
    ports:
      - "80:8080"
      - "443:8443"
    volumes:
      - ./:/var/www/html
    environment:
      SSL_MODE: "full"

Available SSL modes:

• off - SSL disabled (default)
• mixed - Both HTTP (8080) and HTTPS (8443) enabled
• full - HTTPS only on port 8443

Learn more about SSL modes in the Configuring SSL guide.

Logging

FrankenPHP is built on Caddy, and Caddy handles logs differently from NGINX and Apache. Caddy does have an access log, but it is a named logger that shares the same structured format and default output as Caddy's runtime log. Every entry carries its own level: requests are logged at INFO and problems at ERROR.

Because both logs share one format and one default output, the FrankenPHP variation sends everything to stderr. That is Caddy's default, it is what the official FrankenPHP image does, and it is what Laravel Octane expects. Our NGINX and Apache variations keep the traditional split of access logs on stdout and error logs on stderr, because that is what the official images for those servers do. Read how we approach logging across all variations →

docker logs, Docker Compose, and Kubernetes capture both streams, so nothing changes in day-to-day use.

The format follows Caddy's default as well. Caddy writes human-readable console lines when stderr is an interactive terminal and JSON otherwise. A container started by Docker Compose, Docker Swarm, or Kubernetes has no terminal, so it gets one JSON object per line. That is what log collectors expect, and every entry carries a level field your log pipeline can map to a severity instead of guessing from the stream (for example, GKE tags stderr as ERROR unless it can read a severity). docker run -it and tty: true give you the console lines instead. Set CADDY_LOG_FORMAT if you want the same format everywhere:

• CADDY_LOG_FORMAT=console if you read logs by eye with docker compose logs or docker service logs and want the colored, human-readable lines whether or not a terminal is attached.
• CADDY_LOG_FORMAT=json if a container runs with a terminal attached but you still want structured logs.

In both formats the request log redacts the authorization query parameter, so the JWT that Mercure 0.x subscribers pass in the URL never lands in your logs. This is the same filter that FrankenPHP's own Caddyfile recommends.

Control the verbosity with LOG_OUTPUT_LEVEL. It defaults to info for FrankenPHP so request logs are included. Set it to warn to log problems only.

Mercure

Mercure pushes real-time updates from your app to the browser. FrankenPHP has a Mercure hub built in, and you turn it on with environment variables instead of editing a Caddyfile. The hub answers at /.well-known/mercure on the same ports as your app, in classic mode and with Laravel Octane.

services:
  php:
    image: serversideup/php:8.5-frankenphp
    ports:
      - "80:8080"
    volumes:
      - ./:/var/www/html
    environment:
      MERCURE_ENABLED: "true"
      MERCURE_TRUSTED_ISSUERS: "https://example.com"
      MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_JWT_SECRET}"
      MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_JWT_SECRET}"

Docker Compose reads MERCURE_JWT_SECRET from your .env file. Generate a secret with openssl rand -base64 32.

The hub only accepts subscribers with a valid token. Use MERCURE_EXTRA_DIRECTIVES to allow anonymous subscribers to public updates or to set CORS origins:

    environment:
      MERCURE_EXTRA_DIRECTIVES: |
        anonymous
        cors_origins https://example.com

Environment Variables

The FrankenPHP variation supports extensive customization through environment variables.

FrankenPHP/Caddy Configuration

PHP Configuration

Caddy Configuration

FrankenPHP uses Caddy's configuration format (Caddyfile) instead of NGINX configuration.

Adding your own Caddyfile rules

Most changes only need one of the environment variables above, such as CADDY_SERVER_ROOT, SSL_MODE, or the port settings. When you need a rule the variables don't cover, add raw Caddyfile config at the level where it belongs:

Every .caddyfile file in a folder is imported at that level. Use the environment variables for a quick one-liner and the folders for anything longer. The folders also work with Laravel Octane, which replaces CADDY_GLOBAL_OPTIONS and CADDY_SERVER_EXTRA_DIRECTIVES with its own values.

Two more variables cover FrankenPHP itself:

This is where each one lands in /etc/frankenphp/Caddyfile:

{
    frankenphp {
        FRANKENPHP_CONFIG
    }
    CADDY_GLOBAL_OPTIONS
    caddyfile-global.d/*.caddyfile
}

your app's site (one per listener that SSL_MODE creates) {
    php_server {
        CADDY_PHP_SERVER_OPTIONS
    }
    CADDY_SERVER_EXTRA_DIRECTIVES
    caddyfile-server.d/*.caddyfile
}

caddyfile.d/*.caddyfile

Add rules to your app

Put directives for your app in caddyfile-server.d/. This example gives one JavaScript file a short cache, overriding the year-long cache the image sets for static assets:

@embed path /embed.js
header @embed >Cache-Control "public, max-age=3600"

Mount the file in development, or copy it into your image for production:

services:
  php:
    image: serversideup/php:8.5-frankenphp
    volumes:
      - ./embed-cache.caddyfile:/etc/frankenphp/caddyfile-server.d/embed-cache.caddyfile

FROM serversideup/php:8.5-frankenphp
COPY embed-cache.caddyfile /etc/frankenphp/caddyfile-server.d/

Rules in caddyfile-server.d/ apply on every listener SSL_MODE creates. With SSL_MODE=mixed, that includes plain HTTP, so match on protocol https for anything that only belongs on HTTPS.

@protected not path /healthcheck {$HEALTHCHECK_PATH:/healthcheck}
basic_auth @protected {
    admin $2a$14$KbVXTcgF3ZrK76FfvPLFj.kXOV/PH5pkAk.o53ct8bGdsl6yai9eC
}

Add another site

Files in caddyfile.d/ sit at the top level of the Caddyfile, outside your app's site. Use them for a whole new site block:

http://docs.example.com:{$CADDY_HTTP_PORT:8080} {
    reverse_proxy docs:3000
}

Rules for your app don't work here. The embed-cache.caddyfile example above fails in this folder with "request matchers may not be defined globally", so put rules like that in caddyfile-server.d/ instead.

Replace the whole Caddyfile

If you need a completely different setup, copy your own file over /etc/frankenphp/Caddyfile. You then own everything the image's Caddyfile does, including SSL modes, security headers, and the health check endpoint, so reach for the folders first.

Further Customization

If you need to customize the container further, reference the docs below:

• Environment Variable Specification - See which environment variables are available to customize PHP and Caddy settings.
• Command Reference - See which commands are available to run inside the container.
• FrankenPHP Documentation - Official FrankenPHP documentation for advanced features.
• Caddy Documentation - Official Caddy documentation for web server configuration.