Getting ready for RabbitMQ

To get started, the following three installation and configuration steps need to be completed:

• Installing the RabbitMQ broker
• Installing the management plugin (Web UI)
• Configuring the vhost and user

Let's start by installing the broker!

Installing the broker

CC runs its production servers on Ubuntu Linux. One developer has macOS and Linux, while the other one is all Windows. This heterogeneity is not a concern for RabbitMQ, which can run natively on all these operating systems.

RabbitMQ provides complete online installation guides for all the supported operating systems, and they can be found here: http://www.rabbitmq.com/download.html. This book contains instructions for Debian/Ubuntu, where RabbitMQ is installed from the apt repository. It also contains instructions for Docker further down in this chapter.

RabbitMQ installation on Ubuntu

There are relatively few steps required to install RabbitMQ. They are as follows:

1. Update Ubuntu.
2. Download and install the repository key.
3. Ensure the key is in the repository.
4. Install RabbitMQ from the package repository.

Ensure that Ubuntu is up to date before starting the download process. Make sure that the operating system is using the latest versions of all software since outdated dependencies create security vulnerabilities.

Run the apt update command to download the latest releases of the installed software:

apt upgrade

RabbitMQ requires several software packages. Verify that curl, apt-transport-https, and GnuPG are on the system by running the following command:

sudo apt install curl gnupg -y
sudo apt install apt-transport-https

The -y option accepts any licenses for these dependencies. Ubuntu installs all required sub-packages.

Discover the name of the operating system by running any of the following commands:

• cat /etc/os-release
• lsb_release -a
• hostnamectl

The release name is non-technical. Previous names include focal and bionic. Ubuntu does not include RabbitMQ by default, so it must be added to the repository key before you proceed. Execute the following set of commands in a Terminal:

curl -fsSL https://github.com/rabbitmq/signing-keys/releases/download/2.0/rabbitmq-release-signing-key.asc 
sudo apt-key add -
sudo tee /etc/apt/sources.list.d/bintray.rabbitmq.list <<EOF
deb https://dl.bintray.com/rabbitmq-erlang/debian [os release name] erlang
deb https://dl.bintray.com/rabbitmq/debian [os release name] main
EOF

These commands download the key and add it to the repository list before adding the appropriate operating system packages for the broker and Erlang.

