-
Notifications
You must be signed in to change notification settings - Fork 104
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 Configuration Options below for details on the available options.
| Config Option | Description | Default |
|---|---|---|
| mqtt_url | URL for connecting to MQTT server. Example: mqtts://user:password@my-mqtt-host:8883 (TLS encryption with username/password authentication) | mqtt://localhost:1883 |
| enable_cameras | Default false since the native Ring component for Home Assistant supports cameras, set to true to enable camera/chime support in this add-on. Access to Chimes cannot be granted to shared users so Chime support requires use of the primary Ring account. | false |
| livestream_user | Specify a password for RTSP connections. Highly recommended if the RTSP port for external media player access is enabled. The livestream_password option must also be defined or this option is ignored. | blank |
| livestream_pass | Specify a password for RTSP connections. Highly recommended if the RTSP port for external media player access is enabled. The livestream_user option must also be defined or this option is ignored. | blank |
| enable_modes | Enable support for Location Modes for sites without a Ring Alarm Panel | false |
| enable_panic | Enable panic buttons on Alarm Control Panel device | false |
| beam_duration | Set a default duration in seconds for Smart Lights when turned on via this integration. The default value of 0 will attempt to detect the last used duration or default to 60 seconds for light groups. This value can be overridden for individual lights using the duration feature but must be set before the light is turned on. | 0 |
| disarm_code | Used only with Home Assistant, when defined this option causes the Home Assistant Alarm Control Panel integration to require entering this code to disarm the alarm | blank |
| location_ids | Array of location Ids in format: ["loc-id", "loc-id2"], see Limiting Locations for details | blank |
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-mqttRing 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:
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 !!!
Using 2FA authentication opens up the possibility that, if the environment running ring-mqtt is compromised, an attacker can acquire the refresh token and use this to authenticate to your Ring account without knowing your username/password and completely bypassing the standard 2FA protections. Please secure your environment carefully.
Because of this added risk, it can be a good idea to create an account dedicated for use with ring-mqtt and provide that account with access only to the specific devices that it should be able to control. This allows actions performed by ring-mqtt to be easily audited since they will show up in activity logs with their own name instead of that of the primary account. However, when using a shared account, there are some limitations as Ring does not allow certain devices and functions to be granted access to these accounts, thus, when using a shared account, support for Chimes, Smart Lighting groups, and Base Station volume control will not function.
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-mqttTo 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 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"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.
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.