Installation (Docker)

For Docker installation, please read this document entirely as it covers important configuration steps that are required prior to running the Docker image.

Starting with version 5.x, all installation methods store configuration and state data in two separate files. The config.json file stores global configuration options needed for startup, while the ring-state.json file contains run-time generated state data such as the current refresh token, generated systemId, and device specific configuration options and generally should not be edited by hand. Because of this requirement, the Docker installation method now requires a persistent volume from the host to be mapped to /data within the container.

Before the first run of the ring-mqtt image, select a source path on the Docker host to store the persistent data. The examples below use /etc/ring-mqtt on the host, but it can be any path which Docker can access and to which it has read/write/create permissions. After creating the desired path, download the default config.json file and save it to that path. Once saved, edit the file to set the required configuration options as appropriate to your environment. See Global Configuration Options for details on the available options.

Pull the Docker Image

While it is possible to build the image locally from the included Dockerfile, it is recommended to install and update by pulling the official image directly from Docker Hub. To pull the image manually without running the container, simply issue the following command:

docker pull tsightler/ring-mqtt

Authentication

Ring has made two factor authentication (2FA) mandatory thus the script now only supports this authentication method. Using 2FA requires acquiring a refresh token for your Ring account which can be done by running the included get-ring-token.js CLI tool which will prompt for the required account information and 2FA code, and then acquire the token and save it to the ring-state.json file where it will be updated automatically going forward. Below is an example of running this command directly from the docker image, note that you must map the same persistent volume that will be used for running the primary container image:

Acquire a token for the Docker image via CLI

Run the bundled get-ring-token.js utility directly via the Docker command line to acquire the token:

docker run -it --rm --mount type=bind,source=/etc/ring-mqtt,target=/data --entrypoint /app/ring-mqtt/init-ring-mqtt.js tsightler/ring-mqtt

!!! Important Note regarding the security of your refresh token !!!
Be sure to restrict access to your system as any user that gets access to the refresh token can authenticate to the associated Ring account with no other credentials.

Docker Run

Now that the initial configuration is complete and the refresh token has been generated, it's time to start the container by issuing the appropriate "docker run" command as follows:

docker run --rm --mount type=bind,source=/etc/ring-mqtt,target=/data tsightler/ring-mqtt

Starting the Docker container automatically during boot

To start the ring-mqtt docker container automatically during boot simply use the standard Docker methods, for example, adding --restart unless-stopped to the docker run command will cause Docker to automatically restart the container unless it has been explicitly stopped.

Docker Compose

Docker Compose also works well if this method of managing Docker containers is preferred. An example docker-compose configuration is as follows:

version: "3.7"
services:
  ring-mqtt:
    container_name: ring-mqtt
    restart: unless-stopped
    image: tsightler/ring-mqtt
    ports:
      - 8554:8554                      # Enable RTSP port for external media player access
    volumes:
      - /etc/ring-mqtt:/data           # Mapping of local folder to provide persistent storage
    logging:                           #limit logs to 10m and 3 files
      options:
        max-size: 10m
        max-file: "3"

Docker Specific Features

External RTSP Server Access

When using the camera support for video streaming the Docker container will also run a local instance of rtsp-simple-server. If your streaming platform runs on the same host you can usually just access directly via the Docker network, however, if you want to access the stream from other host on the network you can expose the RTSP port during startup as well. Note that, if you choose to export the port, it is HIGHLY recommended to set a live stream user and password using the appropriate configuration options.

To expose the RTSP port externally, simply add the standard Docker port options to your run command, something like "-p 8554:8554" would allow external media player clients to access the RTSP server on TCP port 8554.

Branch Selection

The Docker image includes a feature that allows for easy, temporary testing of the latest code from the master or dev branch of ring-mqtt from GitHub, without requiring the installation of a new image. This feature was primarily designed to simplify testing of newer code for users of the Home Assistant addon, but Docker users can leverage it as well. When running the Docker image normally the local image copy of ring-mqtt is used, however, sometimes the latest code in the GitHub repo master branch may be a few versions ahead, while waiting on the code to stabilize, or a user may need to test code in the dev branch to see if it corrects a reported issue. This feature allows this to be done very easily without having to push or build a new Docker image. To use this feature, simply set the BRANCH environment variable while running the container: BRANCH="latest" When this option is set, the container startup scripts will fetch the latest code from the Github master branch prior to starting ring-mqtt BRANCH="dev" When this option is set, the container startup scripts will fetch the latest code from the Github dev branch prior to starting ring-mqtt

To revert to the code in the Docker image, simply run the container without the BRANCH environment set.