$docker.recipes

RoadRunner

intermediate

High-performance PHP application server and process manager.

[i]Overview

RoadRunner is a high-performance PHP application server written in Go that revolutionizes PHP application deployment by keeping PHP workers in memory between requests, eliminating the overhead of traditional PHP-FPM cold starts. Unlike conventional web servers that spawn new PHP processes for each request, RoadRunner maintains persistent worker pools that handle requests continuously, resulting in dramatically improved performance and reduced memory usage. RoadRunner's architecture combines Go's concurrency capabilities with PHP's flexibility, creating a modern application server that supports HTTP, gRPC, job queues, and TCP services through a plugin-based system. This stack provides a complete PHP application environment where RoadRunner manages worker processes, handles HTTP routing, and provides built-in monitoring and health checks without requiring separate web servers or process managers. The configuration uses a single .rr.yaml file to define worker pools, memory limits, debugging options, and plugin configurations, making it particularly suitable for high-traffic applications that need consistent performance. PHP developers seeking to modernize their deployment architecture will find RoadRunner especially valuable for applications requiring low latency, high throughput, or complex background job processing, as it bridges the gap between traditional PHP hosting and modern microservice architectures.

[*]Key Features

  • [+]Persistent PHP worker pools that eliminate cold start overhead and maintain application state between requests
  • [+]Built-in job queue system supporting async processing, delayed jobs, and priority queues without external dependencies
  • [+]Native gRPC server support enabling high-performance API communication and microservice integration
  • [+]Real-time metrics collection and Prometheus integration for comprehensive application monitoring
  • [+]Hot-reload capability allowing configuration changes and worker restarts without service interruption
  • [+]Memory leak protection with automatic worker recycling based on configurable memory and request limits
  • [+]Multi-protocol support handling HTTP/HTTPS, HTTP/2, WebSockets, and TCP connections simultaneously
  • [+]Framework-agnostic design with optimized integrations for Laravel, Symfony, Spiral, and custom PHP applications

[#]Common Use Cases

  • [1]High-traffic Laravel applications requiring sub-50ms response times with consistent performance under load
  • [2]API-first applications serving JSON responses where traditional PHP-FPM creates unnecessary overhead
  • [3]E-commerce platforms needing reliable background job processing for order fulfillment and inventory updates
  • [4]SaaS applications with real-time features requiring WebSocket connections and low-latency data processing
  • [5]Microservice architectures where PHP services need gRPC communication with other language components
  • [6]Content management systems handling media processing and thumbnail generation through job queues
  • [7]Financial applications requiring high-performance PHP processing with strict uptime requirements

[!]Prerequisites

  • [!]Docker and Docker Compose installed with at least 2GB RAM available for worker pools
  • [!]PHP application code structured for persistent execution without global state dependencies
  • [!]Port 8080 available on the host system for HTTP traffic routing
  • [!]Understanding of PHP worker lifecycle and memory management for optimal configuration
  • [!]Basic knowledge of YAML configuration for customizing RoadRunner settings and worker parameters
[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]
1services: 
2  roadrunner: 
3    image: ghcr.io/roadrunner-server/roadrunner:latest
4    container_name: roadrunner
5    restart: unless-stopped
6    volumes: 
7      - ./app:/var/www
8      - ./.rr.yaml:/etc/rr.yaml:ro
9    ports: 
10      - "8080:8080"
11    networks: 
12      - rr-network
13
14networks: 
15  rr-network: 
16    driver: bridge

[$].env Template

[.env]
1# RoadRunner configuration in .rr.yaml

[i]Usage Notes

  1. [1]Docs: https://roadrunner.dev/docs
  2. [2]Written in Go - PHP workers stay in memory (no cold starts)
  3. [3]No php-fpm needed - RoadRunner handles process management
  4. [4]Configure via .rr.yaml - workers, pools, plugins
  5. [5]Built-in job queues, gRPC, metrics, health checks
  6. [6]Integrates with Laravel, Symfony, Spiral frameworks

[>]Quick Start

[terminal]
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  roadrunner:
5    image: ghcr.io/roadrunner-server/roadrunner:latest
6    container_name: roadrunner
7    restart: unless-stopped
8    volumes:
9      - ./app:/var/www
10      - ./.rr.yaml:/etc/rr.yaml:ro
11    ports:
12      - "8080:8080"
13    networks:
14      - rr-network
15
16networks:
17  rr-network:
18    driver: bridge
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23# RoadRunner configuration in .rr.yaml
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]
1curl -fsSL https://docker.recipes/api/recipes/roadrunner/run | bash

[?]Troubleshooting

  • [!]Workers consuming excessive memory: Reduce worker count in .rr.yaml or lower max_memory limits to force recycling
  • [!]Application errors after worker restart: Check for global state dependencies and initialize required services in worker bootstrap
  • [!]RoadRunner fails to start with config error: Validate .rr.yaml syntax and ensure all referenced directories exist in mounted volumes
  • [!]Slow response times despite worker pools: Increase worker count or adjust max_jobs per worker to handle concurrent requests
  • [!]Job queue jobs not processing: Verify queue consumer configuration in .rr.yaml and check application job handler registration
  • [!]Container restart loops: Check application logs for fatal PHP errors and ensure proper error handling in worker code

Community Notes

Loading...
Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

roadrunner

## Tags

#roadrunner#php#golang#performance#grpc

## Category

Web Servers & Reverse Proxies

## Related