Stackhero for MQTT Mosquitto

This add-on is operated by Stackhero

Mosquitto on dedicated instances, up-to-date versions and attractive prices.

Stackhero for MQTT Mosquitto

Last updated September 16, 2024

Stackhero for MQTT Mosquitto provides a managed MQTT Mosquitto instance running on a fully dedicated instance to handle thousands devices easily.

The Stackhero for MQTT Mosquitto add-on provides the folowing:

  • A private instance (dedicated VM) for high performances and security
  • TLS encryption (aka SSL)
  • Devices authentication and advanced ACLs via external API
  • An automatic backup every 24 hours
  • One click to update to new MQTT Mosquitto versions

There is an MQTT client library available for most languages including Ruby, Node.js, Java, Python, Clojure, and Erlang.

Provisioning the Add-on

You can attach Stackhero for MQTT Mosquitto via the CLI:

A list of all plans available can be found here.

$ heroku addons:create ah-mosquitto-mqtt-stackhero --app <your app name>
-----> Adding ah-mosquitto-mqtt-stackhero to sharp-mountain-4005... done

After you provision Stackhero for MQTT Mosquitto, the STACKHERO_MOSQUITTO_HOST and STACKHERO_MOSQUITTO_URL_TLS config variables are available in your app’s configuration. They contain the URLs to connect to your MQTT Mosquitto instance.

If you’ve checked the Allow clear connections option in your Mosquitto service, the STACKHERO_MOSQUITTO_URL_CLEAR environment variable will also be available. We don’t recommend using clear connections.

You can see the content of those variables via the heroku config:get command:

$ heroku config:get STACKHERO_MOSQUITTO_URL_TLS
$ heroku config:get STACKHERO_MOSQUITTO_LOGIN
$ heroku config:get STACKHERO_MOSQUITTO_PASSWORD

Local Setup

After you provision the add-on, you must replicate its config variables locally.

Use the Heroku Local command-line tool to configure, run, and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from an .env file. Use heroku config to view your app’s config variables. Use the following command for each value that you want to add to your .env file:

heroku config:get <STACKHERO_MOSQUITTO_VARIABLE> -s  >> .env

For example:

$ heroku config:get STACKHERO_MOSQUITTO_URL_TLS -s  >> .env
$ heroku config:get STACKHERO_MOSQUITTO_LOGIN -s  >> .env
$ heroku config:get STACKHERO_MOSQUITTO_PASSWORD -s  >> .env

Don’t commit credentials and other sensitive configuration values to source-control. In Git, exclude the .env file with: echo .env >> .gitignore.

For more information, see Heroku Local.

Connect to Stackhero Dashboard

You can see your instance usage, restart your instance, and apply updates from the Stackhero dashboard. You can access the dashboard via the CLI:

$ heroku addons:open ah-mosquitto-mqtt-stackhero
Opening ah-mosquitto-mqtt-stackhero for sharp-mountain-4005

You can also visit the Heroku Dashboard, select your application, and then select Stackhero for MQTT Mosquitto from the Add-ons menu.

Authentication

You can authenticate your users and devices connections to Mosquitto manually or with an external API.

Authenticating Manually

Manual authentication is useful when you are testing. If you want to handle more than 10 devices, you should authenticate with an external API.

You can use the manual authentication system to let your backend connect to Mosquitto and use the external API method to let your devices authenticate.

To add a new user, connect to your Stackhero dashboard, then select your Mosquitto service and choose “Configure”. For “Users”, specify a “login” and “password”. You can add up to 20 users with this method.

Authenticating using an External API

Use the external API to authenticate many devices. It can handle thousands of devices.

When a device connects to MQTT, Mosquitto makes an HTTP POST request to your API, passing a JSON string containing the username and the password for the device. If your API replies with an HTTP status code 200, the device is authorized. If it replies with a 401 (unauthorized) or another code, the device authentication is rejected.

For ACLs, 4 parameters are be passed: username, clientId, topic, acc. Your API must confirm username is allowed to make an acc type request on topic. acc can have the following values:

  • 1 - read access
  • 2 - write access
  • 3 - read and write access
  • 4 - subscribe access

For example, if the user userA tries to subscribe to the topic sensors/temperatures, your API receives the following JSON data:

{
  "username": "userA",
  "clientId": "userA",
  "topic": "sensors/temperatures",
  "acc": 4
}

See Gettng Started with Mosquitto to see an example API authentication server written in Jode.js.

Connecting to MQTT Mosquitto

You can retrieve your MQTT Mosquitto URL, username, and password via the following environment variables:

  • STACKHERO_MOSQUITTO_URL_TLS
  • STACKHERO_MOSQUITTO_LOGIN
  • STACKHERO_MOSQUITTO_PASSWORD

Upgrading Your Plan

You can’t downgrade an existing add-on.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade ah-mosquitto-mqtt-stackhero:newplan
-----> Upgrading ah-mosquitto-mqtt-stackhero:newplan to sharp-mountain-4005... done
       Your plan has been updated to: ah-mosquitto-mqtt-stackhero:newplan

Manage migration timing to ensure your application is available during the migration process.

Removing the Add-on

You can remove Stackhero for MQTT Mosquitto via the CLI:

This destroys all associated data and can’t be undone!

$ heroku addons:destroy ah-mosquitto-mqtt-stackhero
-----> Removing ah-mosquitto-mqtt-stackhero from sharp-mountain-4005... done

Support

Stackhero for MQTT Mosquitto support and runtime issues should be submitted via one of the Heroku Support channels. We recommend adding support@stackhero.io in copy for urgent issues.

Additional Resources

Feedback

Log in to submit feedback.