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 18.18.2 or higher installed, current LTS version recommended — download it here;
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 recommended model is 4 Model B with at least 2GB 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.

As Raspberry Pis are still in short supply, there has been an ongoing discussion of low-costalternatives in the SmartHome Community.

Raspberry Pi OS Version

Versions of Raspberry Pi OS (previously called Raspbian) prior to Bullseye (Debian 11) are no longer supported, and Bullseye is now deprecated; recommended is bookworm (Debian 12). A 64-bit installation is recommended if supported by the hardware architecture of your chosen hardware, as newer versions of nodejs seem to have package dependencies that cannot be resolved on the older and 32-bit versions.

Raspbian Buster (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. Not that this OS is no longer supported, so if you are still using it, please upgrade to a newer version.

Alpha/Beta/Pre-release Software/Firmware/Hardware

Unless specifically required by instructions here, any and all pre-release versions of hardware, any host or client operating system, browser, firmware, application, or package are expressly not supported. They may work, but I will not spend time trouble-shooting issues on them. Use general release versions only, and preferably those designated for long-term support (LTS).

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.

Special Consideration for Home Assistant Users

There are several ways Home Assistant can be installed.. How you install Reactor depends in part on how you have installed Home Assistant.

Currently, the most-recommended way of installing Home Assistant is to use the all-inclusive install previously known as Hass.io, which includes the HassOS operating system, Supervisor, and add-ons. If this is how you have chosen to run Home Assistant, you may want to use the community-supplied (not officially part of the Reactor distribution) Reactor for Home Assistant Add-on. It is not required that you use this add-on, however; you can still use a docker container or bare-metal install, but in that case, it is not recommended that you install it under HassOS; use a separate host or VM.

If you have installed Home Assistant as a docker container (Home Assistant Container as described in their wiki), or by other "bare metal" means, then you probably want to install Reactor either as a docker container or bare-metal as well, either on the same host system with Home Assistant or on a separate host/VM.

Special Consideration for Non-US-English Language Users

Reactor inherits its locale settings from the host operating system configuration and the browser configuration (both). In order to ensure that Reactor displays the correct time and date formats, and possibly is even translated to display in your language, you must correctly set and configure your locale in the host operating system and your browser(s). These configurations are host- and browser-specific and will not be covered here. Once correctly configured, no further configuration of Reactor should be necessary.

Language Translations

Currently, only a translation for Swedish has been done. If you would like to do a translation for another language (and possibly contribute it for the benefit of other users), please see the Localization section.

New Install: Docker Container

STOP! If you are using docker on a Synology or QNAP NAS system, please go to the respective detailed installation page for: Synology NAS or QNAP NAS. If you are using Portainer (as a NAS add-on or otherwise), see the detailed instructions for Portainer.

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.

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

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.

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
```

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)

Make sure nodejs is installed (see Installation Prerequisites above; try node -v to confirm install and version number);
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 nodejs.
Download a Reactor distribution package; the .tar.gz format is recommended for Linux users.
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
```
Change directory to the reactor subdirectory:
```
cd reactor
```
Install the package dependencies:
```
npm run deps
```
Copy the contents of dist-config to config:
```
cp dist-config/* config/
```
Start a trial run:
```
NODE_PATH=$(pwd) node app.js
```
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:

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
```
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.
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).
Tell systemd to start Reactor: systemctl start reactor
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 4 and up. 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.

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

sudo systemctl enable ssh ; sudo systemctl start ssh
Download a Reactor distribution package (in tar.gz form).
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.
Go into the installation directory and run the installation script like this:
```
cd ./reactor
bash tools/rpi-install.sh
```
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).
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.
At this point, you should be able to type node -v on the command line and see a correct/compatible nodejs version is available.
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`
```
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

Download the nodejs install package (msi) from https://nodejs.org/ for the current LTS version of nodejs.
Run the installer;
Create a directory in a convenient location in which to install Reactor;
Download a Reactor distribution package (release or latest) in ZIP format.
Unpack the archive in your new directory. This will create a reactor subdirectory;
Open a Command Prompt window;
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;
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
```
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\
```

Install the node package dependencies for Reactor:

npm install --loglevel error --no-save --omit dev
cd dashboard\slapdash
npm install --loglevel error --no-save --omit dev
cd ..\..

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'
```
Start Reactor: node app.js
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.
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.

In a command prompt window, running as Administrator, change directory to your Reactor install directory.
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
```

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 before making any system changes.

Download a release package from: https://reactor.toggledbits.com/download/ (.tar.gz form).
Stop Reactor:
- If running under systemd: sudo systemctl stop reactor
- Otherwise: touch/path/to/reactor/app.stop ; pkill -QUIT node
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>
```
Remove any existing package-lock.json file from your Reactor install directory.
Update the package dependencies. Go into the reactor directory and run:
```
npm run deps
```
Restart Reactor.
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.

Download a Reactor distribution ZIP from https://reactor.toggledbits.com/download/ and place it in the folder above your existing reactor (runtime) directory.

Stop and remove any existing Reactor service:

cd \path\to\reactor
node tools\install_reactor_windows_service.js -u .

Remove any existing package-lock.json file from your Reactor directory.
Unzip the archive file and copy its contents over the contents of your existing Reactor install directory.

From the Reactor install directory, re-install/upgrade all package dependencies:

npm install --no-save --omit dev
cd dashboard\slapdash
npm install --no-save --omit dev
cd ..\..

If you are running Reactor as a Windows service, repeat those steps above.
Restart Reactor (restart the service).
Hard-refresh all browsers that are displaying Reactor content.

Updated 2023-Nov-25