Integrating RabbitMQ in Studio Server

Info: Performing the steps described in this article requires direct server access. Depending upon how your system is hosted and the level of access you have to that system, coordination may be required with your Partner or WoodWing Support team. For a full overview of the steps that need to be done by WoodWing and how to request them, see WoodWing Cloud - Change management.

Integrating RabbitMQ in Studio 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 Studio Server. This ensures that users immediately see the changes that other users make, such as via the Dynamic Updating feature of the Studio panel in Studio for InDesign and InCopy.

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, 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:

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, Studio Server pushes messages to the RabbitMQ queues while the client applications such as Studio and Studio for InDesign and InCopy read the messages from these queues.

When both n-casting and RabbitMQ are enabled, Studio Server will send out the same message twice: one over n-casting and one over RabbitMQ. Studio for InDesign and InCopy 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.

Studio 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 Studio 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 Studio Server, see the Compatibility Matrix.
• When running RabbitMQ and Studio Server on the same machine, make sure that the operating system is compatible with both packages. For details about Studio Server compatibility, see the Compatibility Matrix.

Requirements

For information about which versions of RabbitMQ can be used with which versions of Studio 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 Studio Server, follow these steps:

1. Installing and configuring RabbitMQ
2. Configuring Studio 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

The example below defines all default ports which gives you a starting point to adjust the ports the way you want. After doing so, also adjust your firewall settings.

[
    {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.

To stop RabbitMQ: 

rabbitmqctl stop

For more options, see the RabbitMQ documentation: rabbitmqctl(1) manual page.

To start RabbitMQ: 

rabbitmq-server

For more options, see the RabbitMQ documentation: rabbitmq-server(1) manual page.

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

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

Step 9a. In Studio Server, access the Health Check page. by clicking Advanced in the Maintenance menu or on the Home page. Then click Health Check.

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

Step 9c. Search for Studio Server 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 Studio Server 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 Studio Server installation.

2. Configuring Studio Server

Configuring Studio 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 Studio Server jobs to clean up message queues

1. Establishing the connection

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

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 (//).
• Studio Server 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 Studio 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

Studio 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 (recommended: config_overrule.php file):

• RABBITMQ_CONNECTION_TIMEOUT. When Studio 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 Studio Server 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.

Copy the code

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), Studio 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 Studio Server 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.

Copy the code

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

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

When Studio Server connects to RabbitMQ, it sends HTTP requests for each Brand that a user has access to.

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 Studio Server 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 (recommended: config_overrule.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.

Copy the code

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 that each user has access to.

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

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

Studio 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 Studio Server Job named AutoCleanRabbitMQ.

For details about setting up Studio 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 Studio 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

Studio 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 Studio 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 (recommended: config_overrule.php file):

Copy the code

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 Studio Server.

Steps on RabbitMQ

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

Step 2. Store the generated testca/cacert.pem file in one of the following locations:

• Recommended: the CA certificate store.
• The StudioServer/config/encryptkeys/rabbitmq folder.

Step 3. Configure Studio Server to find the generated certificate, depending on where the file is stored and the version of Studio Server used:

For Studio Server 10.30.0 or higher:

For Studio Server 10.29.0 or lower:

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

Copy the code

[
    {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 5. Open the following ports in your firewall:

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

• 5672
• 15672
• 15674

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

Step 8. 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 Studio Server

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

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

Copy the code

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