Table of Contents

1. Document Revision History

For information about all the latest releases and updates on interworks.cloud platform, please visit http://kb.interworkscloud.net/display/ICPD/Release+Notes

2. About this Guide

2.1. Document Conventions

Throughout this guide, specific fonts and styles are used to identify user input, computer code, and user interface elements. The following table lists conventions used in this guide.

Table 1. Document conventions

3. Overview of RabbitMQ server within an interworks.cloud platform deployment

RabbitMQ is one of the most popular and widely used open source message brokers. When properly configured and in conjunction with interworks.cloud platform it allows for significant workload to be lifted away from interworks.cloud platform application components and provides a robust queueing mechanism that can handle asynchronously a vast amount of messages/application requests without compromising performance or platform operations efficiency.

4. Preparing for the Installation

This chapter explains how to prepare a hosting environment for the RabbitMQ server installation.

4.1. General Server Requirements

Although there are several ways to deploy and configure RabbitMQ in a variety of platforms, this guide will focus on deploying the solution for production use using 3 servers (VMs) to achieve high availability.

To install a RabbitMQ cluster you need to obtain the following servers:

• Three (3) servers

Each of these servers must meet the general minimum requirements shown in the following table:

Table 2. General server requirements

5. Installing RabbitMQ

This chapter explains how to install RabbitMQ in a high available configuration (3-node cluster) using an RPM-based installation on CentOS 8.x. as well as a windows-based installation.

5.1. RabbitMQ installation (linux-based)

The following steps show how to perform a typical installation of RabbitMQ on three CentOS 8.x nodes. The presented commands assume that the three (3) servers are named: node01, node02 and node03.

1. Connect to an available node (node01) with administrator (root) credentials
   
   

2. Import RabbitMQ signing key
   rpm --import https://github.com/rabbitmq/signing-keys/releases/download/2.0/rabbitmq-release-signing-key.asc
   
   

3. Setup RabbitMQ repository that will install RabbitMQ 3.8 and targets CentOS 8
   Edit/create the file /etc/yum.repos.d/rabbitmq-bintray.repo and set the following content:
   
   [bintray-rabbitmq-server]
   name=bintray-rabbitmq-rpm
   baseurl=https://dl.bintray.com/rabbitmq/rpm/rabbitmq-server/v3.8.x/el/8/
   gpgcheck=0
   repo_gpgcheck=0
   enabled=1
   
   

4. Install RabbitMQ
   dnf -y update
   dnf -y install epel-release telnet
   dnf -y install rabbitmq-server.noarch
   
   

5. Connect to servers node02 and node03 and repeat steps 2, 3 and 4
   
   

6. Start and Stop RabbitMQ server on node01
   systemctl start rabbitmq-server
   systemctl stop rabbitmq-server
   
   

7. Copy the Erlang cookie from node 1 to nodes 2 and 3
   scp /var/lib/rabbitmq/.erlang.cookie root@<node02>:/var/lib/rabbitmq/
   scp /var/lib/rabbitmq/.erlang.cookie root@<node03>:/var/lib/rabbitmq/
   
   

8. Assign appropriate permissions to .erlang.cookie on all servers (node01, node02 and node03)
   chown rabbitmq:rabbitmq /var/lib/rabbitmq/.erlang.cookie
   chmod 400 /var/lib/rabbitmq/.erlang.cookie
   
   

9. Enable the RabbitMQ server service on all servers (node01, node02 and node03)
   systemctl enable rabbitmq-server
   rabbitmq-plugins enable rabbitmq_management
   
   

10. Create the cluster (Start the RabbitMQ server on node01)
    systemctl start rabbitmq-server
    
    

11. Start the RabbitMQ server on servers node02 and node02
    systemctl start rabbitmq-server -detached
    
    

12. Initial cluster configuration (Add administrator user and create basic policies on node01)
    rabbitmqctl add_user <rabbitadmin> <rabbitadminpassword>
    rabbitmqctl set_user_tags <rabbitadmin> administrator
    rabbitmqctl set_permissions -p / <rabbitadmin> “.*” “.*” “.*”
    rabbitmqctl delete_user guest
    rabbitmqctl list_users
    rabbitmqctl set_policy ha-all “.*” ‘{“ha-mode”:”all”}'
    
    

13. Check the cluster status (node01)
    rabbitmqctl cluster_status
    
    

14. Add the rest of the nodes to the cluster. On each node (node02 and node03) execute the following commands:
    rabbitmqctl stop_app
    rabbitmqctl reset
    rabbitmqctl join_cluster rabbit@<node01>
    rabbimqctl start_app
    
    

15. Check the cluster status again and verify all three (3) nodes have joined the cluster.
    rabbitmqctl cluster_status
    
    
    
    

5.2. RabbitMQ configuration (linux-based)

Initial configuration of the newly formed RabbitMQ cluster is required on the following items:

1. System limits
   RabbitMQ installations running production workloads may need system limits and kernel parameters tuning in order to handle a decent number of concurrent connections and queues. The main setting that needs adjustment is the max number of open files. This setting can be set in /etc/systemd/system/rabbitmq-server.service.d/limits.conf. The configuration file should look like this:
   
   [Service]
   LimitNOFILE=150000
   
   

2. To change the name of the RabbitMQ cluster use the web management interface.
   Navigate to [admin] tab, select [Cluster] and set the name of the cluster as desired
   
   

3. Cloud platform queues
   
   
   

5.3. RabbitMQ installation (windows-based)

The following steps show how to perform a typical installation of RabbitMQ on three Windows Server 2019 nodes. The presented commands assume that the three (3) servers are named: node01, node02 and node03.

