How to Install and Configure FrankenPHP for Magento 2

Introduction

If you want a faster, more efficient PHP runtime, it’s time to install and configure FrankenPHP for Magento 2.

This modern PHP application server combines performance and simplicity in one package. Moreover, it handles concurrent requests with minimal configuration effort.

In this guide, we’ll explore every step — from installation to system-level configuration — to make FrankenPHP production-ready for your Magento 2 project.

What Is FrankenPHP?

FrankenPHP is a next-generation PHP server built on Caddy, offering speed, security, and simplicity.

Unlike PHP-FPM, FrankenPHP serves requests directly — skipping FastCGI overhead for better performance.

Additionally, it supports HTTP/3 support, automatic HTTPS, and modern worker-based architecture, making it ideal for high-performance Magento 2 environments.

Why Use FrankenPHP for Magento 2?

• Improved Performance: Handles requests faster than PHP-FPM.
• Simpler Setup: No dependency on Apache or Nginx.
• Built-in HTTPS: Comes with automatic TLS and HTTP/3.
• Better Resource Efficiency: Uses fewer processes to manage concurrent requests.

Moreover, it simplifies Magento hosting by combining the web server and PHP engine into a single binary.

Advantages of FrankenPHP over Apache and Nginx

FrankenPHP offers several advantages compared to Apache and Nginx:

• Better Performance: No FastCGI overhead; requests are processed natively.
• Simpler Configuration: A single binary handles all requests.
• Built-in HTTPS & HTTP/3: No external configuration needed.
• Lower Memory Usage: Efficient request handling for modern cloud environments.
• Quick Startup: Faster initialization compared to multi-service setups.

Consequently, FrankenPHP simplifies your Magento 2 hosting and improves speed significantly.

Disadvantages of FrankenPHP over Apache and Nginx

Despite its strengths, FrankenPHP still has some drawbacks:

• Limited Production Adoption: It’s still relatively new compared to Apache/Nginx.
• Smaller Community Support: Fewer guides and community fixes available.
• Feature Gaps: Some advanced rewrite rules or modules aren’t yet supported.
• Compatibility Issues: Not all hosting panels or tools support it natively.

However, FrankenPHP provides speed and simplicity, even though it still lacks Apache and Nginx’s maturity and ecosystem.

Step 1: Install FrankenPHP

Run the following commands to download and install FrankenPHP:

curl -fsSL https://github.com/dunglas/frankenphp/releases/latest/download/frankenphp-linux-x86_64 -o /usr/local/bin/frankenphp
chmod +x /usr/local/bin/frankenphp

Verify installation:

frankenphp --version

Step 2: Create Required Directories and Configuration Files

To make FrankenPHP run smoothly as a system service, create the following directories and files:

1️⃣ Create Directories

sudo mkdir -p /etc/frankenphp
sudo mkdir -p /var/log/frankenphp
sudo mkdir -p /var/lib/frankenphp

• /etc/frankenphp → Stores FrankenPHP configuration files.
• /var/log/frankenphp/ → Contains logs for monitoring and debugging.
• /var/lib/frankenphp → Used as a data directory for runtime files.

Additionally, these directories ensure proper separation of configuration, logs, and data.

2️⃣ Create and Configure /etc/frankenphp/Caddyfile

This is the main FrankenPHP configuration file.

File Path:
/etc/frankenphp/Caddyfile

Content:

{
    frankenphp {
        # Enable worker mode for better performance (optional)
        # worker
    }
    
    # Allow self-signed certificates but disable automatic HTTPS for domains without explicit TLS
    auto_https disable_redirects
}

:8080 {
    root * /var/www/html
    
    # Enable compression for better performance
    encode zstd br gzip
    
    # Default handling for non-Magento files
    php_server
    file_server browse
}

# HTTPS Virtual Host for Magento248 on port 8080
magento248.local:8080 {
    root * /var/www/html/userprojects/Magento248/pub
    
    # Use self-signed certificate for local development
    tls internal
    
    # Enable compression for better performance
    encode zstd br gzip
    
    # Handle static files first
    @static {
        path *.css *.js *.png *.jpg *.jpeg *.gif *.ico *.svg *.woff *.woff2 *.ttf *.eot *.otf *.pdf
        path /static/* /media/* /opt/*
    }
    handle @static {
        file_server
    }
    
    # For all other requests, try file then index.php
    try_files {path} {path}/ /index.php
    
    # Execute PHP
    php_server
}

✅ Explanation:

• The first block handles basic PHP requests and static file serving.
• The second block is a dedicated Magento 2 virtual host that runs on port 8080 with HTTPS enabled.
• Compression is added for better page load speed.

Moreover, this configuration ensures smooth Magento 2 performance.

3️⃣ Create the Systemd Service File

This allows FrankenPHP to start automatically on system boot.

File Path:
/etc/systemd/system/frankenphp.service

Content:

[Unit]
Description=FrankenPHP Application Server
Documentation=https://frankenphp.dev/
After=network.target network-online.target
Wants=network-online.target systemd-networkd-wait-online.service

[Service]
Type=notify
User=custom.user
Group=customgroup
ExecStart=/usr/local/bin/frankenphp run --config /etc/frankenphp/Caddyfile
ExecReload=/bin/kill -USR1 $MAINPID
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=1048576
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_BIND_SERVICE
Environment=XDG_DATA_HOME=/var/lib/frankenphp
Environment=XDG_CONFIG_HOME=/etc/frankenphp

# Restart policy
Restart=on-abnormal
RestartSec=5s
StartLimitBurst=5
StartLimitInterval=60s

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=frankenphp

# Security settings
NoNewPrivileges=true
ProtectControlGroups=true
ProtectKernelModules=true
ProtectKernelTunables=true
RestrictRealtime=true
RestrictSUIDSGID=true
RemoveIPC=true
RestrictNamespaces=true

[Install]
WantedBy=multi-user.target

Then run:

sudo systemctl daemon-reload
sudo systemctl enable frankenphp
sudo systemctl start frankenphp
sudo systemctl status frankenphp

Consequently, FrankenPHP starts at boot and logs errors properly.

✅ Explanation:

This service configuration ensures FrankenPHP starts at boot, runs securely, logs properly, and restarts automatically if it crashes.

Step 3: Configure Magento for FrankenPHP

1. First, Set Base URLs:

bin/magento setup:store-config:set --base-url="http://localhost/"
bin/magento setup:store-config:set --base-url-secure="https://magento248.local"

2. Next, Flush Cache:

bin/magento cache:flush

Finally, test the store at https://magento248.local:8080. It should load smoothly via FrankenPHP.

Note: In case if you are getting Database Connection Failure error
Then you may need to update the host of db connection :
env.php: ‘host’ => ‘localhost’ → ‘host’ => ‘127.0.0.1’

Conclusion

That’s it — you’ve now learned how to install and configure FrankenPHP for Magento 2, including systemd service setup, directory structure, and configuration details.

This approach improves performance, enhances manageability, and introduces modern PHP serving technology.

Moreover, while FrankenPHP is still new compared to Apache and Nginx, it’s rapidly evolving into a strong, efficient option for modern Magento deployments.

Ready to take your Magento 2 performance to the next level? Try FrankenPHP and experience a faster, cleaner hosting stack!