-
Notifications
You must be signed in to change notification settings - Fork 104
Installation (Manual)
Manual installation is possible, however, with the size this project has grown to, and the sheer number of variables for all of the different systems, it is impossible for me to help every person with their various installation issues so, manual installation is considered unsupported. I try to occasionally update these instructions, but I don't really test this method at all, and, if there are problems, you are going to have to solve them yourself. The project Dockerfile can be used as an additional reference, since it effectively is a scripted installation of ring-mqtt.
While manually installation is not particularly complex, it does require basic Linux admin knowledge such as working with systemd unit files, installation of binary applications both using the system package manager and manually, as well as a working understanding of file/folder permissions, etc. If this doesn't sound like you, then I highly recommend using the fully tested and supported Docker image instead as it should be quite easy to get running on any modern system.
If you decide to perform a manual installation, you will need to manually check for and update to any newly required pre-requisites when upgrading to new versions of ring-mqtt.
- NodeJS version should be 20.16.0 or later (latest LTS version is generally recommended). It's possible this code might run on previous versions, however, no testing has been completed on versions older than the recommended version.
- go2rtc v1.9.4 should be installed and available in the system path. For the most reliable streaming operation, you should download the custom built binary for your platform from https://github.com/tsightler/ring-mqtt/tree/main/bin, rename the file to simply go2rtc, and place it in the system path.
- The Mosquitto clients package (mosquitto_sub/mosquitto_pub) must be installed. These clients should be available via the package manager on most distributions (Ubuntu/Debian: "sudo apt install mosquitto-clients")
- The jq package must be installed. This package should be available via the OS package manager on most distributions (Ubuntu/Debian: "sudo apt install jq").
Once the pre-requisites have been met, simply clone this project from GitHub into a directory of your choice (the included systemd unit file below assumes /opt but can be easily modified):
git clone https://github.com/tsightler/ring-mqtt.gitThen switch to the ring-mqtt directory and run:
chmod +x ring-mqtt.js
npm installThis will install all of the required node dependencies.
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.
Two factor authentication (2FA) is mandatory for accessing the Ring API. Using 2FA requires acquiring a refresh token using either the built-in web UI or the provided init-ring-mqtt.js CLI tool. Either method will prompt for account information and 2FA code, acquire the token and save it to the ring-state.json file after which new tokens are requested and updated automatically in the state file.
If the script is started and the ring_token config parameter is empty, it will start a small web service at http://<ip_of_server>:55123. Simply navigate to this URL with your browser, enter your Ring account username/password and then 2FA code, and, if authentication is successful, the token will be saved and the script will connect to Ring and continue.
Use the get-ring-token.js CLI utility which will prompt for your account information and 2FA code and the acquire the token and save it to the state file:
node ./init-ring-mqtt.js!!! 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.
Once ring-mqtt is running review the Device Level Options to customize individual behavior of cameras, smart lighting and various other features.
For standalone installs the repo includes a sample systemd unit file, named ring-mqtt.service and located in the ring-mqtt/init/systemd folder, which can be used to automatically start the script during system boot. The unit file assumes that the script is installed in /opt/ring-mqtt and it runs the script as the root user (to make sure it has permissions to write config.json), but you can easily modify this to any path and user you'd like. Just edit the file as required and drop it in /lib/systemd/system then run the following:
systemctl daemon-reload
systemctl enable ring-mqtt
systemctl start ring-mqtt