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: current version of Chrome, Brave, Edge, Firefox, or Opera; no mobile browsers are currently tested or supported. I don't have a Mac and do not test with or explicitly support Safari, but since it's supported by jQuery, current versions may work.

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 16.13.0 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 Reactor 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 Reactor 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 Reactor 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 Reactor 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 16.13.0 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); the .tar.gz format is recommended for Linux users.
  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 only the IP address with the actual primary IP address of your Linux host.
  9. Start a trial run: NODE_PATH=$(pwd) 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.

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.

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

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, tar.gz form).

  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 (v16.13.0 if you let the script install nodejs).
  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.

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.

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

New Install: Windows 10 -- Bare Metal

  1. Download the nodejs install package (msi) from https://nodejs.org/ for the current LTS version of nodejs.
  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) in ZIP format.
  5. Unpack the archive in your new directory. This will create a reactor subdirectory;
  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 real directory path):

    For cmd.exe (the old Windows command shell):

    set NODE_PATH=C:\Users\Example\Documents\Reactor
    

    For Windows PowerShell:

    $env:NODE_PATH = 'C:\Users\Example\Documents\Reactor'
    
  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.

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.

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

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. Download a release package from: https://reactor.toggledbits.com/download/ (.tar.gz form).
  2. Stop Reactor:
    • If running under systemd: sudo systemctl stop reactor
    • Otherwise: touch/path/to/reactor/app.stop ; pkill -QUIT node
  3. 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-tar.gz-file>
    
  4. Update the package dependencies. Go into the reactor directory and run:

    npm update --no-save
    
  5. Restart Reactor.

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

Attention

Do not run the install script when performing an upgrade.

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

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.

Upgrading from versions prior to 21210

If your current version of Reactor on Windows is older than 21210 (seen in UI header upper-right corner), you should not upgrade it in place, but rather completely reinstall Reactor as described in the New Install: Windows 10 -- Bare Metal section above, and install Reactor as a Windows service.

  1. Download a Reactor distribution ZIP from https://reactor.toggledbits.com/download/ and place it in the folder above your existing reactor (runtime) directory.
  2. Stop the Reactor service.
  3. De-archive the distribution, allowing it to overwrite files in the existing reactor subdirectory — it will not overwrite your configuration or data files;
  4. Upgrade all package dependencies; from the "reactor" directory (where app.js is located), run:

    npm update --no-save
    
  5. Restart Reactor (restart the service).

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

Updated 2021-Dev-27