1. Connect to an available node (node01) with administrative credentials
   
   

2. Download the latest supported 64-bit Erlang version at the OTP Versions Tree page
   
   

3. Download the installer for the latest stable release of RabbitMQ server at Github
   
   

4. Set the following system-wide environment variables on the server:
   ERLANG_HOME = C:\Program Files\erl
   RABBITMQ_BASE = C:\RabbitMQ
   RABBITMQ_CONFIG_FILE = %RABBITMQ_BASE%
   RABBITMQ_NODENAME = rabbit@NODE01
   
   Note: Depending on the server host name you should also set the RABBITMQ_NODENAME environment variable as needed. For example if the server host name is srvrab01 then the variable should be set as RABBITMQ_NODENAME = rabbit@SRVRAB01
   
   

5. Restart the server node01
   
   

6. Install Erlang OTP using as installation path the path you set for the ERLANG_HOME environment variable in step 4
   Important: You must use an administrative account and install the software as an administrator (… run as administrator)
   

7. Install RabbitMQ Server using the default installation options
   Important: You must use an administrative account and install the software as an administrator (… run as administrator)
   Note: If you are installing a second or subsequent node (node02, node03, and so forth) copy the original cookie located on the first node (node01) at C:\Windows\System32\config\systemprofile\.erlang.cookie to the same location of the current node (overwrite if asked)
   
   

8. Add C:\Program Files\RabbitMQ Server\rabbitmq_server-A.B.CD\sbin to path system environment variable, where A.B.CD is the release version of the RabbitMQ Server you downloaded in step 3 (e.g.: 3.8.19)
   
   

9. Launch an elevated command prompt and run the following command:
   rabbitmqctl status
   
   If you encounter the error “[error] Failed to create cookie file 'h:/.erlang.cookie': enoent“ please proceed with the following actions:

   1. Edit the file C:\Program Files\RabbitMQ Server\rabbitmq_server-A.B.CD\sbin\rabbitmq-env.bat and locate the section
      
      REM Environment cleanup
      set BOOT_MODULE=
      set CONFIG_FILE=
      set FEATURE_FLAGS_FILE=
      set ENABLED_PLUGINS_FILE=
      set LOG_BASE=
      set MNESIA_BASE=
      set PLUGINS_DIR=
      set SCRIPT_DIR=
      set SCRIPT_NAME=
      set TDP0=
      
      Directly beneath this section insert a new line with the following content:
      set HOMEDRIVE=C:\RabbitMQ
      
      

   2. Copy C:\Windows\System32\config\systemprofile\.erlang.cookie to C:\rabbitmq (overwrite if asked)
      
      

   3. Run the following commands on an elevated command prompt to re-install the RabbitMQ service:
      rabbitmq-service stop
      rabbitmq-service remove
      rabbitmq-service install
      rabbitmq-service start
      
      

   4. Verify service is started and is operational by running the following commands on an elevated command prompt:
      rabbitmqctl start_app
      rabbitmqctl status

       

10. Create a user (rabbitadmin) with administrative privileges by running the following commands on an elevated command prompt:
    rabbitmqctl add_user rabbitadmin some_random_password
    rabbitmqctl set_user_tags rabbitadmin administrator
    rabbitmqctl set_permissions -p / rabbitadmin "." "." ".*"
    Note: You must not run these commands on subsequent nodes, since you will be forming a cluster and you will be accessing all cluster nodes using this specific set of credentials
    
    

11. Enable the management plugin by running the following command on an elevated command prompt:
    rabbitmq-plugins enable rabbitmq_management
    Verify access to the management interface by navigating to the URL: http://node01:15672 on the server
    
    

12. Configure the local server firewall by:

    1. Allowing incoming traffic to the following TCP ports: 5671, 5672, 4369, 25672, 35672-35682, 15672, 61613, 61614, 1883, 8883, 15674, 15675, 15692, 44002

    2. Allowing access to the following binaries:

       1. %ProgramFiles%\erl\bin\erl.exe (Erlang)

       2. %ProgramFiles%\erl\erts-X.Y.Z\bin\erl.exe (Erlang Run-Time System)

       3. %ProgramFiles%\erl\erts-X.Y.Z\bin\epmd.exe (Erlang Port Mapper Daemon)
          Note: X.Y.Z denotes the version of Erlang installed, make sure to check the path in order to get the correct version.
          
          

13. In order to install the rest of the nodes repeat steps 1 to 12 (omitting step 10) for all other nodes (node02 and node03 in this tutorial)
    Important: Make sure to copy the original cookie (C:\Windows\System32\config\systemprofile\.erlang.cookie) from the first node (node01) to the other nodes at Step 7
    
    

14. Join node node02 to the cluster by executing the following commands on an elevated command prompt:
    rabbitmqctl stop_app
    rabbitmqctl reset
    rabbitmqctl join_cluster rabbit@NODE01
    rabbitmqctl start_app
    
    

15. Join node node03 to the cluster by executing the following commands on an elevated command prompt:
    rabbitmqctl stop_app
    rabbitmqctl reset
    rabbitmqctl join_cluster rabbit@NODE01
    rabbitmqctl start_app
    
    

16. Check the cluster status and verify all three (3) nodes have joined the cluster by executing the following command on an elevated command prompt:
    rabbitmqctl cluster_status
    

5.4. RabbitMQ configuration (windows-based)

Initial configuration of the newly formed RabbitMQ cluster is required on the following items:

1. To change the name of the RabbitMQ cluster use the web management interface.
   Navigate to [admin] tab, select [Cluster] and set the name of the cluster as desired
   
   

2. Cloud platform queues