Integrating RabbitMQ in Enterprise Server 10

Integrating RabbitMQ in Enterprise Server makes it possible to instantly push message notifications — such as when a user updates the properties of a file — to client views of all users who are connected to Enterprise. This ensures that users immediately see the changes that other users make.

Because RabbitMQ can be used over LAN connections (local users) and WAN connections (remote users), it can be seen as an alternative to the n-cast feature of earlier versions of Enterprise Server, which only works via broadcasting or multi-casting over LAN connections.

The following overview shows how RabbitMQ and n-casting is supported by the various clients and how the use of RabbitMQ and n-casting differs between Enterprise Server 9 and 10:

Note: Rabbit MQ and n-casting can be used side-by-side to serve different client versions. When n-casting was previously implemented but is now no longer used (for example because applications that only support n-casting are no longer used), it is advised to disable n-casting.

The following table summarizes the capabilities of using n-casting and RabbitMQ:

How it works

During most workflow operations, Enterprise Server pushes messages to the RabbitMQ queues while the client applications such as Content Station and Smart Connection read the messages from these queues.

When both n-casting and RabbitMQ are enabled, Enterprise Server will send out the same message twice: one over n-casting and one over RabbitMQ. Smart Connection will only listen to one of the two; when it cannot connect to RabbitMQ it will fall back to n-casting.

There is no functional drawback in leaving n-casting on when RabbitMQ is enabled; it does however have some performance impact. When n-casting is not used by any of the clients, it is better to disable it.

Enterprise Server itself does not make use of the messaging feature of RabbitMQ, nor does it rely on it in any way.

Before you start

Please take note of the following:

• The RabbitMQ server requires a fast connection to the Internet, especially in combination with Enterprise Server.
• In production environments, consider installing RabbitMQ on a separate machine. This can be a VMWare installation, a cloud instance or a physical machine.
• To determine which operating system to use with RabbitMQ, see the RabbitMQ documentation: Supported Platforms.
• For information about the compatibility of RabbitMQ and Enterprise Server, see the Compatibility Matrix.
• When running RabbitMQ and Enterprise Server on the same machine, make sure that the operating system is compatible with both packages. For details about Enterprise Server compatibility, see the Compatibility Matrix.

Requirements

For information about which versions of RabbitMQ can be used with which versions of Enterprise Server, see the Compatibility Matrix.

Installing RabbitMQ to work over SSL requires OpenSSL 1.0.1 or higher . Older versions of OpenSSL are incompatible with RabbitMQ.

Installing the RabbitMQ plug-in in the PHP extension requires bcmath to be available in PHP. Instructions on how to check if it is already installed and how to install it when needed are provided in this article.

Steps to perform

To integrate RabbitMQ with Enterprise Server, follow these steps:

1. Installing and configuring RabbitMQ
2. Configuring Enterprise Server
3. (Optional) Setting up public and private connections
4. Setting up SSL
5. (Optional) Disabling n-casting

1. Installing and configuring RabbitMQ

Step 1. Download, install and run RabbitMQ by following these instructions: Downloading and Installing RabbitMQ.

Step 2. Enable pre-installed plug-ins:

Step 2a. From the command line, navigate to the <rabbitmq server>/sbin folder.

Step 2b. Run the following commands:

rabbitmq-plugins enable rabbitmq_management

rabbitmq-plugins enable rabbitmq_web_stomp

Step 3. Open the following ports in your firewall:

Step 4. (Optional, only when you want to use alternative ports) Open the following file in a plain-text editor (or create it if it does not exist) and define your own ports:

<location details>/rabbitmq.config

[
    {rabbit, [
        {tcp_listeners, [5672]}
    ]},
    {rabbitmq_management, [
        {listener, [
            {port, 15672}
        ]}
    ]},
    {rabbitmq_stomp, [
        {tcp_listeners, [61613]}
    ]},
    {rabbitmq_web_stomp, [
        {tcp_config, [
            {port, 15674}
        ]}
    ]}  
].

Step 5. Start (or restart) the RabbitMQ server.

Step 6. Grant access to the guest user by doing one of the following:

Step 9. Add a Virtual Host in RabbitMQ for Enterprise Server:

Step 9a. In Enterprise Server, access the Health Check page.

Step 9b. In the menu on the left, choose Config Overview.

Step 9c. Search for Enterprise System ID and copy it or take a note of it.

Step 9d. In RabbitMQ, access the Admin tab in the admin pages.

Step 9e. In the menu on the right, choose Virtual Hosts.

Step 9f. Expand the Add a new virtual host section and fill in the Enterprise System ID.

