Docker RabbitMQ Server

Overview

This project creates a Docker based RabbitMQ server.

The stack includes:

• A RabbitMQ server.

Credit

This repo is based on the official RabbitMQ Docker image available at https://hub.docker.com/_/rabbitmq/.

Quick Start

Do the following to quickly get up and running with this server.

1. Provide or create TLS certs: (You can learn more about TLS with RabbitMQ on their TLS Support page.)
   1. For production use: provide your own TLS certs (CA Cert, Server Cert, Server Key). Be sure to update the RabbiqMQ config file /[repo-root]/rabbitmq/config/rabbitmq.conf to provide the proper file names for your certs.
   2. For dev/test, you could use the included TLS Gen script to generate self-signed certs. (See Generating TLS Certs for Dev.) You can also provide self signed certs using any other means.
2. With certificates in place, from the root of the repo run docker compose build to build the stack. (Internet is required at this point).
3. From the root of the repo, run docker compose up -d to bring the stack up.
4. The passwords for the RabbitMQ admin (rmqadmin) and one RabbitMQ user (rmquser) are generated by the setup, then stored in files inside ./rabbitmq-secrets/. (Note, if you want to create different users, see Ansible Provisioning.)
5. Access the RabbitMQ Admin Console at https://localhost:15671/ (or whatever domain you're using that matches your TLS certs). If you used a self-signed TLS cert, your web browser will give you a warning, which you can skip since you are using self-signed certs.
6. Don't forget to stop the stack once you are done. From the root of the repo, you can run docker compose down --volumes to bring down the stack.

Example Client Code (Connecting to RMQ)

We invite you to visit our other repository, AMQP Cacoon, a NodeJS package that facilitates connecting to RabbitMQ from NodeJS. This repo contains the library and also several examples that demonstrate how to work with an AMQP host and how to use TLS when connecting.

Stack Details

RabbitMQ Version

The file docker-compose.yml includes a parameter RMQ_VERSION_TAG: which will determine the version of RabbitMQ that will be used. Update that to suit your needs. You can find versions on the official Docker Image page https://hub.docker.com/_/rabbitmq/.

RabbitMQ Server Details

The RabbitMQ Server in this stack provides a RabbitMQ Core with standard AMQP. TLS certificates are not provided, but we do provide a tool you can use to generate self-signed for development purposes, or of course, you can provide your own.

The default setup has TLS enabled and uses the domain https://localhost:15671/.

The rest of this documentation assumes you understand concepts of RabbitMQ. If you'd like to learn more about RabbitMQ, please see our RabbitMQ primer.

• Plugins Installed:
  • Management - to manage RMQ using a web dashboard.

Note: You can install more plugins by editing the file /[repo-root]/rabbitmq/config/enabled_plugins.erl. Learn more about RabbitMQ plugins on the RabbitMQ Plugins page.

RabbitMQ Configuration

The instance of RabbitMQ created by this image is configured via the file rabbitmq.conf in the /rabbitmq/config/ directory of this repository. The configuration provided here is fairly basic but it can be fully customized to suit your needs.

Please refer to RabbitMQ's Configuration page for the full details!

Stack Dependencies

The following are the items you need on your workstation to use this stack:

1. docker
2. docker-compose (recent versions of Docker include docker-compose as a built in command!)
3. Homebrew (macOS workstations only, see "macOS Docker Install via Homebrew")
4. Internet for the Docker Build (although see the section "Deploy Images to a Remote Docker Server Offline" if your docker host does not have Internet access.)

macOS workstations, Docker Desktop Install via Homebrew

Developers on macOS can install Docker via Homebrew:

$ brew cask install docker

The above should install both docker and docker-compose. After installing via Homebrew, be sure to start Docker.app for the first time and get through the initial permissions dialogs in macOS.

Windows workstations, Docker Desktop via Docker.com

Developers on Windows should follow the steps at https://docs.docker.com/docker-for-windows/install/. Note, Windows imposes additional dependencies in terms of version of Windows and features.

Offline Ubuntu, Docker CE via Offline Installation

This option allows Docker to be installed in a system that does not have internet access.

Docker Install Steps:

1. Download the proper packages on a workstation with internet access from https://download.docker.com/linux/ubuntu/dists/, choose your Ubuntu version, then browse to pool/stable/, choose amd64, armhf, arm64, ppc64el, or s390x, and download the .deb files for the Docker Engine version you want to install. (You need 3 packages: containerd.io, docker-ce-cli, docker-ce).
2. Copy the three packages to the target machine.
3. Install the packages in the following order:

$ sudo dpkg -i /path/to/containerd.io_x.x.x_amd64.deb
$ sudo dpkg -i /path/to/docker-ce-cli_x.x.x-ubuntu-xenial_amd64.deb
$ sudo dpkg -i /path/to/docker-ce_x.x.x-ubuntu-xenial_amd64.deb

(Replace the x.x.x with the proper version you downloaded! Replace 'xenial' with your proper Ubuntu version.)

After the above three packages are installed, make sure you enable Docker to restart on boot with:

$ sudo systemctl enable docker

Docker-Compose Install Steps

