Installation (Docker)

Overview

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.

Persistent Storage

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 <host_path> which you can substitute with any valid path which Docker can access and to which it has read/write permissions. After creating the desired path continue with the steps below, substituting your source path for the <host_path> placeholder in the example commands below.

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

Two factor authentication (2FA) is mandatory for Ring API access thus the script only supports this authentication method. Using 2FA requires acquiring a refresh token for your Ring account which can be done by running the included init-ring-mqtt.js CLI tool which will prompt for the required account information and 2FA code, acquire the token and, finally, save it to the ring-state.json file where it will be updated automatically going forward. This tool will also create a default config.json file in the same location if one does not already exist. 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 the Refresh Token

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

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

!!! Important Note regarding the security of your refresh token !!!
The refresh token provides complete access to your Ring account without requiring any additional account information so be sure to protect your system from access by unauthorized parties.

Set Configuration Options

Prior to running the container for the first time you should edit the <host_path>/config.json file with the appropriate information. See Global Configuration Options for details on the available settings.

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=<host_path>,target=/data tsightler/ring-mqtt

Starting Automatically on 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:
      - <host_path>:/data           # Mapping of local folder to provide persistent storage
    logging:                           #limit logs to 10m and 3 files
      options:
        max-size: 10m
        max-file: "3"

Device Level Options

Once ring-mqtt is running review the Device Level Options to customize individual behavior of cameras, smart lighting and various other features.

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 branch selection feature allows for easy, temporary testing of the latest development code from the development branch of ring-mqtt by pulling the latest code directly from GitHub, without requiring the installation of a new image. This feature is primarily designed to simplify testing of newer code for users of the Home Assistant addon, but Docker users can leverage it as well. To use this feature, simply set the BRANCH environment variable while running the container as desired.

Using BRANCH="latest" will fetch the latest code from the Github main branch prior to starting ring-mqtt
Using BRANCH="dev" will fetch the latest code from the Github development branch prior to starting ring-mqtt

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