Step 9g. Click Add virtual host.

Step 10. Grant admin rights to the created virtual host:

Step 10a. In RabbitMQ, access the Admin tab in the admin pages.

Step 10b. In the menu on the right, choose Users.

Step 10c. Click the admin user, for example 'woodwing'.

Step 10d. Expand the Set permission section and fill in the fields:

• For Virtual Host, select the one you created earlier
• For all regexp fields, enter .*

Step 10e. Click Set permission.

The new admin user now has full access to the resources that will be created for the Enterprise installation.

2. Configuring Enterprise Server

Configuring Enterprise Server involves the following areas:

1. The connection to and with RabbitMQ
2. System cleanup tasks

1. Configuring the connection

This step can be broken down into:

1. Establishing the connection with RabbitMQ
2. (Optional) Improving performance by configuring connection timeouts
3. (Optional) Improving performance by excluding users from receiving notifications
4. (Optional) Setting up Enterprise Server jobs to clean up message queues

1. Establishing the connection

Step 1. Open the configserver.php file in a plain-text editor and locate the MESSAGE_QUEUE_CONNECTIONS option:

Tip: (For Enterprise Server 10.1 or higher only) Easily manage and configure settings of all configuration files by adding them to a single configuration file.

define( 'MESSAGE_QUEUE_CONNECTIONS', serialize(array(
// - - - - Unsecure connection over TCP: - - - -
//  new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqp://localhost:5672', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'REST', 'http://localhost:15672', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'ws://localhost:15674/ws', true, 'woodwing', 'ww' ),
// - - - - Secure connection over SSL: - - - -
//  new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqps://localhost:5671', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'REST', 'https://localhost:15671', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'wss://localhost:15673/ws', true, 'woodwing', 'ww' ),
)));

Note the following:

