Twitter Discord GitHub Discussions

Installation

Requirements

Before installing Relay, make sure the system meets the requirements:

  • PHP 7.4+
  • Redis Server 6.2.7+
  • The json, igbinary and msgpack PHP extensions

macOS

Relay can be installed on macOS using Homebrew.

brew tap cachewerk/tap

brew install relay      # PHP 8.4
brew install relay@7.4  # PHP 7.4

Afterwards, be sure to restart PHP-FPM and the web server:

sudo brew services restart php
sudo brew services restart nginx

Next, ensure that Relay was installed by running:

php --ri relay

If necessary, adjust the configuration in /opt/homebrew/etc/relay/relay.ini.

It is worth noting that macOS lacks a decent futex mechanism and Relay will be somewhat slower than running it on Linux.

Linux

Relay can be installed on any Linux system. We have packages for popular PHP repositories, and for other common systems we have various Docker examples, as well as manual installation instructions for highly customized system.

Using Docker

We have various Docker examples on GitHub. If you’re using the official PHP Docker images you can install Relay using the php-extension-installer:

FROM php:8.4-cli
COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/
RUN install-php-extensions relay

Using APT

If the setup is using Ondřej’s wonderful ppa:ondrej/php repository (deb.sury.org) to manage PHP and extensions, simply add our key and repository:

curl -s https://repos.r2.relay.so/key.gpg | sudo apt-key add -
sudo add-apt-repository "deb https://repos.r2.relay.so/deb $(lsb_release -cs) main"

If apt-key or add-apt-repository are deprecated or not available, use:

curl -fsSL "https://repos.r2.relay.so/key.gpg" | sudo gpg --dearmor -o "/usr/share/keyrings/cachewerk.gpg"
echo "deb [signed-by=/usr/share/keyrings/cachewerk.gpg] https://repos.r2.relay.so/deb $(lsb_release -sc) main" \
  | sudo tee /etc/apt/sources.list.d/cachewerk.list > /dev/null
sudo apt-get update

Then, depending on the setup, install either Relay for a specific PHP version, or for the default version.

sudo apt install php-relay     # default php version
sudo apt install php8.1-relay  # specific php version
sudo apt install lsphp81-relay # for litespeed setups

Next, ensure that Relay was installed by running:

php --ri relay

Finally, restart PHP-FPM and the web server.

Using YUM / DNF

If the setup is using Remi’s excellent repository (rpms.remirepo.net) to manage PHP and extensions, simply add our key and repository:

curl -s -o /etc/yum.repos.d/cachewerk.repo "https://repos.r2.relay.so/rpm/el.repo"

Then, depending on the setup, install either Relay for a specific PHP version, or for the default version.

yum install relay-php        # single php version
yum install php81-php-relay  # multiple php versions
yum install lsphp81-relay    # for litespeed setups

Next, ensure that Relay was installed by running:

php --ri relay

Finally, restart PHP-FPM and the web server.

Using PIE

Relay can be installed using PHP PIE:

pie install cachewerk/relay

# install for a specific PHP version:
pie install --with-php-config=/usr/bin/php-config7.4 cachewerk/relay

Heroku

To use Relay on Heroku, add the platform repository to the Heroku app:

heroku config:set HEROKU_PHP_PLATFORM_REPOSITORIES="https://relay.so/heroku/"

Then add the extensions to composer.json as usual:

composer require "ext-relay:*"

Deploy the app and ensure that Relay was installed by running:

heroku run "php --ri relay"

Learn more on GitHub.

Configuring Relay on Heroku

The Relay configuration can be changed by adding Heroku’s compile step to your composer.json file.

{
  "require": {
    "ext-relay": "*"
  },
  "scripts": {
    "compile": [
      "./bin/compile.sh"
    ]
  }
}

This is how your compile script could look:

#!/bin/bash
set -e

RELAY_INI=`find $(php-config --ini-dir) -name "*-relay.ini"`

sed -i "s/^;\? \?relay.key =.*/relay.key = $RELAY_KEY/" $RELAY_INI
sed -i 's/^;\? \?relay.maxmemory =.*/relay.maxmemory = 128M/' $RELAY_INI
sed -i 's/^;\? \?relay.eviction_policy =.*/relay.eviction_policy = lru/' $RELAY_INI

