RoadRunner
  • 🟠General
    • What is RoadRunner?
    • Features
    • Quick Start
    • Installation
    • Configuration
    • Contributing
    • Upgrade and Compatibility
  • 👷PHP Worker
    • Worker
    • Workers pool
    • Developer mode
    • Code Coverage
    • Debugging
    • Environment
    • Manual workers scaling
    • Auto workers scaling
    • RPC
  • 🟢Customization
    • Building RR with a custom plugin
    • Integrating with Golang Apps
    • Writing a Middleware
    • Writing a Jobs Driver
    • Writing a Plugin
    • Events Bus
  • 🔌Plugins
    • Intro into Plugins
    • Centrifuge (WebSockets)
    • Service (Systemd)
    • Configuration
    • Server
    • Locks
    • gRPC
    • TCP
  • 🌐Community Plugins
    • Intro into Community Plugins
    • Circuit Breaker
    • SendRemoteFile
    • RFC 7234 Cache
  • 🔵App Server
    • Production Usage
    • RoadRunner with NGINX
    • RR as AWS Lambda
    • Docker Images
    • CLI Commands
    • Systemd
  • 🔐Key-Value
    • Intro into KV
    • Memcached
    • In-Memory
    • BoltDB
    • Redis
  • 📦Queues and Jobs
    • Intro into Jobs
    • Google Pub/Sub
    • Beanstalk
    • In-Memory
    • RabbitMQ
    • BoltDB
    • Kafka
    • NATS
    • SQS
  • 🕸️HTTP
    • Intro into HTTP
    • Headers and CORS
    • Proxy IP parser
    • Static files
    • X-Sendfile
    • Streaming
    • gzip
  • 📈Logging and Observability
    • OpenTelemetry
    • HealthChecks
    • Access Logs
    • AppLogger
    • Metrics
    • Grafana
    • Logger
  • 🔀Workflow Engine
    • Temporal.io
    • Worker
  • 🧩Integrations
    • Migration from RRv1 to RRv2
    • Spiral Framework
    • Yii
    • Symfony
    • Laravel
    • ChubbyPHP
  • 🧪Experimental Features
    • List of the Experimental Features
  • 🚨Error codes
    • CRC validation failed
    • Allocate Timeout
  • 📚Releases
    • v2025.1.2
    • v2025.1.1
    • v2025.1.0
    • v2024.3.5
    • v2024.3.4
    • v2024.3.3
    • v2024.3.2
    • v2024.3.1
    • v2024.3.0
Powered by GitBook
On this page
  • Configuration reference
  • Configuration file
  • CLI command and arguments
  • Support for the nested configurations: [>=2024.2.0], issue
  • What's Next?

Was this helpful?

Edit on GitHub
  1. General

Configuration

PreviousInstallationNextContributing

Last updated 10 months ago

Was this helpful?

RoadRunner supports both YAML and JSON configuration formats. The examples in our documentation use YAML, but you can use JSON as well.

To convert a YAML configuration file to JSON, you can use an online tool such as .

Configuration reference

The most recent configuration reference with all available options can be found in the .rr.yaml file in the RoadRunner GitHub repository:

We use dots as level separators, e.g.: http.pool, you can't use dots in section names, queue names, etc. You can find out more about it .

Configuration file

The RoadRunner looks for a configuration file named .rr.yaml in the same directory as the server binary.

If your configuration file and other application files are located in a different directory than the binary, you can use the -w option to specify the working directory.

./rr serve -w /path/to/project

You can also use the -c option to specify the path to the configuration file if you don't want to specify the working directory.

./rr serve -c /path/to/project/.rr-dev.yaml

Or you can combine the -c and -w options to specify both the configuration file and the working directory:

./rr serve -c .rr-dev.yaml -w /path/to/project

Read more about starting the server in the section.

CLI command and arguments

You can also use environment variables in CLI commands to customize the behavior of your RR server. This is especially useful when you need to pass configuration values that are environment-specific or sensitive, such as secrets or API keys.

set -a
source /var/www/config/.env
set +a

exec /var/www/rr \
  -c /var/www/.rr.yaml \
  -w /var/www \
  -o http.pool.num_workers=${RR_NUM_WORKERS:-8} \
  -o http.pool.max_jobs=${RR_MAX_JOBS:-16} \
  -o http.pool.supervisor.max_worker_memory=${RR_MAX_WORKER_MEMORY:-512}
  serve

The set -a enables automatic exporting of variables. Any variables that are defined in /var/www/config/.env will be automatically exported to the environment, making them available to any child processes that are executed from the current shell. The final set +a command disables automatic exporting of variables, ensuring that only the variables that were defined in /var/www/config/.env are exported, and preventing any unintended variables from leaking into the environment.

In this example, the following options are used:

Option
Description

-c

Specifies the configuration file.

-w

Specifies the working directory.

-o

Overwrites specific configuration options.

/var/www/config/.env

File that contains the required environment variables.

${RR_NUM_WORKERS:-8}

Sets the number of workers to RR_NUM_WORKERS from the .env file or uses the default value of 8 if the variable is not present.

Using the following syntax, you may include other configuration files into the main one:

.rr.yaml
version: "3"

include:
  - .rr.include1-sub1.yaml
  - ../foo/bar/rr.include1-sub2.yaml

reload:
  interval: 1s
  patterns: [".php"]

Starting from version v2024.2.0, the includes configuration option no longer has restrictions on where the included config can be placed. However, please note that the path for the included configurations is calculated based on the working directory of the RoadRunner process.

Includes override the main configuration file. For example, if you have the following nested configuration:

.rr.include1-sub1.yaml
version: "3"

server:
  command: "php php_test_files/psr-worker-bench.php"
  relay: pipes

http:
  address: 127.0.0.1:15389
  middleware:
    - "sendfile"
  pool:
    allocate_timeout: 10s
    num_workers: 2

It will override the server and http sections of the main configuration file. You may use env variables in the included configuration files, but you can't use overrides for the nested configuration. For example:

The next 'include' will override values set by the previous 'include'. Values in the root .rr.yaml will also be overwritten by the includes. Feel free to send us feedback on this feature.

.rr.include1-sub1.yaml
version: "3"

server:
  command: "${PHP_COMMAND:-php_test_files/psr-worker-bench.php}"
  relay: pipes

You may use any number of the included configuration files via CLI command, in quotas and separated by whitespace. For example:

./rr serve -e -c .rr.yaml -o include=".rr.yaml .rr2.yaml"

What's Next?

Support for the nested configurations: [>=2024.2.0],

- learn how to start the server.

- learn how to configure PHP workers environment.

- learn more about the Config plugin.

🟠
https://onlineyamltools.com/convert-yaml-to-json
.rr.yaml
here
Server Commands
issue
Server Commands
PHP Workers — Environment variables
Config plugin