Skip to content

Installation

Installation Prerequisites

All system requirements are subject to change without notice.

  • CPU/system? pretty modest requirements here...
  • 1GB RAM or more (2GB recommended for most systems);
  • A stable time base: use NTP to sync time to network time servers (inside or outside of your network);
  • The system (or container, if running in Docker or similar) time zone must be local time for the installed location (UTC will not work unless you're in UTC);
  • Web browser: Chrome 63+, Edge 18+, Firefox 58+, Opera 50+, Safari 11.1+; no mobile browsers are currently tested or supported.

If you are planning on using Docker, then docker should also be installed, of course, as well as docker-compose if you are going that additional step. For non-docker users (i.e. "bare metal" installers) you will need nodejs version 14.15 or higher.

You're also going to need a plain-text editor you are comfortable with. Most Linux systems have vi pre-installed, but many people find alternatives like nano easier to use. For windows, NotePad++ is recommended, but any good plain text editor will do.

Other recommendations:

  • It is strongly advised that a hard-wired Ethernet connection to the system running MSR be used. The relatively lower reliability of WiFi is not well-suited to the mission-critical nature of this application.
  • If you are using a Raspberry Pi, you are strongly advised to use an SSD boot drive rather than a MicroSD card. You can get by with the MicroSD card for a short while to get started and/or experiment, but most MicroSD cards are not up to the rigor of being a long-term-use filesystem for an application of this type, and fall short both on speed and reliability (the latter with tragic results).
  • A UPS or similar form of battery backup for your system is advisable. If you are providing power to your MSR host system via PoE (Power over Ethernet), the network switch providing power should be on a UPS. Be sure to configure your system to be "UPS-aware" and shut down in an orderly manner before battery is exhausted. Any Windows- or Linux-based host system runs the risk of data corruption/loss as a result of a sudden or disorderly shutdowns. It is up to you to "harden" the host system and its network.
  • Under no circumstances should you use port forwarding or other means to permit access to your MSR host or application (or anything else in your local network, really) from outside your network.

Now use the Table of Contents in the right margin to choose the installation process that suits your environment.

New Install: Docker Container

STOP! If you are using a docker container on a Synology or QNAP NAS system, please go to the respective detailed installation page for: Synology NAS or QNAP. Please note that docker images are only available for NAS systems that can run docker and are Intel/AMD-based. ARM and other processor architectures are not currently offered or supported.

There are several "official" Docker images for Reactor on DockerHub. The version-numbered images (e.g. 1.0.0-generic-amd64) are specific releases and will not change. The latest-branded images are development builds that are updated periodically. If you want the most stable configuration possible, choose a version-numbered build. If you want to follow the latest feature changes and bug fixes, use the latest builds.

Permissions

Depending on the permissions setup of your system, you may need to prefix the commands in steps 2 and 3 below with sudo. Try doing docker ps to list running containers. If you get an error, you probably need to use sudo (or, maybe docker isn't yet installed -- take care of that first!).

  1. Create a subdirectory in your user home directory to store your Reactor configuration and state data (the examples below will assume you have named it reactor).
  2. Pull the docker image the usual (docker) way: docker pull <imagename>

    # For most systems (except RPi):
    docker pull toggledbits/reactor:latest-generic-amd64
    #
    # For RPi on Raspbian Buster:
    docker pull toggledbits/reactor:latest-raspbian-armv7l
    
  3. Start a container using the image:

    # Typically for Generic (modify with username below):
    docker run --name reactor -d --restart on-failure -p 8111:8111 \
        -v /home/username/reactor:/var/reactor \
        --mount type=bind,src=/etc/localtime,target=/etc/localtime \
        toggledbits/reactor:latest-generic-amd64
    #
    # For Raspbian (assuming user "pi"):
    docker run --name reactor -d --restart on-failure -p 8111:8111 \
        -v /home/pi/reactor:/var/reactor \
        -e TZ=America/New_York \
        toggledbits/reactor:latest-raspbian-armv7l
    

For a list of time zones, see: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

To stop your container, run docker stop reactor. You can upgrade your container by stopping it, repeating the docker pull command with the name of the image you are using, and then starting it again.

Starting and stopping your container via the docker command can get a little verbose (particularly starting it). Many docker users prefer to use docker-compose to manage the container. This is a separate package you can install that uses a configuration file to capture the arguments necessary to run the container. The following is a template docker-compose.yml file. Modify it to reflect the correct path to your Reactor config/data directory and the image name you are using. Depending on the system, you may also need to set the TZ environment variable (uncomment in environment section below and provide the correct time zone name.

# Multi-System Reactor template docker-compose.yml (version 21209)
#
# Change the lines indicated by "DO"...
#
version: '3'

services:
  web:
    container_name: reactor
    environment:
      # DO change the TZ: line to set your local time zone.
      # See valid TZ list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      TZ: America/New_York
      #
      # DO NOT change this path. Your directory location is in "source" below.
      REACTOR_DATA_PREFIX: /var/reactor

    # DO change the image below to the one you are using, if necessary.
    image: toggledbits/reactor:latest-generic-amd64

    restart: "on-failure"
    expose:
      - 8111
    ports:
      - 8111:8111
    volumes:
        # DO change the /home/username/reactor below to the directory you created for
        # your local data; DO NOT change the /var/reactor part
      - /home/username/reactor:/var/reactor
      - /etc/localtime:/etc/localtime:ro
    tmpfs: /tmp

Start MSR as a daemon with docker-compose up -d from the directory in which you created your docker-compose.yml.

Starting at Boot

In the examples above for running the container either by docker directly or using docker-compose, the container is already configured to start at boot and restart if Reactor crashes. There is nothing more you need to do (except, perhaps, do a test reboot to make sure it's working properly).

New Install: Linux (various) - Bare Metal (without Docker)

  1. Install nodejs version 14.15 or higher. Most Linux distros have nodejs as an installable package via apt-get or yum, for example, but you will need to make sure it's a supported version. You can also download it directly.
  2. Log in as a non-root user. Reactor should not be installed or run as root. Any non-privileged account will do, as long as it has a home directory and access to the node.js installed in the previous step.
  3. Download a Reactor distribution package (release or latest).
  4. Make sure you are in the user home directory, and unpack the Reactor distribution package. A subfolder named reactor will be created/extracted:

    tar xzf /path/to/reactor-X.X.X-YYYYY-NNNNNN.tar.gz

  5. Change into the reactor subdirectory: cd reactor

  6. Install the package dependencies: npm install --loglevel error --no-save
  7. Copy the contents of dist-config to config: cp dist-config/* config/
  8. Edit the file config/reactor.yaml and, on the line beginning baseurl:, replace the IP address with the actual primary IP address of the Linux host.
  9. Start a trial run: node app.js
  10. Open a browser to http://your-system-ip-address:8111/ and you should see the Reactor UI. At this point, you will probably only see a single "reactor_system" entity in the Entities list, and that's normal.

Tip

To stop a Reactor server running in "trial" mode, just hit CTRL-C just once and wait a few seconds. It should exit cleanly.

Proceed to Getting Started for an overview before you configure the interface to your first home automation gateway.

Running Reactor as a Service

The tools directory includes an example service definition file for systems that use systemd for managing daemon processed (e.g. Ubuntu, Debian/Raspbian). If your system does not use systemd (perhaps it uses the older sysinit model), this procedure will not work and you will need to supply your own startup scripts.

To install the service file so Reactor is run as a systemd service:

  1. Copy (from the Reactor install directory) the example service file to the system directory:

    sudo cp tools/reactor.service-example /etc/systemd/system/reactor.service
    
  2. Use vi, nano, or your other favorite editor to change the pathnames in the [Service] section of the file so that they correctly point to your Reactor home directory (for WorkingDirectory and Environment, and the pathname to your nodejs executable (in ExecStart). Make sure you set the User to the owner of the directory where Reactor is installed.

  3. Tell systemd to reload the modified service files: systemctl daemon-reload (you need to do this any time you modify a service file; systemctl is usually pretty good about reminding you if it sees the file has changed, but it will not reload it automatically).
  4. Tell systemd to start Reactor: systemctl start reactor

You can restart a running Reactor service from the command line by running systemctl restart reactor, or stop the Reactor service with systemctl stop reactor.

Note that when running as a daemon, in early startup Reactor will log some message to the syslog daemon on your system. If Reactor isn't starting or is crashing, be sure to check the syslog log files (typically in /var/log) for messages, in addition to Reactor's own log files.

New Install: Raspberry Pi 4B (2GB/4GB/8GB) - Bare Metal (without Docker)

These are the instructions for "bare metal" installation on a Raspberry Pi 3B+/4B. If you prefer to use Docker, see the separate procedure below.

Be a 'Real' User

Except for the first optional step (enabling the SSH server), these steps do not require root privileges and you should not perform them as root or using sudo. All of these commands are intended to be run at a standard user permission level. The installation exists entirely within the home directory of the logged-in user. You can create a new user account, or use the default pi account.

  1. Optional but recommended: enable SSH on your RPi if you haven't already:

    sudo systemctl enable ssh ; sudo systemctl start ssh

  2. Download a Reactor distribution package (release or latest).

  3. Unpack the Reactor distribution package into the Documents subfolder of the logged-in user:

    cd ~/Documents
    tar xzf <path-to-reactor-distribution-archive-file>
    

Note

If your version/install of Raspios doesn't give you a Documents folder in your user directory, no problem. Just cd ~ and install Reactor right there in the user home. It really doesn't matter where Reactor is installed, as long as it's a directory that (a) you know and remember, and (b) the logged-in user has full permissions to use.

  1. Go into the installation directory and run the installation script like this:

    cd ./reactor
    bash tools/rpi-install.sh
    
  2. Follow the prompts in the script. If nodejs isn't available on your RPi, or the installed version is not compatible, the script will offer to install a local version (does not replace the system version installed, if any). If you want to install a specific version you've downloaded, you can run the script with the path to the downloaded archive file added as the first argument (e.g. bash tools/rpi-install.sh path-to-archive).

  3. When the script completes, log out, and then log back in. If you are in a terminal window in the GUI, it is not sufficient to simply close the terminal window and open another; you must fully log out and log back in.
  4. At this point, you should be able to type node -v on the command line and see a correct/compabitle nodejs version is running (v14.15.4 if you let the script do the download, or anything v14 or higher if it was already installed on your RPi).
  5. If you installed Reactor under systemd when the script asked, Reactor is now running, so skip to the next step. Otherwise, let's start Reactor manually in "trial" mode now. Issue the following shell command:

    NODE_PATH=$(pwd) node app.js`
    
  6. Open a browser to: http://your-rpi-ip-address:8111/ and you should see the Reactor UI. Click on the Entities link in the left navigation area, and you should see a single entity named "reactor_system", which is the entity that represents your RPi.

Tip

To stop a Reactor server running in "trial" mode, just hit CTRL-C and wait a few seconds. It should exit.

Tip

If you're running Reactor under systemd, you can stop Reactor by running sudo systemctl stop reactor, or restart a running Reactor instance with sudo systemctl restart reactor.

Proceed to Getting Started for an overview before you configure the interface to your first home automation hub/gateway.

Running Reactor as a Service

The install script will ask you if you want to run Reactor as a service. If you answered "yes" to this question, there's nothing more you need to do. If you answered "no" during the install, then you will need to install the Reactor systemd service manually. The procedure for running Reactor as a service under Raspbian is the same as that described in the "Bare Metal" section for other Linux systems, above. Please refer to that section.

New Install: Windows 10 -- Bare Metal

  1. Download the node.js install package (msi) from https://nodejs.org/
  2. Run the installer;
  3. Create a directory in a convenient location in which to install Reactor;
  4. Download a Reactor distribution package (release or latest).
  5. Unpack the archive in your new directory (you will need WinRAR or 7Zip to do this). This will create a reactor subdirectory. Note that if you are using 7Zip, you may need to run it twice: the first time to uncompress the archive to a .tar file, and the second time to de-archive the .tar file;
  6. Open a Command Prompt window;
  7. Change directory (cd) to the reactor subdirectory in your new directory. If you run dir, you should see app.js. This will from here forward be referred to as your Reactor install directory;
  8. Run the following commands in the Command Prompt window (if you get an error a name already exists, no worries, keep going):

    mkdir config
    mkdir storage
    mkdir logs
    
  9. Copy the default configuration files from dist-config to your new config directory (do not do this if you are just upgrading from a prior version of Reactor!):

    copy dist-config\* config\
    
  10. Install the node package dependencies for Reactor: npm install --loglevel error --no-save

  11. Set the NODE_PATH environment variable to the pathname of your Reactor install directory (note that although Windows does not think pathnames are case-sensitive, nodejs does, so make sure the case of your path value exactly matches the actual case of each element of the directory path):

    set NODE_PATH=C:\Users\Example\Documents\MSR
    
  12. Start Reactor: node app.js

  13. Open a browser window to http://127.0.0.1:8111/ and you should see the Reactor UI. Click the Entities left navigation item to see a single Reactor System entity.
  14. Type CTRL-C in the Command Prompt window to stop Reactor.

You may now proceed to Getting Started to do some initial configuration and get your first controller/hub configured.

Firewall?

You may need to open port 8111 on your system's firewall to allow access to Reactor.

Running Reactor as a Windows Service

If you want to run Reactor as a Windows service, there is a very experimental script in the tools subdirectory called install_reactor_windows_service.js. This script can both install and uninstall the Reactor service.

  1. Change directory to your Reactor install directory.
  2. Install the "node-windows" package: npm install node-windows --no-save
  3. Run the script to install:
    node tools/install_reactor_windows_service.js -i .
    

If your system's clock is using UTC, but your local timezone is not UTC, you need to add the option -t <zone> to the above install command to set the local timezone name. Valid timezone names can be found here.

To uninstall, run the command as shown above, but use -u in place of -i.

Upgrade: All Linux Platforms (including Raspberry Pi) -- Bare Metal (without Docker)

You can safely upgrade an existing Linux installation simply by un-tar'ing the release archive.

Tip

Un-taring the release archive will not overwrite your data or configuration, but it's always a good idea to make a backup when making any system changes.

  1. Stop Reactor: pkill -QUIT node
  2. Un-tar the release archive in the release directory by first changing to the directory that contains the reactor subdirectory (i.e. above reactor, not in it):

    cd /wherever
    tar xzvf <path-to-reactor-distribution-archive-file>
    
  3. Restart Reactor.

  4. Hard-refresh all browsers that are displaying Reactor content.

Attention

Do not run the install script when performing an upgrade.

Upgrade: Windows 10 -- Bare Metal

Tip

It's a good idea to back up your Reactor install before upgrading. At a minimum, make a backup of the config and storage subdirectories found underneath the reactor runtime directory.

  1. Download the Reactor update archive and place it in the folder above the reactor (runtime) directory.
  2. Stop Reactor (CTRL-C).
  3. Using WinRAR or 7Zip or similar tool, uncompress and de-archive the distribution, allowing it to overwrite files in the reactor subdirectory (it will not overwrite your configuration or data files).
  4. Restart Reactor (node app.js)
  5. Hard-refresh all browsers that are displaying Reactor content.

Updated 2021-Sep-02