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

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.4-frankenphp
    environment:
      # Use Laravel's built-in health check
      HEALTHCHECK_PATH: /up
    healthcheck:
      test: ["CMD", "healthcheck"]
      interval: 10s
      timeout: 5s
      retries: 3

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.21
• Alpine 3.22

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.4-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.4-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. 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.4-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"

SSL Modes for Development

For local development, use the SSL_MODE environment variable:

services:
  php:
    image: serversideup/php:8.4-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.

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 Custom Options

There are a few areas where you can use environment variables to customize your Caddy configuration:

services:
  php:
    image: serversideup/php:8.4-frankenphp
    environment:
      CADDY_SERVER_EXTRA_DIRECTIVES: |
        # Add custom headers
        header {
          X-Custom-Header "My Value"
          -Server
        }

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.