Ring-MQTT

References

• Ring-MQTT Wiki (documentation)
• DockerHub (Docker images)
• GitHub (Source code and issues)

Getting started

1. Be in the correct directory (assumed throughout):

   $ cd ~/IOTstack
   

2. Run the IOTstack menu:

   • Select "Services"
   • Select "ring-mqtt"
   • Select "Install"
   • Select "Return"
   • Select "Build"
   • Select "Exit" (twice)

   You can also do this from the command line:

   $ ./iotstack-menu.sh install ring-mqtt
   $ ./iotstack-menu.sh build
   

3. Bring up the container:

   $ docker compose up -d ring-mqtt
   

   This pulls the image from DockerHub, instantiates the container, and initialises its persistent storage.

4. Use sudo and a text editor to open the configuration file at the path. For example:

   $ sudo vi ./volumes/ring-mqtt/data/config.json
   

   At the time of writing, the default configuration file looked like this:

   {
       "mqtt_url": "mqtt://localhost:1883",
       "mqtt_options": "",
       "livestream_user": "",
       "livestream_pass": "",
       "disarm_code": "",
       "enable_cameras": false,
       "enable_modes": false,
       "enable_panic": false,
       "hass_topic": "homeassistant/status",
       "ring_topic": "ring",
       "location_ids": [
           ""
       ]
   }
   

   From the perspective of any process running in a Docker container, localhost means "this container" rather than "this Raspberry Pi". You need to edit line 2 to point to your MQTT broker:

   • If the ring-mqtt container and your mosquitto container are running on the same Raspberry Pi:

     "mqtt_url": "mqtt://mosquitto:1883",
     

   • Otherwise, replace localhost with the IP address or domain name of the host where your MQTT broker is running. For example:

     "mqtt_url": "mqtt://192.168.0.100:1883",
     

   • If your MQTT broker is protected by a username and password, refer to the Ring-MQTT Wiki for the correct syntax.

   Save your work then restart the container:

   $ docker compose restart ring-mqtt
   

5. Launch your browser (eg Chrome, Firefox, Safari) and open the following URL:

   http://«ip-or-name»:55123
   

   where «ip-or-name» is the IP address or domain name of the Raspberry Pi running your ring-mqtt container. Examples:

   • http://192.168.1.100:55123
   • http://iot-hub.my.domain.com:55123
   • http://iot-hub.local:55123

   You should see the following screen:

   

   Follow the instructions on the screen to generate your refresh token.

6. Check the logs:

   $ docker logs ring-mqtt
   

   Unless you see errors being reported, your ring-mqtt container should be ready.

Debugging

To enable debugging, create an override file at the path:

~/IOTstack/services/ring-mqtt/override.yml

with the content:

ring-mqtt:
  environment:
    DEBUG: ring-*

Refer to the Ring-MQTT Wiki.

To apply the change:

$ cd ~/IOTstack
$ ./iotstack-menu.sh build
$ docker compose up -d ring-mqtt

To undo this change, either:

1. Delete the override file; or

2. Edit the override file to disable the environment section, like this:

   ring-mqtt:
     x-environment:
       DEBUG: ring-*
   

and then re-apply the change as above.

Configuration

Consult the Ring-MQTT Wiki.

Maintenance

Periodically:

$ cd ~/IOTstack
$ docker compose pull ring-mqtt

If a new image comes down from DockerHub:

$ docker compose up -d ring-mqtt
$ docker system prune -f

The "up" instantiates the newly-downloaded image as the running container. The "prune" cleans up the older image.