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.

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.

1. 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.

2. 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

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

For changes to take effect, restart the zendhqd daemon by running the following command:

systemctl restart zendhqd

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

Changing the ZendHQ 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.

To change the token, follow these steps:

• Hash the new token; in the following command, replace {token value} with the new access token you wish to use, and run the command from a bash prompt:

  echo -n "{token value}" | sha256sum | awk '{ print $1 }'

• Use the generated hash as the zendhqd.session.auth_token_hash value.
• Restart the zendhqd daemon using the following command:

  systemctl restart zendhqd

You can also use the zendphpctl command to update he value.

zendphpctl zendhq-token {new token}

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.