RabbitMQ is written in Erlang, a functional language that has robust built-in support for creating distributed networks. The developers maintain a list of minimum versions (https://www.rabbitmq.com/which-erlang.html) of the language for the latest supported releases of the broker. At the time of writing, RabbitMQ 3.8 supports Erlang 21.3 through 23.

RabbitMQ can now be installed correctly.

Run the following commands to install RabbitMQ:

sudo apt install -y rabbitmq-server
sudo apt install librabbitmq-dev 

The librabbitmq-dev library includes a client for interacting with the broker. However, the server may be the only requirement.

RabbitMQ installation on Docker

Docker containers allow the separation and control of resources without risking corrupting the operating system. Instructions for installing Docker are available from the official website: https://docs.docker.com/get-docker/. With Docker installed, pull the RabbitMQ image:

docker pull rabbitmq

Run the broker with reasonable defaults:

docker run -d --hostname my-rabbit --name my-rabbit -p 5672:5672 -p 15672:15672 -e RABBITMQ_ERLANG_COOKIE='cookie_for_clustering' -e RABBITMQ_DEFAULT_USER=user -e RABBITMQ_DEFAULT_PASS=password  --name some-rabbit rabbitmq:3-management

A Docker container needs to be created so that it's accessible from the localhost with the management console enabled. This will be discovered shortly.

Starting RabbitMQ

Installing the RabbitMQ server from the repository also installs a suite of command-line tools used to start the server for the first time. This is done by executing the following command:

rabbitmq-server start 

The server starts in the foreground. To run the broker as a service, use the following commands:

sudo systemctl enable rabbitmq-server
sudo systemctl start rabbitmq-server
sudo systemctl status rabbitmq-server 

The systemctl command can also be used to manage services in Ubuntu. The output of the final command should show that the broker is running. Consult the RabbitMQ documentation (https://www.rabbitmq.com/troubleshooting.html) if not.

Downloading the example code

Download all the example code files for this book. They can be purchased from http://www.packtpub.com. If you purchased this book elsewhere, visit http://www.packtpub.com/support and register to have the files emailed to you directly.

Verifying that the RabbitMQ broker is running

Now, verify that the RabbitMQ broker is actually working by using the status service command.

Write the following line in the Terminal:

$ sudo service rabbitmq-server status
  rabbitmq-server.service - RabbitMQ broker
   Loaded: loaded (/lib/systemd/system/rabbitmq-server.service; enabled; vendor preset: enabled)
  Drop-In: /etc/systemd/system/rabbitmq-server.service.d
           └─10-limits.conf, 90-env.conf
   Active: active (running) since Mon 2019-04-29 13:28:43 UTC; 1h 43min ago
  Process: 27474 ExecStop=/usr/lib/rabbitmq/bin/rabbitmqctl shutdown (code=exited, status=0/SUCCESS)
 Main PID: 27583 (beam.smp)
   Status: "Initialized"
    Tasks: 87 (limit: 1121)
   CGroup: /system.slice/rabbitmq-server.service
           ├─27583 /usr/lib/erlang/erts-10.2.2/bin/beam.smp -W w -A 64 -MBas ageffcbf -MHas ageffcbf -MBlmbcs 512 -MHlmbcs 512 -MMmcs 30 -P 1048576 -t 5000000 
           ├─27698 /usr/lib/erlang/erts-10.2.2/bin/epmd -daemon
           ├─27854 erl_child_setup 1000000
           ├─27882 inet_gethost 4
           └─27883 inet_gethost 4

Apr 29 13:28:42 test-young-mouse-01 rabbitmq-server[27583]:   ##  ##
Apr 29 13:28:42 test-young-mouse-01 rabbitmq-server[27583]:   ##  ##      RabbitMQ 3.7.14. Copyright (C) 2007-2019 Pivotal Software, Inc.
Apr 29 13:28:42 test-young-mouse-01 rabbitmq-server[27583]:   ##########  Licensed under the MPL.  See https://www.rabbitmq.com/
Apr 29 13:28:42 test-young-mouse-01 rabbitmq-server[27583]:   ######  ##
Apr 29 13:28:42 test-young-mouse-01 rabbitmq-server[27583]:   ##########  Logs: /var/log/rabbitmq/rabbit@test-young-mouse-01.log
Apr 29 13:28:42 test-young-mouse-01 rabbitmq-server[27583]:                     /var/log/rabbitmq/rabbit@test-young-mouse-01_upgrade.log
Apr 29 13:28:42 test-young-mouse-01 rabbitmq-server[27583]:               Starting broker...
Apr 29 13:28:43 test-young-mouse-01 rabbitmq-server[27583]: systemd unit for activation check: "rabbitmq-server.service"
Apr 29 13:28:43 test-young-mouse-01 systemd[1]: Started RabbitMQ broker.
Apr 29 13:28:43 test-young-mouse-01 rabbitmq-server[27583]:  completed with 9 plugins.

Look at the running processes for RabbitMQ and find both the service wrapper and the Erlang VM (also known as BEAM) that's running, as follows:

$ pgrep -fl rabbitmq
27583 beam.smp

$ ps aux | grep rabbitmq
ubuntu   10260  0.0  0.1  14856  1004 pts/0    S+   15:13   0:00 grep --color=auto rabbitmq
rabbitmq 27583  0.5  8.5 2186988 83484 ?       Ssl  13:28   0:36 /usr/lib/erlang/erts-10.2.2/bin/beam.smp -W w -A 64 -MBas ageffcbf -MHas ageffcbf -MBlmbcs 512 -MHlmbcs 512 -MMmcs 30 -P 1048576 -t 5000000 -stbt db -zdbbl 128000 -K true -- -root /usr/lib/erlang -progname erl -- -home /var/lib/rabbitmq -- -pa /usr/librabbitmq/lib/rabbitmq_server-3.7.14/ebin  -noshell -noinput -s rabbit boot -sname rabbit@test-young-mouse-01 -boot start_sasl -config /etc/rabbitmq/rabbitmq -kernel inet_default_connect_options [{nodelay,true}] -sasl errlog_type error -sasl sasl_error_logger false -rabbit lager_log_root "/var/log/rabbitmq" -rabbit lager_default_file "/var/log/rabbitmq/rabbit@test-young-mouse-01.log" -rabbit lager_upgrade_file "/var/log/rabbitmq/rabbit@test-young-mouse-01_upgrade.log" -rabbit enabled_plugins_file "/etc/rabbitmq/enabled_plugins" -rabbit plugins_dir "/usr/lib/rabbitmq/plugins:/usr/lib/rabbitmq/lib/rabbitmq_server-3.7.14/plugins" -rabbit plugins_expand_dir "/var/lib/rabbitmq/mnesia/rabbit@test-young-mouse-01-plugins-expand" -os_mon start_cpu_sup false -os_mon start_disksup false -os_mon start_memsup false -mnesia dir "/var/lib/rabbitmq/mnesia/rabbit@test-young-mouse-01" -kernel inet_dist_listen_min 25672 -kernel inet_dist_listen_max 25672
rabbitmq 27698  0.0  0.1   8532  1528 ?        S    13:28   0:00 /usr/lib/erlang/erts-10.2.2/bin/epmd -daemon
rabbitmq 27854  0.0  0.1   4520  1576 ?        Ss   13:28   0:00 erl_child_setup 1000000
rabbitmq 27882  0.0  0.1   8264  1076 ?        Ss   13:28   0:00 inet_gethost 4
rabbitmq 27883  0.0  0.1  14616  1808 ?        S    13:28   0:00 inet_gethost 4

Note that by default, the broker service is configured to auto-start when the Linux host starts.

Installing the management plugin (Web UI)

RabbitMQ does not install a management console by default, but the optional web-based plugin used in this example makes it easy to peek into a running RabbitMQ instance.

The Debian package installs several scripts. One of them is rabbitmq-plugins. Its purpose is to allow us to install and remove plugins. Use it to install the management plugin, as follows:

$ sudo rabbitmq-plugins enable rabbitmq_management 
Enabling plugins on node rabbit@host:
rabbitmq_management
The following plugins have been configured:
 rabbitmq_consistent_hash_exchange
 rabbitmq_event_exchange
 rabbitmq_federation
 rabbitmq_management
 rabbitmq_management_agent
 rabbitmq_shovel
 rabbitmq_web_dispatch
Applying plugin configuration to rabbit@host...
The following plugins have been enabled:
  rabbitmq_management
  rabbitmq_management_agent
  rabbitmq_web_dispatch

Yes, it is that easy!

Use a web browser to reach the home page of the management console by navigating to http://<hostname>:15672, as shown in the following screenshot:

Stay tuned for the next episode – creating and configuring users!

Configuring users

One of the scripts that's installed by the Debian package is rabbitmqctl, which is a tool for managing RabbitMQ nodes and used to configure all aspects of the broker. Use it to configure an administration user in the broker, as follows:

$ sudo rabbitmqctl add_user cc-admin taxi123
Adding user "cc-admin" ...

$ sudo rabbitmqctl set_user_tags cc-admin administrator
Setting tags for user "cc-admin" to [administrator] ...

By default, RabbitMQ comes with a guest user that's authenticated with the guest password. Change this password to something else, as follows:

$ sudo rabbitmqctl change_password guest guest123

Navigating back to the management console login screen allows us to log in with the username cc-admin and the password taxi123.

The welcome screen provides an overview of the broker's internals, as shown in the following screenshot:

Note that at this point, the cc-admin user is not able to examine any exchange or queue in any vhost. For now, another user must be created for development purposes so that applications can connect to RabbitMQ.

Create the cc-dev user, as follows:

$ sudo rabbitmqctl add_user cc-dev taxi123
Adding user "cc-dev" ...

As discussed earlier in this chapter, RabbitMQ supports the notion of vhosts, which is where different users can have different access privileges. The CC development environment will have a vhost, also known as vhost. Anything that happens in the vhost happens in isolation from any other environment created in the future (such as a QA environment). It is possible to set per-vhost limits on a number of queues and concurrent client connections in later versions of RabbitMQ (3.7+).

Create a vhost called cc-dev-vhost, as follows:

$ sudo rabbitmqctl add_vhost cc-dev-vhost
Adding vhost "cc-dev-vhost" ...

This creates a user and a vhost for development.

Configuring dedicated vhosts

RabbitMQ comes with a default vhost called / that the guest user has full permissions for. Though this is convenient for quick tests, it is recommended that a dedicated vhost is created to keep concerns separated so that it is possible to completely drop a vhost and restart from scratch without unexpected impacts.

As it stands, neither the cc-admin nor cc-dev users have permission to do anything on cc-dev-vhost. You can fix this by giving the vhost full rights, as follows:

$ sudo rabbitmqctl set_permissions -p cc-dev-vhost cc-admin ".*" ".*" ".*"
Setting permissions for user "cc-admin" in vhost "cc-dev-vhost" ... $ sudo rabbitmqctl set_permissions -p cc-dev-vhost cc-dev ".*" ".*" ".*"
Setting permissions for user "cc-dev" in vhost "cc-dev-vhost" ...

To recap what was just done, most of the command is straightforward but the ".*" ".*" ".*" part looks a tad mysterious, so let's analyze it.

It is a triplet of permissions for the considered vhost, which grants configure, write, and read permissions on the designated resources for the considered user and vhost. Resources, which consist of exchanges and queues, are designated by regular expressions that match their names. In this case, any resource that's requested via the .* regular expression is allowed.

The actual commands that are granted depend on the resource type and the granted permissions. For a complete list of the access control policies supported by RabbitMQ, see http://www.rabbitmq.com/access-control.html.

As an alternative to all command lines, turn to the user management features of the management console. Click on the Admin tab of the console and then on the cc-dev user listed in the Users tab to view information similar to what's shown in the following screenshot. The entire user configuration that was set from the command line is visible and can be edited in the management console:

The details of an individual user can be found by clicking on a given user's name in the management console:

The RabbitMQ broker and the management plugin (Web UI) have been installed and the vhost and the users have been configured.