1. Download the desired release of Docker-Compose from https://github.com/docker/compose/releases.
2. Copy the downloaded package to the target machine.
3. Rename and move to a useful path with:

$ mv docker-compose-Linux-x86_64 docker-compose
$ chmod +x docker-compose
$ sudo mv docker-compose /usr/local/bin/

(Replace the downloaded name above with the one that matches your download.)

Generating TLS Certs for Dev

For development and testing, you can generate self-signed TLS certs with the library tls-gen (a copy of which is included in this repo). We have also provided a simple script to run the tool.

1. Verify that you have or Install Python 3.6+ on your workstation.
2. Verify that you have or Install OpenSSL on your workstation.
3. Change into /[project-root]/rabbitmq/provisioning/tls-gen/.
4. Execute the script generate-certs.sh. This will create certs and drop them into /[repo-root]/rabbitmq/config/certs/.

Note that the certs are generated for the hostname docker-rmq.local, but you can change that to suit your needs!

Deployment

Deployment Steps:

• Copy the entire contents of this repo to the host with Docker installed.
• Build (see "Docker Build" elsewhere in this document.)
  • Online hosts: build the container's image on the host. (Requires Internet).
  • Alternatively, for offline hosts, deploy your packaged image. (See "Deploy Images to a Remote Docker Server Offline".)
• Start the container when ready (see "Startup" elsewhere in this document.)

Deploy Images to an Offline Remote Docker Server

If you need to deploy images to a remote Docker server that does not have Internet access, use this procedure to build then export images from a workstation with Docker.

For full details, refer to https://docs.docker.com/engine/reference/commandline/save/

On a computer that has Internet Access

$ sudo docker pull ubuntu

(Note, on macOS, omit the sudo from the above command.)

Alternatively, you can do a local BUILD from a Docker compose configuration.

Once you have your image(s) ready, export them with:

$ sudo docker save -o /path/to/your/image/docker-rmq.docker docker-rmq

(Note, on macOS, omit the sudo from the above command.)

Zip then transfer the file to the offline computer. Once there, unzip then load the image from the file:

sudo docker load -i /path/to/your/image/docker-rmq.docker

You can verify with:

sudo docker image list

Once your image(s) is(are) deployed, you can then deploy the other needed files (docker-compose.yml, and other necessary files to support your stack.)

Using the stack

Dependency Repos

None.

Stack Configuration

Configuration for the stack can be added to the .env file. Any variables in that file will be available to use in other stack files as ${ENV_VAR_NAME}. You can also edit other variables in docker-compose.yml.

Docker Build

Every time you PULL from the project repository or if you make changes to Dockerfile or any of the files in the rabbitmq directory, you'll want to re-build the docker image.

To re-build the Docker image(s), from the root of this project:

$ docker compose build

Startup

Most of the time, you'll just need to start up the stack. To do this, from the root of this project:

$ docker compose up -d

(-d runs the container in the background. Skip that to run the container interactively and see the command output.)

The Docker-Compose.yml file sets up the container with restart: always so the container should restart on host server boot.

Note: Each time the stack is started, an Ansible provisioning script will run on one or more servers to ensure the servers are properly configured! See Ansible Provisioning for more information.

Stop Docker

Once you're done with the stack, you should stop it so it does not consumer resources on your workstation.

To stop the Server Stack:

# This will stop the Stack
$ docker compose stop

Cleanup Docker

If you're done and also want to clean up the state of the Server Stack, you can do a cleanup of the volumes dedicated to the Stack.

To stop and cleanup the Stack:

# This will stop your application and remove all volumes associated with the container
$ docker compose down --volumes

Docker Processes

To see the Docker processes running, from the same directory that contains the Docker-compose file, you can use the command:

# This will stop your application and remove all volumes associated with the container
$ docker compose ps

Connecting to and Managing the servers/services on the Stack

Connecting

RabbitMQ Clients should connect on the TLS port 5671 as they would to any normal RMQ server (using AMQPS=AMQP over TLS.)

Authentication is required for all connections.

Note: For the users and passwords, look in rabbitmq-secrets/. To start up RMQ with different users/passwords, you can edit the values in the rabbitmq-secrets files and repeat the up process. If you delete the files in rabbitmq-secrets new random passwords will be created for the configured users!

RabbitMQ Management

After the RMQ server is up, you can see the management console at:

• https://localhost:15671/#/

(You might need to accept your browser's warnings about SSL Security if you're using a self-signed TLS cert.)

The login for the console is: u: rmqadmin P: [see the note below]

Note: For the admin passwords, look in rabbitmq-secrets/. To start up RMQ with a different password, you can the value in the rabbitmq-secrets files and repeat the up process. If you delete the files in rabbitmq-secrets a new random password will be created!

Ansible Provisioning

Every time the container starts, the Ansible provisioing script in /[repo-root]/rabbitmq/provisioning/ansible-config-at-up.yml will execute. For now, all this does is ensures your users are created in RabbitMQ, but it is possible to use this to perform additional setup. This could include, creating exchanges and queues and otherwise setting up RMQ to suit your needs.

Learn more about Community.Rabbitmq support in Ansible.

To creat more or different users for RMQ, edit /[repo-root]/rabbitmq/provisioning/ansible-config-at-up.yml to suit your needs.