Be sure to set your RELAY_KEY config variable:

heroku config:set RELAY_KEY=...

GitHub Actions

Installing Relay on GitHub Actions using shivammathur/setup-php is seamless.

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.4
          extensions: relay # or `relay-v0.9.1`

      - name: Dump Relay configuration
        run: |
          php --ri relay

Manual installation

In some cases, Relay may need to be installed manually. Let’s go over it step by step, or skip to the TLDR.

1. Preparation

First, you’ll need to know the:

  • OS name (CentOS, Debian)
  • OS version
  • OS architecture (amd64, aarch64, etc.)
  • PHP version (7.4, 8.4, etc.)

If this is difficult or unclear, you may want to consider stopping and asking someone for help.

2. PHP installations

Second, identify the PHP binaries that should use Relay. Your system might be using separate PHP installations for CLI and FPM.

Let’s go with a single binary for this guide:

which php
# /usr/bin/php

3. PHP extensions

Next, make sure the PHP installation you picked in step 2 have the json, igbinary and msgpack extensions installed.

/usr/bin/php -m | grep -e json -e igbinary -e msgpack
# igbinary
# json
# msgpack

If any of the extensions are missing, be sure to install them via pecl or the system’s PHP package manager before continuing. Do this for all PHP installations of step 2.

4. Relay artifact

Next, grab the URL for the build matching the system. We’ll use Ubuntu 20.04 and PHP 8.1 as an example.

mkdir /tmp/relay
curl -sSL "https://builds.r2.relay.so/v0.9.1/relay-v0.9.1-php8.1-debian-x86-64.tar.gz" | tar -xz --strip-components=1 -C /tmp/relay

If we’re missing a build for your particular system or architecture, please open an issue.

5. System dependencies

Relay requires several system libraries (OpenSSL, hiredis, Concurrency Kit, Zstandard, LZ4). All Relay builds come with a relay.so and a relay-pkg.so, the latter comes with with hiredis and ck bundled in, because:

  1. Relay requires hiredis >=1.1.0
  2. Relay on Silicon requires ck >=0.7.1 (which also hasn’t been released)

The OpenSSL dependency can be ignored, because it’s typically installed along with PHP.

While you should use the relay.so today and have all libraries linked dynamically, you may use the relay-pkg.so for convenience.

Alright, now make sure the relay-pkg.so has all its dependencies using ldd (or otool on macOS):

ldd /tmp/relay/relay-pkg.so

# libpthread.so.0 => /lib/aarch64-linux-gnu/libpthread.so.0 (0x0000ffff9676d000)
# libssl.so.1.1 => /lib/aarch64-linux-gnu/libssl.so.1.1 (0x0000ffff966d3000)
# libcrypto.so.1.1 => /lib/aarch64-linux-gnu/libcrypto.so.1.1 (0x0000ffff96445000)
# libzstd.so.1 => not found
# liblz4.so.1 => /lib/aarch64-linux-gnu/liblz4.so.1 (0x0000ffff96203000)

If you’re seeing a not a dynamic executable error, then the downloaded build doesn’t match the os/arch, or you’re obscure distro is blocking ldd calls in /tmp.

If any dependency says not found the library missing needs to be installed:

apt-get install libzstd

6. Relay extension

Let’s move the Relay binary. First, we’ll inject the mandatory UUID into the binary:

sed -i "s/00000000-0000-0000-0000-000000000000/$(cat /proc/sys/kernel/random/uuid)/" /tmp/relay/relay-pkg.so

Second, identify PHP’s extension directory for all:

/usr/bin/php -i | grep '^extension_dir'
# extension_dir => /usr/lib/php/20210902 => /usr/lib/php/20210902

php-config --extension-dir
# /usr/lib/php/20210902

Then move and rename the relay-pkg.so to relay.so and move it to the extension directory:

cp /tmp/relay/relay-pkg.so /usr/lib/php/20210902/relay.so

Do this for all PHP installations of step 2.

7. Relay configuration

