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

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 subtree of directories in your user home directory to store your Reactor configuration and state data (the examples below will assume you have named it `reactor`).

       cd /home/username
       mkdir -p reactor/data
       mkdir -p reactor/reactor-ext

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 Bullseye 64-bit, NVIDIA Jetson Nano, etc.:
       docker pull toggledbits/reactor:latest-arm64

   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 it says any variant of `arm`, read the Caution below.

4. Start/create a container using the image:

       # Typically for Generic (modify with username below):
       docker run --name reactor -d --restart on-failure -p 8111:8111 -p 8554:8554 \
           -v /home/username/reactor/data:/var/reactor \
           -v /home/username/reactor/reactor-ext:/opt/reactor/ext \
           --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 -p 8554:8554 \
           -v /home/pi/reactor/data:/var/reactor \
           -v /home/pi/reactor/reactor-ext:/opt/reactor/ext \
           -e TZ=America/New_York \
           toggledbits/reactor:latest-arm64

For a list of time zones, see: https://grokipedia.com/page/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.yaml` file. You can find this file in the `tools/` subdirectory (next to your `config`). Do not modify the file in place! Copy it to another convenient location (e.g. `/home/username/reactor`) and modify the copy to reflect the correct paths to your Reactor `data` and `reactor-ext` subdirectories and the image name/architecture you are using. Depending on the system, you may also need to set the TZ environment variable with your correct time zone name.

tools/docker-compose.yaml

    # Multi-System Reactor template docker-compose.yml (version 26174)
    #
    # Adjust 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://grokipedia.com/page/List_of_tz_database_time_zones
          TZ: America/New_York

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

        restart: "always"
        expose:
          - 8111  # default Reactor UI port (no SSL/TLS)
          - 8554  # default Reactor UI port (when SSL/TLS configured)
        ports:
          - 8111:8111
          - 8554:8554
        volumes:
            # DO change the /home/username/reactor below to the directory you created for
            # your local data and extensions; DO NOT change the parts on the right side
            # of the colon (:); only change the pathnames on the left.
          - /home/username/reactor/data:/var/reactor
          - /home/username/reactor/ext:/opt/reactor/ext
          - /etc/localtime:/etc/localtime:ro
        tmpfs: /tmp

Start Reactor as a daemon with `docker-compose up -d` from the directory in which you placed your customized `docker-compose.yaml`.

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. Make sure nodejs is installed (see Installation Prerequisites above; try `node -v` to confirm install and version number);
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 nodejs.
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 run deps

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

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

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/11 — 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
        cd dashboard\slapdash
        npm install --loglevel error --no-save --omit dev
        cd ..\..

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 before 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 run deps

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/11 — 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/11 — 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
       cd dashboard\slapdash
       npm install --no-save --omit dev
       cd ..\..

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: 2026-Jun-22