ZendHQ Installation and Configuration

Note This topic describes the procedures for installing ZendHQ. ZendHQ is only available for PHP versions 7.2 and forward on Linux.

Requirements

ZendHQ requires the following:

Only available on supported Linux platforms and only for PHP versions 7.2 and above.
For a list of supported platforms, see ZendHQ Supported Platforms.
Install the ZendPHP repository on your system before installing ZendHQ. You can use the zendphpctl repo-install script, or see the platform-specific installation documentation.

Install the ZendHQ PHP extension

ZendHQ requires that you install and enable the ZendHQ extension on servers running ZendPHP, and the ZendHQ daemon. The ZendHQ daemon can run on a ZendPHP server, or separately; If you are running ZendPHP on multiple servers, we recommend that you run the ZendHQ daemon on a separate server.

Note ZendHQ is not available on Ubuntu 16.04.

To install the ZendHQ extension on servers running ZendPHP:

For RPM-based servers, install the `php{VERSION}zend-php-zendhq` package, where `{VERSION}` is the PHP minor version minus the `.` separator (e.g., 72, 80, 81).
For DEB-based servers, install the `php{VERSION}-zend-zendhq` package, where `{VERSION}` is the PHP minor version (e.g., 7.2, 8.0, 8.1).

To install the ZendHQ daemon on either RPM or DEB servers, install the `zendhqd` package.

Licensing

You will also need to 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.

ZendHQ Node Configuration

You will need to configure the server running the zendhqd so that:

It can communicate with ZendPHP nodes.
It can communicate with the GUI.

These 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, specify the port only, prefixed by `:`; For example, `:10091`.

Restart the zendhqd daemon for changes to take effect:

systemctl restart zendhqd

Changing the token

ZendHQ uses an access token in order to authenticate users. By default, the token is "zendphp", and a sha256 hash of the value is stored as the zendhqd.session.auth_token_hash value in /opt/zend/zendphp/etc/zendhqd.ini. If you wish to change the token, you will need to follow these steps:

Hash the token; from a bash prompt, you can do this using: echo -n "{token value}" | sha256sum | awk '{ print $1 }'
- replace {token value} with the access token you wish to use.
Use the generated hash as the zendhqd.session.auth_token_hash value.
Restart the zendhqd daemon using systemctl restart zendhqd.

You can also use 'zendphpctl zendhq-token {new token}' to accomplish this.

ZendPHP Node Configuration

You need to configure your ZendPHP nodes to communicate with the ZendHQ node. This is done via a 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).

The setting you need to change is the zendhq.daemon_uri setting, and this should mirror the zendhqd.daemon_uri setting. As an 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, you need to restart your FPM process for the changes to take effect.
For example, systemctl restart php7.4-zend-fpm

Installing the ZendHQ interface

ZendHQ has a separate GUI for interacting with the daemon. The latest Linux version is included in the 'gui' subdirectory. You can download it from:

https://downloads.zend.com/zendphp/zendhq-ui/

Select the release appropriate for your platform, and extract its contents to a directory. It contains two files, an executable, and a resources.neu file; both MUST be present for the executable to run.

Auto-update: The GUI has an auto-update feature.

Assuming you have the ZendHQ daemon running somewhere, you can double-click the executable to start the GUI, and then provide it the IP address or DNS-resolvable name to connect to ZendHQ; if you are using one of the provided setups, use either 127.0.0.1 or localhost for the server. By default, the token is "zendphp".

Windows-specific installation notes

In some cases when running on Windows, you may need to grant privileges so that you can make HTTP and websocket requests to localhost. You can achieve this by running the following from a command prompt:

Copy

CheckNetIsolation.exe LoopbackExempt -a -n="Microsoft.Win32WebViewHost_cw5n1h2txyewy"

Some versions of Windows do not include the WebView component by default, which causes the ZendHQ GUI to display a blank screen. Known versions affected include Windows 10 Enterprise and Windows Server 2019 Datacenter. To fix this issue, you need to install the WebView2 component. You can download the component here.

After you have installed WebView2, relaunch the ZendHQ GUI to verify the fix.