• Example connections are provided, commented-out by leading slashes (//).
• Enterprise talks to RabbitMQ over 3 different protocols; AMQP, REST and STOMPWS.
• For each protocol, an SSL example and a non-SSL example is given.
• To connect to RabbitMQ, exactly one entry should be listed for each protocol.

Step 2. Remove the leading slashes (//) for the entries you want to enable.

Note: For configuring SSL connections, see 4. Setting up SSL.

Step 3. (Optional) For non-SSL connections, configure as follows:

define( 'MESSAGE_QUEUE_CONNECTIONS', serialize(array(
// - - - - Insecure connection over TCP: - - - -
    new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqp://localhost:5672', true, 'woodwing', 'ww' ),
    new MessageQueueConnection( 'RabbitMQ', 'REST', 'http://localhost:15672', true, 'woodwing', 'ww' ),
    new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'ws://localhost:15674/ws', true, 'woodwing', 'ww' ),
// - - - - Secure connection over SSL: - - - -
//  new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqps://localhost:5671', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'REST', 'https://localhost:15671', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'wss://localhost:15673/ws', true, 'woodwing', 'ww' ),
)));

Step 4. (Optional, only when Enterprise Server connects through a proxy) Specify the proxy in the ENTERPRISE_PROXY option of the configserver.php file.

Step 5. Test the integration by running 'RabbitMQ' test on the Health Check page.

2. (Optional) Improving performance by configuring connection timeouts

Enterprise Server sends out various requests when connecting to RabbitMQ. The time period after which these requests should time out can be set through the following options in configserver.php:

Tip: Easily manage and configure settings of all configuration files by adding them to a single configuration file.

• RABBITMQ_CONNECTION_TIMEOUT. When Enterprise Server connects to RabbitMQ, it sends HTTP requests. The timeout period for these requests is set to 2 seconds and can be controlled through this option.

Note: The higher the number, the more the Enterprise workflow operations are delayed in case RabbitMQ is suddenly no longer accessible. The lower the number, the higher the risk of losing push message notifications.

if( !defined( 'RABBITMQ_CONNECTION_TIMEOUT' ) ) {
	define( 'RABBITMQ_CONNECTION_TIMEOUT', 2 );
}

• RABBITMQ_EXECUTION_TIMEOUT. During a workflow operation (such as file check-in, save version, and so on), Enterprise Server invokes RabbitMQ by sending HTTP requests. The timeout period for these requests is set to 2 seconds and can be controlled through this option.

Note: The higher the number, the more the Enterprise workflow operations are delayed in case RabbitMQ is suddenly operating very slow. The lower the number, the higher the risk of losing push message notifications.

if( !defined( 'RABBITMQ_EXECUTION_TIMEOUT' ) ) {
	define( 'RABBITMQ_EXECUTION_TIMEOUT', 2 );
}

3. (Optional) Improving performance by excluding users from receiving notifications

When Enterprise Server connects to RabbitMQ, it sends HTTP requests for each Brand that a user has access to. This includes Issues for which the Overrule Brand option is enabled.

Each request takes a few milliseconds to complete, so even when a user has access to a few dozen Brands the process does not take long. When a user has access to a significantly high number of Brands though, the log-on duration can be negatively impacted.

While it is common practice for Enterprise installations to limit the number of Brands that a user has access to, some users (such as Brand administrators or system administrators) will typically have access to a high number of Brands. However, for those users the push message notifications may be not important. These users can therefore be excluded from receiving notifications.

This is done by setting the RABBITMQ_MAX_PUBLICATIONS option in the configserver.php file. In it, the maximum number of Brands that a user can have access to in order to receive notifications through RabbitMQ is specified.

When the number of Brands that a user has access to is lower than or equal to the defined maximum, notifications are sent to that user by RabbitMQ.

When the number of Brands that a user has access to is higher than the defined maximum, notifications are not sent to that user by RabbitMQ.

Tip: Easily manage and configure settings of all configuration files by adding them to a single configuration file.

if( !defined('RABBITMQ_MAX_PUBLICATIONS') ) {
	define( 'RABBITMQ_MAX_PUBLICATIONS', 50 );
}

Note: To see which users are excluded from receiving notifications by RabbitMQ as a result of setting this option, run the RabbitMQ test on the Health Check page. It will also show the number of Brands and overruled Issues that each user has access to.

4. (Optional) Setting up an Enterprise Server job to clean up message queues

When RabbitMQ is temporarily down during production hours, Enterprise Server can no longer push message notifications.

Enterprise Server can also not remove message queues in RabbitMQ when tickets expire or when users log off.

The result of both scenarios is that the resource administration of RabbitMQ may get out-of-sync.

If RabbitMQ would remain down for many hours while many users are connected, many message queues could remain abandoned in RabbitMQ forever. If this problem repeats itself many times, there is a potential risk that RabbitMQ gets exhausted by using too many resources.

For this purpose, message queues in RabbitMQ can be periodically cleaned up by running the Enterprise Server Job named AutoCleanRabbitMQ.

For details about setting up Enterprise Server Jobs, see Working with Enterprise Server Jobs in Enterprise Server 10.

3. (Optional) Setting up public and private connections

In several cases it can be useful to configure both public and private connections for RabbitMQ.

REST

This protocol is used by Enterprise Server to communicates with RabbitMQ over REST (for resource management); it is not used by the client applications. Therefore, only a private connection is needed.

AMQP

Enterprise Server uses AMQP for publishing events, and the clients use AMQP to receive events. In this case, configure both a private and a public connection. The public connection will be communicated to the clients, while Enterprise Server uses the private connection.

STOMPWS

This protocol is only used by clients for receiving events, and therefore only requires a public connection.

The following is an example configuration (non-SSL) of the configserver.php file:

define( 'MESSAGE_QUEUE_CONNECTIONS', serialize(array(
// - - - - Insecure connection over TCP: - - - -
    new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqp://123.123.123.123:5672', true, 'woodwing', 'ww' ),
    new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqp://localhost:5672', false, 'woodwing', 'ww' ),
    new MessageQueueConnection( 'RabbitMQ', 'REST', 'http://localhost:15672', false, 'woodwing', 'ww' ),
    new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'ws://123.123.123.123:15674/ws', true, 'woodwing', 'ww' ),
// - - - - Secure connection over SSL: - - - -
//  new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqps://localhost:5671', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'REST', 'https://localhost:15671', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'wss://localhost:15673/ws', true, 'woodwing', 'ww' ),
)));

Note:The fourth parameter of each MessageQueueConnection entry indicates whether or not the connection is public. This parameter varies between the first and second connection: the first one is true (=public) and the second one is false (=private). When this parameter varies it is allowed to have two AMQP connections.

4. Setting up SSL

Setting up an SSL connection involves steps on RabbitMQ and on Enterprise Server.

Steps on RabbitMQ

Step 1. Follow the installation steps on RabbitMQ: TLS Support.

Step 2. Copy the generated testca/cacert.pem file to the following folder:

Enterprise/config/encryptkeys/rabbitmq

Step 3. Open the rabbitmq.config file in a plain-text editor and specify the protocols and ports as outlined below:

