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.

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.