Install on an existing system

Use this method when the target OS is already installed and you can sign in. You do not need to rewrite a card or run the card-preparation wizard. If you prefer individual commands, follow manual Linux installation.

Download and choose the target

Extract the complete nq2-installation folder. Keep core, config.yaml and the platform folders together. config.yaml is shared by all launchers; its comments are in English and the wizard can run in EN or PL.

Linux checks allow arm64, amd64 and armhf; Node.js 24 and the application dependencies must also support the target hardware. A listed architecture is not a guarantee that every native dependency will work. For a Raspberry Pi, use the 64-bit system described in the card guide. There is no native macOS installer.

The scripts are for a new application installation. They check occupied ports and existing selected services. If you already have Nginx, Mosquitto or Zigbee2MQTT, choose false for that component to keep it; configure the existing service separately. They do not upgrade an existing NQ2 installation. Linux accounts already using PM2 are rejected to avoid disturbing their processes; use a different existing regular account with --user.

Ubuntu or Raspberry Pi OS over SSH

Make sure the OS already has a working network and SSH. On your computer, extract the ZIP, open a terminal in the parent of nq2-installation, and copy the entire folder using SCP or SFTP. Replace YOUR_USER and DEVICE_ADDRESS with your actual login and server IP/hostname:

scp -r nq2-installation YOUR_USER@DEVICE_ADDRESS:~/
ssh YOUR_USER@DEVICE_ADDRESS
cd ~/nq2-installation

Now run one launcher on the target, as the regular account:

# Ubuntu
bash ubuntu/install.sh

# Raspberry Pi OS / Debian
bash raspbian/install.sh

The script requests sudo privileges. The two launchers use the same core/install_linux.sh engine. You do not need chmod +x when invoking them with Bash. If already logged in as root, select an existing application account explicitly, for example bash ubuntu/install.sh --user YOUR_USER.

The installer preserves the existing Linux account, password, hostname, network and SSH. Applications run from /opt/nq2 and /opt/zigbee2mqtt as the selected account. PM2 configuration is in that account’s home; installer settings are saved privately in /etc/nq2-image/config.yaml.

Wi-Fi: disable power saving

If the Raspberry Pi or Linux server uses Wi-Fi, disable Wi-Fi power saving to address intermittent disconnections after idle periods. The device can appear switched off while it is still running. The current NQ2 installer configures this automatically on systems using NetworkManager. For a manual installation or an older bundle, follow the Wi-Fi configuration and verification guide. Ethernet does not require this Wi-Fi change.

Existing Windows

Run windows\install.cmd from the complete extracted package. This installs NQ2 on the Windows computer, not on a Raspberry Pi card. Approve UAC using the same account that should own the applications. WSL and a separate Python installation are not needed by the wizard. Some application dependencies may require C++ build tools and Python; if npm install fails, resolve the reported requirement before retrying.

Keep the default destination C:\ProgramData\NQ2. Use a path without spaces: a previously tested application package had a UI path bug in directories containing spaces. Node.js and PM2 tools are private to this installation; Mosquitto is installed as a Windows service in Program Files\mosquitto. For a USB Zigbee coordinator, install its Windows driver and use its COM port, for example COM3.

The NQ2 Applications scheduled task starts PM2 applications after the selected Windows user logs in. It is not startup before login. Mosquitto runs as an automatic Windows service independently. Windows does not receive the Linux .local hostname setup; use localhost or the computer’s IP.

Wizard questions and installation order

1. Choose EN or PL.
2. Select Nginx, local Mosquitto and Zigbee2MQTT, all enabled by default.
3. When installing Mosquitto, choose whether other computers may access it. The default is false / local-only.
4. Enter the MQTT username/password and NQ2 administrator email/password. Enter accepts values from config.yaml. Change example passwords to your own.
5. If Mosquitto is disabled and Zigbee2MQTT is enabled, provide the existing broker URL, such as mqtt://192.0.2.10:1883, and its credentials. The example IP is a placeholder.

Order: common dependencies, Node.js 24, PM2 and package-manager tools → NQ2 download and npm install → optional Nginx → optional Mosquitto → final Zigbee2MQTT download, dependencies, build and startup. Application processes are named nq2 and zigbee2mqtt. Logs use PM2 rotation: 10 MB, seven compressed archives.

mqtt_allow_remote: false binds the new Mosquitto listener to 127.0.0.1. Set true to bind to all IPv4 interfaces at 0.0.0.0; other devices use mqtt://SERVER_IP:1883 with the MQTT credentials. Authentication stays enabled. Linux firewall rules are not changed. Windows adds the MQTT inbound rule only for Private networks with this option enabled. Router port forwarding and public internet exposure are not configured. This flag does not reconfigure an external broker or an already installed service.

Check progress and open NQ2

On Linux, the installation continues in the background through systemd, even if SSH disconnects:

sudo journalctl -u nq2-firstboot -f
sudo systemctl status nq2-firstboot --no-pager
pm2 list
pm2 logs nq2 --lines 100

Run pm2 as the same regular account that owns the applications; sudo pm2 accesses another process list. Ctrl+C exits log following without stopping installation.

On Windows, wait for the wizard’s completion message and use the installation’s wrapper:

C:\ProgramData\NQ2\pm2.cmd list
C:\ProgramData\NQ2\pm2.cmd logs nq2 --lines 100

With Nginx, open http://SERVER_IP (or http://localhost on the server); without it use port 8080. Selected Zigbee2MQTT uses port 8090. Sign in to NQ2 with the administrator credentials chosen in the wizard, then configure integrations using the appropriate MQTT address and credentials. Test again after a reboot; on Windows sign in to the selected account first.

Retry after an interruption

• Linux: failed service runs retry after 120 seconds; fix the cause shown in logs and use sudo systemctl restart nq2-firstboot. Do not rerun the setup wizard over saved state. A failure during setup may occur before the service exists.
• Windows: completed phases are recorded privately. Rerun install.cmd with the same options and credentials to resume; there is no automatic 120-second installer retry. Restore the original options if the saved-state check rejects changes.
• Successful installations do not keep downloading latest NQ2. This is not an update or migration tool.

The installer has automated checks. The package was smoke-tested on Windows, but that does not certify a full live installation of every service on every target OS. For setup without the installer, use the manual Linux guide.

Application configuration in .env

The installer creates /opt/nq2/.env on Linux or C:\ProgramData\NQ2\apps\nq2\.env on Windows. It writes NODE_ENV, PORT, ADMIN_EMAIL, ADMIN_PASSWORD using wizard / config.yaml values. PM2 starts NQ2 directly (pm2 start index.js --name nq2 for a package using index.js), and adds Zigbee2MQTT separately at the end. pm2 save records the list for startup. No ecosystem file is generated. This applies to new installations; existing installations are not automatically migrated.

Remove initial administrator settings after signing in

After the first startup and a successful sign-in to NQ2, remove ADMIN_EMAIL and ADMIN_PASSWORD from the application’s .env file. They are needed only during the first startup to create the administrator account. Keep the runtime settings, for example:

NODE_ENV=production
PORT=8080

Edit /opt/nq2/.env on Linux or C:\ProgramData\NQ2\apps\nq2\.env on a default Windows installation. Do this after confirming that your administrator login works.