Deploy an MQTT Broker

The MQTT Broker conventionally lives on a small server by itself. The exact reasons for this are lost in the mists of time, but I think were around avoiding resource competitions and ensuring that the broker would be as stable as possible.

Traditionally we have one broker per Infra. This may change going forwards
Infras are provisioned using Ansible Deployments.

Broker Discovery (DNS)

Brokers are discovered via DNS.

The conventional dns for a broker is mqtt.<infra_id>.<…​>.smartermicrogrid.com.

  • Note that this is a public tld.

  • The <…​> represents that fact that there is usually a level of grouping below the tld. Initially, this grouping was a deploy_level (i.e. prod or dev). Later examples include clients, where the mqtt broker is there just for a particular client. Currently, there is no definite convention, and there are likely to be changes anyway.

Ports

Conventionally, brokers run in the port range 20200 - 20300.

The mqtt AWS security group will open these.

AWS EC2 Instance

If the broker is in AWS, you will first need to Create an EC2 Instance of an appropriate size.

Copy one of the existing broker instances and just change the tags for a pre-configured setup.

Ansible Hosts

You may need to add this broker to multiple ansible host files.

If the broker is in AWS, you should add it to the prov/hosts/aws/hosts file. This won’t be enough to actually deploy the broker, but it does register it as an AWS instance for general AWS server maintenance down the line.

If it is for an infra, you should also add it the infra’s hosts file, as per Creating a New Infra Platform. If you are following those instructions this will have enough information to deploy.

Ansible Vars

If you have not already done so by following the Creating a New Infra Platform docs, you will need to have the following vars:

# Required vars for your deployment

mqtt_broker_host: mqtt.<infra_id>.<...>.smartermicrogrid.com


# included by default in the `all` group_vars

mqtt_broker_port: 20200
mqtt_username: smc
mqtt_password: *****
mqtt_config_dir: "/var/lib/dgcsdev/mosquitto/conf"
mqtt_data_dir: "/var/lib/dgcsdev/mosquitto/data"

Ansible Users

If you have a custom user for the infra, you must provide the user details in the mosquitto user.conf file.

This currently has no automation script. Follow the instructions at http://www.steves-internet-guide.com/mqtt-username-password-example/.

The standard smc user will be created regardless.

Deployment

The _mosquitto.yml playbook will do that actual deployment.

If you are using an infra hosts file, the command will look something like:

$ smcrelease <infra> 1.0.0 _mosquitto.yml

Validate Installation

You will need to have the mosquitto tools commands installed. On OSX this can be done with brew install mosquitto.

Tun the following in two separate terminals:

# Shell 1
$ mosquitto_sub -u <USER> -P '<PASSWORD>' -v -h mqtt.<infra_id>.<...>.smartermicrogrid.com -p <PORT> -t hello

# Shell 2
$ mosquitto_pub -u <USER> -P '<PASSWORD> -v -h mqtt.<infra_id>.<...>.smartermicrogrid.com -p <PORT> -t hello -m world

You should see hello world printed in shell 1.

the mosquitto_sub command is installed on OSX alongside mosquitto, i.e. brew install mosquitto.

Local Deployment

Although you can install and run mosquitto directly - in OSX via brew install mosquitto, it is probably better to use a docker image.

Have a look at the roles referenced in the _mosquitto.yml playbook for guidance.