Are you looking to boost the performance of your PHP applications? Look no further than Relay, the next-generation caching layer for PHP.

Installing Relay on a RunCloud server is a straightforward process that can significantly enhance your application’s efficiency.

In this post, we’ll guide you through the steps needed to get Relay up and running on your RunCloud server. But first, let’s see why using Relay is a smart choice.

Why Use Relay?

Relay is a Redis client for PHP built for enhancing the speed and performance of your web applications. Whether you’re running a cutting-edge app or a legacy codebase, it’s designed to supercharge anything. It’s built to be a drop-in replacement for PHPRedis and Predis – with several notable advantages over it. For example:

  • Active Invalidation: Relay actively invalidates its in-memory cache, allowing your application to update its runtime cache mid-request, solving an especially challenging problem in computer science.
  • Resource Efficiency: With Relay, you maintain a partial replica of Redis’ data in memory, handling millions of requests per second while minimizing network communication.
  • Non-Blocking Calls: Relay’s asynchronous, multi-threaded, and lock-free nature removes the bottleneck of Redis’ single-threaded architecture.
  • Scalability: It is designed with shared environments in mind – Relay allows you to set memory limits and automatically evicts keys using LRU and LFU policies.

How to Install Relay on a RunCloud Server

At RunCloud, we use our own spin of Nginx and PHP, so the default installation steps will not work. In this section, we will walk you through the steps of installing Relay.

But before we start, make sure that you have configured SSH access for your server.

  1. Identify the PHP version: RunCloud supports multiple PHP versions and you will need to install Relay for each of them separately. But before you do that, you will need to find the path of the PHP version that you want to use.
    For PHP 8.1, the path of the installation would be /RunCloud/Packages/php81rc/ and the configuration location would be /etc/php81rc/php.ini. You can find the exact location of PHP binaries from the RunCloud documentation. 
  2. Connect to your server with root privileges: To install a PHP module on your server, you will need to log in via SSH with the necessary privileges.
  3. Check PHP Modules: The Relay module requires you to install json, igbinary, and msgpack extensions on your server. RunCloud automatically installs them by default, but you can check whether they are installed by executing the following command:
<path to PHP>/bin/php -m | grep -e json -e igbinary -e msgpack

Make sure to replace <path to PHP> with the value that we noted down in step 1. Once you execute the command, you should see a list of all three modules.

  1. Download Relay: Once you are sure that all necessary modules are installed, you can go to the releases page and copy the URL for the latest release for your PHP version. In the Operating System drop-down, select the Debian/Ubuntu and copy the URL of the binary for the x86 architecture by right-clicking on the name and selecting Copy Link Address.
    For example, in the following demonstration we selected the binary with the following name relay-v0.7.0-php8.1-debian-x86-64.tar.gz.
relay releases
  1. Next, go back to your SSH terminal and use the wget command to download Relay into an empty directory. For example, here is the command (below) for downloading Relay v0.7 for PHP 8.1. If you want to download a different file, you can replace the URL in the last step with the one that you copied earlier.
mkdir /tmp/relay
cd /tmp/relay
wget https://builds.r2.relay.so/v0.7.0/relay-v0.7.0-php8.1-debian-x86-64.tar.gz
  1. Extract the downloaded file: Next, you need to use the tar command to extract the downloaded file. For example:
tar -xvf ./relay-v0.7.0-php8.1-debian-x86-64.tar.gz

In the above command, replace relay-v0.7.0-php8.1-debian-x86-64.tar.gz with the name of your file. 

Hint: You can just type relay and press the Tab key on your keyboard to autocomplete the name.

  1. Check dependencies: After extracting the archive, change the current working directory with the cd command, and then use the ldd command to check if all the dependencies are met. For example:
cd relay-v0.7.0-php8.1-debian-x86-64
ldd ./relay-pkg.so
sed -i "s/00000000-0000-0000-0000-000000000000/$(cat /proc/sys/kernel/random/uuid)/" ./relay-pkg.so

Make sure to replace the relay-v0.7.0-php8.1-debian-x86-64 with the name of the folder on your server. After you execute the command, it should look something like the following screenshot:

If you see a “not a dynamic executable” error, then the downloaded build doesn’t match the OS/architecture, or your distro is blocking ldd calls in /tmp.

If any dependency says “not found”, the missing library needs to be installed.

  1. Locate the PHP extensions Directory: If you don’t see any missing dependencies in the previous step, you can proceed to installing the package. To do this, we simply need to copy the package file into a specific directory. Run the following command to get the path of the directory, making sure to replace the <path to PHP> with the value that we noted down earlier:
<path to PHP>/bin/php-config --extension-dir
  1. Copy the Relay package: The output of the previous command gave us the location of the extensions directory. Now we will use the cp command to copy the Relay package to the PHP extensions directory. 
sudo cp ./relay-pkg.so <path to folder>/relay.so

Make sure to replace the <path to folder> with the output of step 5. If you perform this step correctly, then you will not see any output.

  1. Configure Relay: After copying the package binary, we need to configure some basic settings for the Relay by editing the relay.ini file. Run the following command to append the recommended settings in the configuration file. Alternatively, you can refer to the official documentation and edit the file manually using a text editor such as nano.
echo "relay.maxmemory = 128M
relay.eviction_policy = noeviction
relay.environment = production
relay.key = 1L0O-KF0R-W4RDT0-Y0URR3P-0RTMRBR-OCC0L1" >> relay.ini
  1. Set the INI file: Next, we need to copy this file to the INI directory for your PHP version. To do this, we will use the php-config command to find the INI directory and copy the relay.ini file using the cp command. For example:
<path to PHP>/bin/php-config --ini-dir

In the above command, make sure to use the correct path for your PHP installation and note down the output – it should look similar to /etc/php81rc/conf.d.

Next, use the following command to copy the file to the correct location. Don’t forget to replace <path to INI directory> with the values that you noted down in the previous step.

cp ./relay.ini <path to INI directory>

If you perform this step correctly, then you will see no output.

  1. Test Relay: Finally, we can check whether it is installed correctly by using the –ri option in PHP command. For example:
<path to PHP>/bin/php --ri relay

The above command should give you a list of all the configuration settings that Relay is using. Your output should look similar to the following screenshot:

Alternatively, you can create an empty web app on your RunCloud server and use the file editor to create a PHP page with the following code to test Relay:

<?php
$relay = new \Relay\Relay(host: '127.0.0.1');
var_dump($relay->ping('Hello World!'));
?>

After adding the PHP code, save and close the editor. When you visit this page in a browser, you should see Hello World!.

That’s it! You have successfully installed Relay on your RunCloud Ubuntu server. If you encounter any issues, feel free to ask for help in the comments below. 

After Action Report

In this post we have guided you through the steps of installing Relay for PHP 8.1 on Ubuntu. After successfully installing Relay on your RunCloud server, you can start integrating it with a variety of existing technologies and popular platforms such as Laravel, Symfony, WordPress, Drupal, and Magento.

If you are looking for a better way to manage websites, then you should check out RunCloud.

RunCloud simplifies the complexities of server management, saving you time and automating routine tasks. With RunCloud, you can focus on what truly matters – growing your business and developing exceptional websites.

Don’t let server management hold you back – join RunCloud now and experience the ease of managing websites like never before!