dotlinux blog

How to Install FrankenPHP App Server in Ubuntu 24.04

FrankenPHP is a modern, high-performance app server for PHP built on top of Caddy, a powerful web server with native HTTP/2, HTTP/3, and QUIC support. It combines the speed of Caddy with PHP-FPM-like process management, making it an excellent choice for hosting PHP applications with improved performance, security, and scalability.

Whether you’re running a small blog, a complex e-commerce platform, or a microservice, FrankenPHP simplifies deployment with features like automatic TLS (Let’s Encrypt), built-in caching, and seamless integration with PHP frameworks (e.g., Laravel, Symfony, WordPress).

In this guide, we’ll walk through two methods to install FrankenPHP on Ubuntu 24.04: via precompiled binaries (recommended for most users) and via Docker (for containerized environments). We’ll also cover verifying the installation, running a demo PHP app, and setting up a systemd service for auto-start.

2026-03

Table of Contents#

  1. Prerequisites
  2. Method 1: Install FrankenPHP via Precompiled Binary
  3. Method 2: Install FrankenPHP via Docker
  4. Running a Demo PHP Application
  5. Setting Up FrankenPHP as a Systemd Service (Binary Method)
  6. Troubleshooting Common Issues
  7. Conclusion
  8. References

Prerequisites#

Before starting, ensure your system meets the following requirements:

  • Ubuntu 24.04 LTS (verify with lsb_release -a).
  • A user account with sudo privileges.
  • Internet access to download packages and binaries.
  • For the binary method: Basic tools like curl, wget, and tar (usually preinstalled).
  • For the Docker method: Docker Engine (we’ll install this in Step 1 of Method 2).

Method 1: Install FrankenPHP via Precompiled Binary#

This method is recommended for most users, as it’s lightweight and avoids the overhead of containerization.

Step 1: Update System Packages#

First, update your system’s package index to ensure you have the latest versions of existing packages:

sudo apt update && sudo apt upgrade -y

Step 2: Install Dependencies#

FrankenPHP requires a few system libraries to run. Install them using apt:

sudo apt install -y libc6 libpcre2-8-0 zlib1g libssl3 ca-certificates
  • libc6: GNU C library (required for binary execution).
  • libpcre2-8-0: Perl Compatible Regular Expressions (used for routing).
  • zlib1g: Compression library (for gzip support).
  • libssl3: SSL/TLS support (for HTTPS).

Step 3: Download the FrankenPHP Binary#

FrankenPHP provides precompiled binaries for Linux (amd64 architecture) on its GitHub Releases page.

First, check the latest version (e.g., v1.0.0 at the time of writing). Use curl to download the binary:

# Replace "v1.0.0" with the latest version from GitHub Releases  
FRANKENPHP_VERSION="v1.0.0"  
curl -L "https://github.com/dunglas/frankenphp/releases/download/${FRANKENPHP_VERSION}/frankenphp-linux-amd64" -o frankenphp

Step 4: Make the Binary Executable and Move It to PATH#

Make the downloaded binary executable and move it to /usr/local/bin (a directory in the system PATH for easy access):

chmod +x frankenphp  
sudo mv frankenphp /usr/local/bin/

Step 5: Verify Installation#

To confirm FrankenPHP is installed correctly, run:

frankenphp --version

You should see output similar to:

frankenphp version v1.0.0 (caddy 2.7.6, php 8.3.6)

If you see this, the binary installation is successful!

Method 2: Install FrankenPHP via Docker#

If you prefer containerized deployments, use the official FrankenPHP Docker image.

Step 1: Install Docker on Ubuntu 24.04#

If Docker isn’t already installed, follow these steps:

# Add Docker GPG key  
sudo apt install -y ca-certificates curl gnupg  
sudo install -m 0755 -d /etc/apt/keyrings  
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg  
sudo chmod a+r /etc/apt/keyrings/docker.gpg  
 
# Add Docker repository  
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null  
 
# Install Docker  
sudo apt update  
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin  
 
# Verify Docker installation  
sudo docker --version