[
    {ssl, [
        {versions, ['tlsv1.2', 'tlsv1.1']}
    ]},
    {rabbit, [
        {ssl_listeners, [5671]},
        {ssl_options, [
            {cacertfile, "/usr/local/Cellar/rabbitmq/3.6.0/ssl/testca/cacert.pem"},
            {certfile,   "/usr/local/Cellar/rabbitmq/3.6.0/ssl/server/cert.pem"},
            {keyfile,    "/usr/local/Cellar/rabbitmq/3.6.0/ssl/server/key.pem"},
            {verify,     verify_peer},
            {fail_if_no_peer_cert,false},
            {versions,   ['tlsv1.2', 'tlsv1.1']}
        ]}
    ]},
    {rabbitmq_management, [
        {listener, [
            {port,     15671},
            {ssl,      true},
            {ssl_opts, [
                {cacertfile, "/usr/local/Cellar/rabbitmq/3.6.0/ssl/testca/cacert.pem"},
                {certfile,   "/usr/local/Cellar/rabbitmq/3.6.0/ssl/server/cert.pem"},
                {keyfile,    "/usr/local/Cellar/rabbitmq/3.6.0/ssl/server/key.pem"},
                {verify,     verify_peer},
                {fail_if_no_peer_cert,false},
                {versions,   ['tlsv1.2', 'tlsv1.1']}
            ]}
        ]}
    ]},
   {rabbitmq_stomp, [
      {ssl_listeners, [61614]}
   ]},
   {rabbitmq_web_stomp, [
      {ssl_config, [
         {port,       15673},
         {backlog,    1024},
         {cacertfile, "/usr/local/Cellar/rabbitmq/3.6.0/ssl/testca/cacert.pem"},
         {certfile,   "/usr/local/Cellar/rabbitmq/3.6.0/ssl/server/cert.pem"},
         {keyfile,    "/usr/local/Cellar/rabbitmq/3.6.0/ssl/server/key.pem"},
         {verify,     verify_peer},
         {fail_if_no_peer_cert,false},
         {versions,   ['tlsv1.2', 'tlsv1.1']},
         {password,   "MySecretPassword"}
      ]}
   ]}
]

Step 4. Open the following ports in your firewall:

Step 5. (Optional) Close the following (non-SSL) ports:

• 5672
• 15672
• 15674

Step 6. Start (or restart) the RabbitMQ server.

Step 7. Log in to on the admin pages using the woodwing/ww account and verify if RabbitMQ is running correctly:

https://localhost:15671/#/

Note: By default, the guest user is prohibited from connecting to RabbitMQ remotely; it can only connect over a loopback interface (localhost). Therefore use the woodwing/ww account instead.

See also Troubleshooting RabbitMQ in Enterprise Server 10.

Steps on Enterprise Server

Configuring Enterprise Server involves defining how it can connect to RabbitMQ.

Step 1. Open the configserver.php file in a plain-text editor and locate the MESSAGE_QUEUE_CONNECTIONS option:

define( 'MESSAGE_QUEUE_CONNECTIONS', serialize(array(
// - - - - Insecure connection over TCP: - - - -
//  new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqp://localhost:5672', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'REST', 'http://localhost:15672', true, 'woodwing', 'ww' ),
//  new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'ws://localhost:15674/ws', true, 'woodwing', 'ww' ),
// - - - - Secure connection over SSL: - - - -
    new MessageQueueConnection( 'RabbitMQ', 'AMQP', 'amqps://localhost:5671', true, 'woodwing', 'ww' ),
    new MessageQueueConnection( 'RabbitMQ', 'REST', 'https://localhost:15671', true, 'woodwing', 'ww' ),
    new MessageQueueConnection( 'RabbitMQ', 'STOMPWS', 'wss://localhost:15673/ws', true, 'woodwing', 'ww' ),
)));

Step 2. Comment the non-SSL connections (by pre-fixing them with //) and comment-out the SSL connections by removing the // prefixes.

Step 3. (Optional, only when Enterprise Server connects through a proxy) Specify the proxy in the ENTERPRISE_PROXY option of the configserver.php file.

Step 4. Test the integration by running the following tests tests on the Health Check page:

• php.ini
• RabbitMQ (This will check if bcmath is available. If this is not the case a link is provided with more information about how to install it.)

Step 5. Access the Integration page and verify that RabbitMQ is shown.

5. (Optional) Disabling n-casting

When n-casting was previously implemented but is now no longer used (for example because applications that only support n-casting are no longer used), it is advised to disable n-casting. Leaving it on will have some performance impact.

Do this by disabling the features that were enabled when setting up broadcasting or multi-casting.