ZendHQ Installation and Configuration

This topic describes the procedures for installing ZendHQ. ZendHQ is made up of two pieces, a service daemon and a PHP extension.

Requirements

ZendHQ has the following requirements:

In all cases, the ZendPHP repository must be installed first.
For the service daemon:
- The service daemon is supported only on Linux and IBM i.
For the PHP extension:
- On Linux and IBM i, the ZendHQ extension is available for PHP versions 7.2 and later.
- On Windows, the ZendHQ extension is available for PHP 7.3 and later.

Do not load XDebug and ZendHQ extensions at the same time. This applies to all supported ZendHQ platforms and supported PHP versions. Both extensions interact closely with PHP internals. This can cause conflicts between the extensions resulting in errors or invalid results for ZendHQ. For this reason, running the ZendHQ extension in parallel with XDebug is not supported.

Install the ZendHQ Service

To install the ZendHQ daemon, install the `zendhqd` package for your platform. The ZendHQ daemon can run on a ZendPHP server, or separately. If you are running ZendPHP on multiple servers, run the ZendHQ daemon on a separate server.

Install the ZendPHP repository on your system before installing ZendHQ.
Use either the zendphpctl repo install script, or see the platform-specific ZendPHP installation documentation.
Install ZendHQ for your platform.
Choose one of the following options:
- DEB-based systems: apt install zendhqd
- RPM-based systems: yum install zendhqd and/or dnf install zendhqd
- Alpine systems: apk add zendhqd
- IBM i systems: Either use ACS or yum install zendhqd php83zend-php-zendhq
Before installing the service, consider whether you need to configure ZendHQ Role Management

Install the ZendHQ PHP Extension

To enable the ZendHQ extension on servers running ZendPHP, install one of the following packages:

For RPM-based servers, including IBM i, install the `php{VERSION}zend-php-zendhq` package, where `{VERSION}` is the PHP minor version minus the dot separator.
Example for PHP 8.3:
```
yum install php83zend-php-zendhq
```
and/or
```
dnf install php83zend-php-zendhq
```
For DEB-based servers, install the `php{VERSION}-zend-zendhq` package, where `{VERSION}` is the PHP minor version.

Example for PHP 8.3:
```
apt install php8.3-zend-zendhq
```
For Windows-based servers, there are three options; for more information, see Install the ZendHQ PHP Extension on Windows.
Example for installing PHP 8.3 using the ZendPHP installation script on a server with IP address 10.0.0.1:
```
zendphp-8.3-latest-nts-x64.msi
```

Licensing

Install the license file. After getting your license from Zend Support, copy it to the file /opt/zend/zendphp/etc/license on the server where you have installed the ZendHQ daemon. The ZendHQ daemon is the holder of the license.

ZendHQ extension on Windows does not need a separate local license on the Windows machine. If the ZendHQ daemon has a valid license, the ZendHQ extension will work normally.

ZendHQ Node Configuration

Configure the server running the zendhqd so that:

It can communicate with ZendPHP nodes.
It can communicate with the ZendHQ User Interface.

These URIs are configured in the file /opt/zend/zendphp/etc/zendhqd.ini. The relevant settings for these are, with their defaults, respectively:

zendhqd.daemon_uri = tcp://127.0.0.1:10090
zendhqd.websocket.interface = 127.0.0.1:10091

If you want the zendhqd.daemon_uri to listen to port 10090 on any IP address, use tcp://0.0.0.0:10090. To configure the zendhqd.websocket.interface setting to listen on any IP address behind your firewall, specify the port only, prefixed by `:`; For example, `:10091`.

Do not configure the zendhqd.websocket.interface setting to listen on all IP addresses unless the ZendHQ Daemon is behind a secure firewall. Not specifying an IP address poses a security risk.

For these changes to take effect, restart the zendhqd daemon. For more information, see ZendHQ Service Configuration.

ZendPHP Node Configuration

Configure your ZendPHP nodes to communicate with the ZendHQ node. Edit the configuration file for the extension, which is in one of the following locations:

RPM: /etc/opt/zend/php{VERSION}zend/php.d/90-zendhq.ini
where {VERSION} is the PHP minor version, minus the . separator (e.g., 72, 80, 81).
DEB: /etc/php/{VERSION}-zend/mods-available/zendhq.ini
where {VERSION} is the PHP minor version (e.g., 7.2, 8.0, 8.1).

Change the zendhq.daemon_uri setting so that it mirrors your zendhqd.daemon_uri setting. For example:

zendhq.daemon_uri = tcp://192.168.0.10:10090

You may specify the IP address OR a name that resolves to that IP address via DNS. (For example, with docker-compose or kubernetes, you might specify a service name for the ZendHQ node.)

If you are using PHP-FPM, restart your FPM process for the changes to take effect.
For example:

systemctl restart php7.4-zend-fpm

Customizing the UID/GID for the ZendHQ service

There's a user and group to set permissions of directories and files mounted through volumes, for example, the database directory or the cache directory in the application.

To customize the UID for this user, or the GID for this group, respectively, in your own installations, follow these steps.

Before installing the zendhqd package, create either the user or group, or both.

Examples:

On any platform:

addgroup --system --gid 999 zendphp

For deb- and rpm-based Linux:

adduser --system --home /var/zendphp --shell /usr/sbin/nologin --uid 999 --ingroup zendphp zendphp

For Alpine Linux:

adduser --system --home /var/zendphp --shell /sbin/nologin --uid 999 --gid zendphp zendphp

Installing the ZendHQ User Interface

ZendHQ has a separate GUI for interacting with the daemon. For more information about how to install it on Windows, macOS, or Linux, see ZendHQ User Interface Installation.