Skip to content


Installation Prerequisites

All system requirements are subject to change without notice.

  • CPU/system? pretty modest requirements here...
  • 1GB RAM or more;
  • node.js version 14.15 or higher;
  • A stable time base: use NTP to sync time to network time servers (inside or outside of your network).
  • Web browser: Chrome 63+, Edge 18+, Firefox 58+, Opera 50+, Safari 11.1+; no mobile browsers are currently tested or supported.

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

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

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

  1. Install nodejs version 12.10 or higher. Version 14.15.4 (LTS) or higher is recommended. Most 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. Make sure you are in the user home directory, and unpack the Reactor distribution. A subfolder named reactor will be created/extracted:

    tar xzf /path/to/reactor-X.X.XXXXX-YYYYYY.tar.gz

  4. Change into the reactor subdirectory: cd reactor

  5. Install the package dependencies: npm install --loglevel error --no-save
  6. Copy the contents of dist-config to config: cp dist-config/* config/
  7. 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.
  8. Start a trial run: 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.


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

Proceed to Getting Started for an overview before you configure the interface to your first home automation 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. Unpack the Reactor distribution package into the Documents subfolder of the logged-in user:

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


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/
  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/ 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 v12 or higher if it was already installed on your RPi).
  5. Edit the file config/reactor.yaml and, on the line beginning baseurl:, replace the IP address with the actual primary IP address of your system.
  6. Start up Reactor: node app.js
  7. 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.


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

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

New Install: Docker Image for Synology

  1. Download the Reactor Synology docker image build and store it in your home directory on your Synology NAS. The Reactor image is not on Dockerhub, so you must download it from the Reactor project's Mantis bug tracker (see PR #58 for links, and click "Monitor" in that PR to receive email for updates/new builds).
  2. Make a subdirectory to contain Reactor's data and configuration files. This can be anywhere on your NAS to which you have access; your user home directory is recommended. You can use other directories, even on other volumes, if you choose. If uncertain right now, just create a "reactor-data" subdirectory in your home directory.
  3. Open Docker by clicking the "Open" button under the Docker item in the Package Center of your NAS. If you haven't yet installed Docker, go ahead and do that, and then open it when the install finishes.
  4. Click the "Image" tab in the left navigation area of the Docker window.
  5. Click the "Add" button in the header and choose "Add from File". Navigate to the Reactor image file downloaded in step 1 (in your home directory, unless you decided to put it elsewhere), select it, and hit the "Select" button. The system will upload the image; this takes a few moments.
  6. When the upload finishes, you'll see the "toggledbits/reactor" image listed. Click on that row in the list of images.
  7. Click the "Launch" button, which will open the container creation dialog.
  8. Adjust the "Container Name" if you wish. The "High Privilege" and "Resource Limitation" checkboxes should be left off. Leave all other settings at their defaults for now.
  9. Click the "Advanced Settings" button.
  10. On the Advanced Settings dialog are several tabs... we'll work through these one at a time, starting with the leftmost ("Advanced Settings"): turn on the "Enable auto-restart" checkbox. Then click the "Volume" tab header.
  11. On the "Volume" tab, click "Add Folder". Then, under "File/Folder", navigate to and select the directory you created earlier to contain your Reactor data. Under "Mount Path", enter "/var/reactor". Do not check the "read only" checkbox. When ready, click the "Network" tab header.
  12. The "Network Name" listed should be "bridge"; add it if it's not there. Then click the "Port Settings" tab header.
  13. On the "Port Settings" tab, the "Container Port" should show 8111. The "Local Port" must also show 8111; if it does not (e.g. it shows "Auto" or something else), click on the Local Port and change it to 8111. Click on the "Environment" tab header.
  14. On the "Environment" tab, add a variable called TZ and enter the canonical name of your local timezone, which is of the form area_name/locale_name (e.g. America/New_York or Europe/Prague. If you don't know it, you can browse this list. Also make sure the PORT environment variable agrees with the port assigned on the Network tab (8111 is the default).
  15. Click "Apply" to save your settings. This will close the Advanced Settings dialog and take you back to "Create Container".
  16. Click "Next" and you'll see a summary of the container configuration. Hit the "Run this container after the wizard is finished" checkbox and press "Apply" to start Reactor.

After a few seconds to make the container and start up, you should be able to browse to port 8111 on your NAS and see the Reactor UI: http://your-nas-IP:8111/

In the next steps, you'll be doing configuration by modifying the configuration files. These files are located in the Reactor data directory you created, in the config subdirectory. Any reference in other instructions to logs, config or other subdirectories will mean a subdirectory in your Reactor data directory. When asked to stop and start your container, you can just use the on/off slider in the Docker container list on the Reactor container's row.

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

New Install: Windows 10 -- Bare Metal

  1. Download the node.js install package (msi) from
  2. Run the installer;
  3. Create a directory in a convenient location in which to install Reactor;
  4. Download the Reactor package archive using the "Download" button in the Mantis Bug Tracker;
  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;
  8. Run the following commands in the Command Prompt window (if you get an error because on or both exists, no worries, keep going):

    mkdir config
    mkdir storage
  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. Start Reactor: node app.js
  12. Open a browser window to and you should see the Reactor UI. Click the Entities left navigation item to see a single Reactor System entity.
  13. 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.

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.


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.


Do not run the install script when performing an upgrade.

Upgrade: Windows 10 -- Bare Metal


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-02-22