roadrunner

README

RoadRunner is an open-source (MIT licensed) high-performance PHP application server, process manager written in Go and powered with plugins ❤️. It supports running as a service with the ability to extend its functionality on a per-project basis with plugins.

RoadRunner includes PSR-7/PSR-17 compatible HTTP and HTTP(S)/2/3 servers and can be used to replace classic Nginx+FPM setup with much greater performance and flexibility. HTTP(S)/2/3 servers as just one of its many available plugins, but its capabilities extend far beyond:

• Queue drivers: RabbitMQ, Kafka, SQS, Beanstalk, NATS, In-Memory.
• KV drivers: Redis, Memcached, BoltDB, In-Memory.
• OpenTelemetry protocol support (gRPC, http, jaeger).
• Workflows manager via Temporal
• gRPC server. For increased speed, the protobuf extension can be used.
• HTTP(S)/2/3 server features automatic TLS management and middleware like: Static, Headers, gzip, prometheus (metrics), send (x-sendfile), OTEL, proxy_ip_parser, etc.
• Embedded distribute lock plugin which manages access to shared resources.
• Metrics server (you might easily expose your own).
• WebSockets and Broadcast via Centrifugo server.
• Systemd-like services manager with auto-restarts, execution time limiter, etc.
• And more 😉

Join our discord server: Link

Official Website | Documentation | Forum | Release schedule

Features:

---

• Production-ready
• PCI DSS compliant (HTTP plugin)
• PSR-7 HTTP server (file uploads, error handling, static files, hot reload, middleware, event listeners)
• HTTPS, HTTP/2/3 support (including HTTP/2 Push, H2C)
• A Fully customizable http(s)/2 server
• FastCGI support (HTTP plugin)
• Flexible environment configuration
• No external PHP dependencies (64bit version required)
• Integrated metrics (Prometheus)
• Workflow engine by Temporal.io
• Works over TCP, UNIX sockets and process pipes
• Automatic worker replacement, graceful and safe PHP process destruction
• Worker create/allocate/destroy timeouts
• Max requests per worker limitation
• Worker lifecycle management (controller)
  • max_memory (graceful stop)
  • ttl (graceful stop)
  • idle_ttl (graceful stop)
  • exec_tll (brute, max_execution_time)
• Protocol, worker and job level error management (including PHP errors)
• Development Mode
• Integrations with Symfony, Laravel, Slim, CakePHP, Zend Expressive
• Application server for Spiral
• Works on Windows 10/11 and in WSL2

---

Installation

The easiest way to get the latest RoadRunner version is to use one of the pre-built release binaries, which are available for OSX, Linux, FreeBSD, and Windows. Instructions for using these binaries are on the GitHub releases page.

Docker:

To get the roadrunner binary file you can use our docker image: ghcr.io/roadrunner-server/roadrunner:2023.X.X (more information about image and tags can be found here).

FROM ghcr.io/roadrunner-server/roadrunner:2023.X.X AS roadrunner
FROM php:8.2-cli

COPY --from=roadrunner /usr/bin/rr /usr/local/bin/rr

# USE THE RR

Configuration located in the .rr.yaml file (full sample):

Installation via Composer

You can also install RoadRunner automatically using the command shipped with the composer package, run:

composer require spiral/roadrunner-http spiral/roadrunner-worker nyholm/psr7
./vendor/bin/rr get-binary

Server binary will be available at the root of your project.

Note

PHP's extensions php-curl and php-zip are required to download RoadRunner automatically. PHP's extensions php-sockets need to be installed to run roadrunner. Check with php --modules your installed extensions.

Installation option for the Debian-derivatives (Ubuntu, Mint, MX, etc)

wget https://github.com/roadrunner-server/roadrunner/releases/download/v2023.X.X/roadrunner-2023.X.X-linux-amd64.deb
sudo dpkg -i roadrunner-2023.X.X-linux-amd64.deb

Download the latest release via curl:

curl --proto '=https' --tlsv1.2 -sSf  https://raw.githubusercontent.com/roadrunner-server/roadrunner/master/download-latest.sh | sh

MacOS using Homebrew:

brew install roadrunner

---

Configuration can be located in .rr.yaml file (full sample):

version: '3'

rpc:
  listen: tcp://127.0.0.1:6001

server:
  command: "php worker.php"

http:
  address: "0.0.0.0:8080"

logs:
  level: error

Read more in Documentation.

Example Worker:

<?php

use Spiral\RoadRunner;
use Nyholm\Psr7;

include "vendor/autoload.php";

$worker = RoadRunner\Worker::create();
$psrFactory = new Psr7\Factory\Psr17Factory();

$worker = new RoadRunner\Http\PSR7Worker($worker, $psrFactory, $psrFactory, $psrFactory);

while ($req = $worker->waitRequest()) {
    try {
        $rsp = new Psr7\Response();
        $rsp->getBody()->write('Hello world!');

        $worker->respond($rsp);
    } catch (\Throwable $e) {
        $worker->getWorker()->error((string)$e);
    }
}

[!IMPORTANT]
If you see the EOF error, check that you have installed the PHP packages from this step. If this does not help, try to execute the command php worker.php directly and check the output.

---

Available Plugins: link

Run:

To run application server:

$ ./rr serve -c .rr.yaml

License:

The MIT License (MIT). Please see LICENSE for more information. Maintained by Spiral Scout.

Contributors

Thanks to all the people who already contributed!