ZendHQ Installation and Configuration
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.
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.