# Server

RoadRunner server plugin, is responsible for starting worker pools for plugins that use workers, such as `http`, `tcp`, `jobs`, `centrifuge`, `temporal`, and `grpc`. The worker pools inherit all of RoadRunner's features, such as supervising, state machine, and command handling.

## Configuration

The `server` section contains various options for configuring the plugin.

**Here is an example of a configuration:**

{% code title=".rr.yaml" %}

```yaml
server:
  on_init:
    # Command to execute before the main server's command
    #
    # This option is required if using on_init
    command: "any php or script here"

    # Username (not UID) of the user from whom the on_init command is executed. An empty value means to use the RR process user.
    #
    # Default: ""
    user: ""

    # Script execute timeout
    #
    # Default: 60s [60m, 60h], if used w/o units its means - NANOSECONDS.
    exec_timeout: 20s

    # Environment variables for the worker processes.
    #
    # Default: <empty map>
    env:
      - SOME_KEY: "SOME_VALUE"
      - SOME_KEY2: "SOME_VALUE2"

    # Exit RR if the `on_init` command fails or exceeds the `exec_timeout`.
    exit_on_error: false

  # Worker starting command, with any required arguments.
  #
  # This option is required.
  command: "php psr-worker.php"

  # Username (not UID) for the worker processes. An empty value means to use the RR process user.
  #
  # Default: ""
  user: ""

  # Group name (not GID) for the worker processes. An empty value means to use the RR process user.
  #
  # Default: ""
  group: ""

  # Environment variables for the worker processes.
  #
  # Default: <empty map>
  env:
    - SOME_KEY: "SOME_VALUE"
    - SOME_KEY2: "SOME_VALUE2"

  relay: pipes
```

{% endcode %}

{% hint style="info" %}
Worker relay can be: `pipes`, TCP (e.g.: `tcp://127.0.0.1:6002`), or socket (e.g.: `unix:///var/run/rr.sock`). But in most cases, you should use the default `pipes` relay, it is the fastest communication transport. It uses an inter-process communication mechanism that allows for fast and efficient communication between processes. It does not require any network connections or external libraries, making it a lightweight and fast option.
{% endhint %}

{% hint style="info" %}
Use `on_init.user` option to execute the on\_init command under a different user.
{% endhint %}

### Server initialization

The `on_init` section is used for application initialization or warming up before starting workers. It allows you to set a command script that will be executed before starting the workers. You can also set environment variables to pass to this script.

{% hint style="info" %}
If the `on_init` command fails (i.e., returns a non-zero exit code), RoadRunner will log the error but continue execution. This ensures that a failure during initialization does not interrupt the application's operation. Use `on_init.exit_on_error: true` to stop RoadRunner if `on_init` command fails or exceeds the `exec_timeout`.
{% endhint %}

### Worker starting command

The `server.command` option is required and is used to start the worker pool for each configured section in the config.

{% hint style="info" %}
This option can be overridden by plugins with a pool section, such as the `http.pool.command`, or in general `<plugin>.pool.command`.
{% endhint %}

The `user` and `group` options allow you to set the user and group that will start and own the worker process. This feature provides an additional layer of security and control over the application's execution environment.

{% hint style="info" %}
An empty value means to use the RoadRunner process user.
{% endhint %}

{% hint style="warning" %}
RoadRunner must be started from the root user. Root access is needed only to fork the process under a different user. Once the worker process is started, it will run with the specified user and group permissions, providing a secure and controlled execution environment for the application. All temporary files (`http` for example) would be created with the provided user/group
{% endhint %}

The `env` option allows you to set environment variables to pass to the worker script.

## PHP Client

There is a package that simplifies the process of integrating the RoadRunner worker pool with a PHP application. The package contains a common codebase for all RoadRunner workers, making it easy to integrate and communicate with workers created by RoadRunner.

When RoadRunner creates workers for any plugin that uses workers, it runs a PHP script and starts communicating with it using a relay. The relay can be `pipes`, `TCP`, or a `socket`. The PHP client simplifies this process by providing a convenient interface for sending and receiving payloads to and from the worker.

**Here is an example of simple PHP worker:**

{% code title="worker.php" %}

```php
<?php

require __DIR__ . '/vendor/autoload.php';

// Create a new Worker from global environment
$worker = \Spiral\RoadRunner\Worker::create();

while ($data = $worker->waitPayload()) {
    // Received Payload
    var_dump($data);

    // Respond Answer
    $worker->respond(new \Spiral\RoadRunner\Payload('DONE'));
}
```

{% endcode %}

The worker waits for incoming payloads, for example `HTTP request`, `TCP request`, `Queue task` or`Centrifuge message`, processes them, and sends a response back to the server. Once a payload is received, the worker processes it and sends a response using the `respond` method.

## What's Next?

1. [PHP Workers](https://docs.roadrunner.dev/docs/php-worker/worker) - Read more about PHP workers.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roadrunner.dev/docs/plugins/server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.