Installation
Relay is free to use, closed source software. Enterprise customer may request code audits.
Requirements
Before installing Relay, make sure the system meets the requirements:
- PHP 7.4+
- Redis Server 6+
- The
json
,igbinary
andmsgpack
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:
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