Skip to content

Installation

Installation Prerequisites

All system requirements are subject to change without notice.

  • CPU: 32- or 64-bit Intel/AMD, ARM v7/v8, or anything where the current LTS version of nodejs (and the nodejs packages on which Reactor depends) can run;
  • RAM: 2GB RAM or more is typically the minimum, depending on OS used and other services installed concurrently (e.g. MQTT broker, ZWave-JS, Home Assistant, etc.);
  • A stable time base: use NTP to sync time to network time servers (inside or outside of your network);
  • If you plan on running Reactor under docker, install both docker and docker-compose;
  • If you are not going to use docker, bare-metal installs require:
    1. nodejs version 16.13.0 or higher installed (download it here; LTS recommended);
    2. The system time zone must be local time for the installed location (UTC will not work unless you happen to live 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. Microsoft Internet Explorer is no longer supported.

Recommended Raspberry Pi Models

Reactor has been tested on the following Raspberry Pi models: 3B+, 4B, and Compute Module 4. The original (first generation) RPi, RPi 2, RPi Zero (all versions), and RPi Pico are not recommended due to limited RAM. The author's favorite RPi model for Reactor use is the Compute Module 4 (2GB or more RAM, 8GB or more eMMC recommended, and mounted on Raspberry Pi's Compute Module 4 I/O board). See discussion.

Raspbian Buster (RPi Debian 10) Docker Patch Requirement

Users that wish to use a docker container to run Reactor on a Raspberry Pi running Raspbian Buster will need to install the libseccomp2 patch. The patch process is described in the installation instructions below. This patch does not apply to/is not needed for Raspbian Bullseye.

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 (in the command shell) or geany (for desktop GUI users) easier to use. For Windows, NotePad++ is recommended, but any good plain text editor will do.

Other recommendations before you begin:

  • Read the Support and Suggestions page so that you know where to go if you have questions or need help during installation.
  • 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 latest- branded images are development builds that are updated periodically with the latest bug fixes and enhancements. If you want the most stable configuration possible, use the stable- branded builds, which are prior latest builds that have proven themselves free from serious issues.

  1. The docker container should be started and managed using an unprivileged user account (that is, not root). Issue the following commands to grant permission to the user account under which Reactor will run:

    sudo groupadd docker
    

    If you get a message that the group already exists, just ignore it and continue on...

    sudo service docker restart  # on some systems: sudo systemctl restart docker
    sudo usermod -a -G docker <username>
    

    IMPORTANT: If you are currently logged in as the user to which you are granting docker permission, log out and log back in before continuing.

  2. 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).

  3. Pull the docker image the usual (for docker) way: docker pull <imagename>

    # For most Intel/AMD-based systems (e.g. not Raspberry Pi):
    docker pull toggledbits/reactor:latest-amd64
    #
    # For RPi on Raspbian Buster or later 32-bit:
    docker pull toggledbits/reactor:latest-armv7l
    #
    # For RPi on Raspbian Bullseye 64-bit and NVIDIA Jetson Nano:
    docker pull toggledbits/reactor:latest-aarch64
    

    If you're not sure what your system architecture is, it's probably amd64 if you're using Windows, and if you are on Linux, you can run uname -m on the command line and it will tell you. If it reports x86_64, use amd64.

  4. If you are using a Raspberry Pi running Raspbian Buster (not Raspbian Bullseye), you must install a patch to your system. You can read about the reason here, here, and here. To find out what version of RaspberryPi OS you are running, run grep PRETTY_NAME /etc/os-release and if the word buster appears in the response, you need to patch; otherwise, skip to the next step. To perform the patch on buster:

    $ sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com:443 --recv-keys 04EE7237B7D453EC 648ACFD622F3D138
    $ echo "deb http://httpredir.debian.org/debian buster-backports main contrib non-free" | sudo tee -a "/etc/apt/sources.list.d/debian-backports.list"
    $ sudo apt update
    $ sudo apt install libseccomp2 -t buster-backports
    
  5. 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-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-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.

Simplifying Your Life with docker-compose

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. Install the docker-compose package before continuing.

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 22160)
#
# Change the lines indicated by "DO"...
#
version: '3'

services:
  reactor:
    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 (e.g. armv7l or aarch64 for RPi 4)
    image: toggledbits/reactor:latest-amd64

    restart: "always"
    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.

To upgrade your Reactor to a newer build (if you are using the latest channel version), the following commands will stop the container, pull the new image, and start a new container with it:

docker-compose down
docker-compose pull
docker-compose up -d

Launching the Reactor docker Container at Boot

In the examples above for running the container either by the docker command 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 (node -v will tell you). You can also download it directly; LTS recommended.
  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 nodejs installed in the previous step (try node -v to confirm access and version number).
  3. Download a Reactor distribution package; 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-XXXXX-YYYYY-NNNNN.tar.gz
    
  5. Change directory to the reactor subdirectory:

    cd reactor
    
  6. Install the package dependencies:

    npm install --loglevel error --no-save --omit dev
    
  7. Copy the contents of dist-config to config:

    cp dist-config/* config/
    
  8. Start a trial run:

    NODE_PATH=$(pwd) node app.js
    
  9. 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. 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 node executable (in ExecStart — you can find your node command by using which node on most Linux systems). Also 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
  5. To get your new Reactor service to automatically start at boot, run systemctl enable 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 (All Models) - 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 above.

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 (in 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.

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

    cd ./reactor
    bash tools/rpi-install.sh
    
  5. 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).

  6. 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 of the GUI session and log back in.
  7. At this point, you should be able to type node -v on the command line and see a correct/compatible nodejs version is running (v16.13.0 or higher if you let the script install nodejs).
  8. 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`
    
  9. 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. For this case, 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.

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 --omit dev
    
  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.

Third-party reliance

Installing Reactor as a service on Windows relies on a third-party npm package. To the extent that this package continues to be supported, this should all work fine, but I am not a Windows developers and don't plan on becoming one, so if this library is somehow disable/unsupported on a future version of Windows or nodejs, I will not be taking steps to mitigate the loss of this specific functionality. If someone in the community is a Windows developer/guru and wants to become the subject-matter expert for this area, and perhaps even a contributor to the package, that would be helpful — please make yourself known! Until then, enjoy it while it lasts.

  1. In a command prompt window, running as Administrator, change directory to your Reactor install directory.
  2. Install the node-windows package as a global package (it must be global or the service will not work, and you must install the specific version provided by the command below):

    npm uninstall node-windows
    npm uninstall -g node-windows
    npm install -g node-windows@1.0.0-beta.6
    npm link node-windows
    
  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.

If there are startup errors getting the service running, look at the various log files in the daemon directory created (in the Reactor install directory) by node-windows, in particular the reactor.wrapper.log file. If there are no obvious errors in any of the log files there, also check Reactor's reactor.log file for clues.

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. Remove any existing package-lock.json file from your Reactor install directory.

  5. Update the package dependencies. Go into the reactor directory and run:

    npm install --no-save --omit dev
    
  6. Restart Reactor.

  7. 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 and remove any existing Reactor service:

    cd \path\to\reactor
    node tools\install_reactor_windows_service.js -u .
    
  3. Remove any existing package-lock.json file from your Reactor directory.

  4. Unzip the archive file and copy its contents over the contents of your existing Reactor install directory.
  5. From the Reactor install directory, re-install/upgrade all package dependencies:

    npm install --no-save --omit dev
    
  6. If you are running Reactor as a Windows service, repeat those steps above.

  7. Restart Reactor (restart the service).
  8. Hard-refresh all browsers that are displaying Reactor content.

Updated 2022-Nov-11