You should see output like Docker version 26.1.4, build 5650f9b.

Step 2: Pull the FrankenPHP Docker Image#

The official FrankenPHP image is hosted on Docker Hub. Pull the latest version:

sudo docker pull dunglas/frankenphp:latest

To check the image, run:

sudo docker images | grep frankenphp

Step 3: Run FrankenPHP in a Container#

Start a FrankenPHP container with PHP enabled. For example, to serve a PHP app from your local directory:

# Replace /path/to/your/php/app with the path to your PHP project  
sudo docker run -p 8080:8080 -v /path/to/your/php/app:/app dunglas/frankenphp:latest
  • -p 8080:8080: Maps port 8080 on your host to port 8080 in the container.
  • -v /path/to/your/php/app:/app: Mounts your local PHP app directory to /app in the container (FrankenPHP serves files from /app by default).

Running a Demo PHP Application#

Let’s test FrankenPHP with a simple "Hello World" PHP app.

Option 1: With the Binary Installation#

  1. Create a project directory and an index.php file:

    mkdir -p ~/frankenphp-demo  
cd ~/frankenphp-demo  
echo '<?php echo "Hello, FrankenPHP!"; ?>' > index.php

  2. Start FrankenPHP in development mode (serves files from the current directory):

    frankenphp php-server --dev

  3. Open a browser and navigate to http://localhost:8080. You should see:

    Hello, FrankenPHP!

Option 2: With the Docker Installation#

  1. Create a local directory for your app:

    mkdir -p ~/frankenphp-demo-docker  
cd ~/frankenphp-demo-docker  
echo '<?php echo "Hello, FrankenPHP (Docker)!"; ?>' > index.php

  2. Run the Docker container, mounting your local directory:

    sudo docker run -p 8080:8080 -v $(pwd):/app dunglas/frankenphp:latest

  3. Visit http://localhost:8080 in your browser. You’ll see:

    Hello, FrankenPHP (Docker)!

Setting Up FrankenPHP as a Systemd Service (Binary Method)#

To ensure FrankenPHP starts automatically on system boot (recommended for production), create a systemd service file.

Step 1: Create a Systemd Service File#

Create a new service file at /etc/systemd/system/frankenphp.service:

sudo nano /etc/systemd/system/frankenphp.service

Paste the following content (adjust paths and user as needed):

[Unit]  
Description=FrankenPHP App Server  
After=network.target  
 
[Service]  
User=www-data  # Use a non-root user for security  
Group=www-data  
WorkingDirectory=/path/to/your/php/app  # e.g., /var/www/your-app  
ExecStart=/usr/local/bin/frankenphp php-server --config /path/to/Caddyfile  # Optional: Use a Caddyfile for advanced config  
Restart=always  
RestartSec=3  
 
[Install]  
WantedBy=multi-user.target

Step 2: Reload Systemd and Start the Service#

sudo systemctl daemon-reload  
sudo systemctl enable frankenphp  # Auto-start on boot  
sudo systemctl start frankenphp

Check the service status:

sudo systemctl status frankenphp

You should see active (running) in the output.

Troubleshooting Common Issues#

  • Port 8080 is already in use: Stop the conflicting service or use a different port (e.g., frankenphp php-server --port 8081).
  • Missing dependencies: Reinstall dependencies with sudo apt install -y libc6 libpcre2-8-0 zlib1g libssl3.
  • Permission errors: Ensure the www-data user has read access to your PHP app directory: 
    sudo chown -R www-data:www-data /path/to/your/php/app  
sudo chmod -R 755 /path/to/your/php/app
  • Docker container not starting: Check logs with sudo docker logs <container-id>.

Conclusion#

FrankenPHP is a powerful, modern app server that simplifies PHP deployment with built-in features like HTTP/3, TLS, and process management. In this guide, we covered two installation methods (binary and Docker), verified the setup, ran a demo app, and configured auto-start with systemd.

Whether you’re building a small site or a large application, FrankenPHP’s performance and ease of use make it a compelling alternative to traditional PHP-FPM setups.

References#