Almost! Let’s configure Relay. In testing environments you can skip this step, but for production setups we recommend setting at least:

relay.maxmemory = 128M
relay.eviction_policy = noeviction
relay.environment = production
relay.key = 1L0O-KF0R-W4RDT0-Y0URR3P-0RTMRBR-OCC0L1

You can automate this using sed, or simply vim it — if you know how to exit.

sed -i 's/^;\? \?relay.maxmemory =.*/relay.maxmemory = 128M/' /tmp/relay/relay.ini
sed -i 's/^;\? \?relay.eviction_policy =.*/relay.eviction_policy = lru/' /tmp/relay/relay.ini
sed -i 's/^;\? \?relay.environment =.*/relay.environment = production/' /tmp/relay/relay.ini
sed -i "s/^;\? \?relay.key =.*/relay.key = $RELAY_KEY/" /tmp/relay/relay.ini

Like the extension directory the ini-dir varies greatly from system to system:

/usr/bin/php --ini | grep "Scan for additional"
# Scan for additional .ini files in: /etc/php/8.1/cli/conf.d

php-config --ini-dir
# /etc/php/8.1/cli/conf.d

Then move the relay.ini:

cp /tmp/relay/relay.ini /etc/php/8.1/cli/conf.d

CLI test

Finally, let’s make sure Relay works in your CLI environment and your configuration takes effect.

php --ri relay

HTTP test

Now, let’s restart your PHP and Web Server processes, whether it’s Nginx, Apache, LiteSpeed, restart it all. Same goes for the PHP-FPM process.

Now either run our benchmarks, or simply try a little test script to make sure Relay can connect to Redis Server:

<?php

$relay = new \Relay\Relay(host: '127.0.0.1');

var_dump($relay->ping('hello'));

That’s it, enjoy!

TLDR

First, ensure that the json, igbinary and msgpack PHP extensions are installed for all PHP installations (CLI, FPM, etc). Then make sure zstd and lz4 are installed, as well as other required system libraries.

RELAY_VERSION="v0.9.1"                         # https://builds.r2.relay.so/meta/latest
RELAY_PHP=$(php-config --version | cut -c -3)  # 8.1
RELAY_INI_DIR=$(php-config --ini-dir)          # /etc/php/8.1/cli/conf.d/
RELAY_EXT_DIR=$(php-config --extension-dir)    # /usr/lib/php/20210902
RELAY_ARCH=$(arch | sed -e 's/arm64/aarch64/;s/amd64\|x86_64/x86-64/')

RELAY_ARTIFACT="https://builds.r2.relay.so/$RELAY_VERSION/relay-$RELAY_VERSION-php$RELAY_PHP-debian-$RELAY_ARCH.tar.gz"
RELAY_TMP_DIR=$(mktemp -dt relay)

## Download artifact
curl -sSL $RELAY_ARTIFACT | tar -xz --strip-components=1 -C $RELAY_TMP_DIR

## Inject UUID
sed -i "s/00000000-0000-0000-0000-000000000000/$(cat /proc/sys/kernel/random/uuid)/" $RELAY_TMP_DIR/relay-pkg.so

## Move + rename `relay-pkg.so`
cp $RELAY_TMP_DIR/relay-pkg.so $RELAY_EXT_DIR/relay.so

# Modify `relay.ini`
sed -i 's/^;\? \?relay.maxmemory =.*/relay.maxmemory = 128M/' $RELAY_TMP_DIR/relay.ini
sed -i 's/^;\? \?relay.eviction_policy =.*/relay.eviction_policy = lru/' $RELAY_TMP_DIR/relay.ini
sed -i 's/^;\? \?relay.environment =.*/relay.environment = production/' $RELAY_TMP_DIR/relay.ini
# sed -i "s/^;\? \?relay.key =.*/relay.key = 1L0O-KF0R-W4RDT0-Y0URR3P-0RTMRBR-OCC0L1/" $RELAY_TMP_DIR/relay.ini

## Move `relay.ini`
cp $RELAY_TMP_DIR/relay.ini $RELAY_INI_DIR

Finally, restart the web server and PHP-FPM process.