Installation

Relay is free to use, closed source software. Enterprise customer may request code audits.

• Requirements
• macOS
• Docker
• Linux
• Using APT
• Using YUM
• Heroku
• GitHub Actions

Requirements

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

• PHP 7.4+
• Redis Server 6+
• 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.1
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.

Docker

We’ve included various Docker examples in Relay’s repository on GitHub.

Linux

Relay can be installed manually on most Linux systems. First, ensure that the system meets the requirements listed above.

Then, install the following dependencies if necessary:

• hiredis
• openssl
• lz4
• zstd

Next, grab the latest release from GitHub matching the system architecture.

Unpack the archive and copy the extension and configuration file:

tar -xvzf relay-....tar.gz
cd relay-...

# Copy the extension and config
cp relay-pkg.so $(php-config --extension-dir)/relay.so
cp relay.ini $(php-config --ini-dir)

# Inject a UUID into the binary
sed -i "s/BIN:31415926-5358-9793-2384-626433832795/BIN:$(cat /proc/sys/kernel/random/uuid)/" $(php-config --extension-dir)/relay.so

If the php-config command is not available, the extension and ini directory can be discovered this way:

php -i | grep grep '^extension_dir'
php -i | grep '^Scan this dir'

After copying both files, restart PHP-FPM and the web server.

Finally, ensure that Relay was installed by running:

php --ri relay

If necessary, adjust the configuration in $(php-config --ini-dir)/relay.ini.

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://cachewerk.s3.amazonaws.com/repos/key.gpg | sudo apt-key add -
sudo add-apt-repository "deb https://cachewerk.s3.amazonaws.com/repos/deb $(lsb_release -cs) main"
sudo apt 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

Next, ensure that Relay was installed by running:

php --ri relay

Finally, restart PHP-FPM and the web server.

Using YUM

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://cachewerk.s3.amazonaws.com/repos/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

Next, ensure that Relay was installed by running:

php --ri relay

Finally, restart PHP-FPM and the web server.

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 in combination with shivammathur/setup-php is seamless.

Be sure to install the msgpack and igbinary as well.

name: Test
jobs:
  test:
    runs-on: ubuntu-latest

    env:
      php: 8.1
      relay: v0.4.1

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

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ env.php }}
          extensions: msgpack, igbinary

      - name: Install Relay
        run: |
          curl -L "https://cachewerk.s3.amazonaws.com/relay/${{ env.relay }}/relay-${{ env.relay }}-php${{ env.php }}-debian-x86-64.tar.gz" | tar xz
          cd relay-${{ env.relay }}-php${{ env.php }}-debian-x86-64
          sudo cp relay.ini $(php-config --ini-dir)
          sudo cp relay-pkg.so $(php-config --extension-dir)/relay.so
          sudo sed -i "s/BIN:31415926-5358-9793-2384-626433832795/BIN:$(cat /proc/sys/kernel/random/uuid)/" $(php-config --extension-dir)/relay.so

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