How to install and configure FrankenPHP for Magento 2

Introduction

If you want a faster and 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. Additionally, it handles concurrent requests with minimal configuration effort.

In this guide, we’ll explore each step – from installation to system-level configuration – to prepare FrankenPHP for production for your Magento 2 project.

What is FrankenPHP?

FrankenPHP is a next generation PHP server built on Caddyoffering speed, security and simplicity.

Unlike PHP-FPM, FrankenPHP responds to requests directly, avoiding the overhead of FastCGI for better performance.

In additionhe supports HTTP/3 support, Automatic HTTPSAnd modern worker-based architecturemaking it ideal for high-performance Magento 2 environments.

Why use FrankenPHP for Magento 2?

• Improved performance: Handles requests faster than PHP-FPM.
• Simpler configuration: No dependency on Apache or Nginx.
• Integrated HTTPS: Comes with automatic TLS and HTTP/3.
• Better resource efficiency: Uses fewer processes to handle concurrent requests.

Additionally, 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 over Apache and Nginx:

• Best performance: No FastCGI overhead; requests are processed natively.
• Simpler configuration: A single binary handles all requests.
• Integrated HTTPS and HTTP/3: No external configuration required.
• Reduced memory usage: Efficient request management for modern cloud environments.
• Quick start: Faster initialization compared to multiservice configurations.

ThereforeFrankenPHP simplifies your Magento 2 hosting and significantly improves speed.

Disadvantages of FrankenPHP compared to Apache and Nginx

Despite its advantages, FrankenPHP still has some disadvantages:

• Adoption of limited production: 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 are not yet supported.
• Compatibility issues: Not all hosting panels or tools support it natively.

HoweverFrankenPHP offers speed and simplicity, even if it still lacks the maturity and ecosystem of Apache and Nginx.

Step 1: Install FrankenPHP

Run the following commands to download and install FrankenPHP:

curl -fsSL  -o /usr/local/bin/frankenphp
chmod +x /usr/local/bin/frankenphp

Check the installation:

frankenphp --version

Step 2: Create required directories and configuration files

For FrankenPHP to function properly 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 data directory for runtime files.

In additionThese 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 which works on the port 8080 with HTTPS enabled.
• Compression is added for better page loading speed.

What’s moreThis configuration ensures smooth performance of Magento 2.

3️⃣ Create the Systemd service file

This allows FrankenPHP to start automatically at system startup.

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

Content:

[Unit]
Description=FrankenPHP Application Server
Documentation=
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 execute:

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

ThereforeFrankenPHP starts at startup and logs errors correctly.

✅ Explanation:

This service configuration ensures that FrankenPHP starts at startup, runs securely, connects correctly, and restarts automatically in the event of a failure.

Step 3: Configure Magento for FrankenPHP

1. First of all, Set base URLs:

bin/magento setup:store-config:set --base-url="
bin/magento setup:store-config:set --base-url-secure="

2. Following, Clear cache:

bin/magento cache:flush

Finallytest the store at https://magento248.local:8080. It should load without issue via FrankenPHP.

Note: In case you receive Database connection failed error
Next, you may need to update the database connection host:
env.php: ‘host’ => ‘localhost’ → ‘host’ => ‘127.0.0.1’

Conclusion

There you go, you have now learned how to install and configure FrankenPHP for Magento 2including systemd service configuration, directory structure and configuration details.

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

Additionally, although FrankenPHP is still new compared to Apache and Nginx, it is quickly evolving into a solid and 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!