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:

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 ZendHQ User Interface.

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

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, see ZendHQ User Interface Installation.