Installing NQ2

Choose the path that matches your device. The installer package contains platform-specific launchers and a shared config.yaml; the application ZIP contains NQ2 itself. They are different downloads.

Path 1: a fresh Raspberry Pi card

Use the Raspberry Pi guide with 16 screenshots. Write Raspberry Pi OS Lite (64-bit) with Raspberry Pi Imager, configure the account and network there, then run windows/raspianimager.cmd on your Windows computer to add the NQ2 first-boot installer. Only then eject the card and start the Pi.

This is the simplest setup for a new Raspberry Pi. The installer downloads NQ2 and the selected components on the Pi; it is not a preinstalled .img file and needs internet access at first boot.

Path 2: an existing operating system

Keep your installed system and use either:

• The platform installer: Ubuntu or Raspberry Pi OS over SSH, or a native Windows installation. The wizard handles dependencies, NQ2, startup and optional components.
• Manual installation on Linux: inspect and execute individual commands yourself. Includes Node.js, PM2, Nginx, MQTT authentication and Zigbee2MQTT. No NQ2 installer is run.

Use one method on a fresh application installation. These scripts do not upgrade an existing NQ2 installation or merge existing service configurations.

Which launcher do I use?

The package currently has no native macOS installer and no macOS/Linux raspianimager launcher. Imager is available on those computers, but the NQ2 card-preparation .cmd requires Windows. The Linux launchers run on the target Linux system, not against a card mounted on your computer.

Download and configure

Extract the complete nq2-installation folder. Keep core, the platform folders and config.yaml together. Windows needs no separately installed Python for the wizard. Linux requires Python 3.10+.

The wizard starts with EN/PL selection and reads defaults from the English-commented config.yaml:

install_nginx: true
install_mqtt: true
install_zigbee2mqtt: true
mqtt_allow_remote: false
mqtt_user: "nq2"
mqtt_password: "nq2"
admin_email: "[email protected]"
admin_password: "admin123"
nq2_url: "https://nq2.io/api/apps/nq2-local/download.zip"

The current installer defaults to the application API URL shown above. If reusing an older extracted installer, set nq2_url to that address before running it.

Set your own MQTT and administrator passwords before first start. Linux/SSH credentials, MQTT credentials and the NQ2 administrator account are separate. The Raspberry Pi network, hostname and Linux account come from Imager; the NQ2 wizard does not change them.

The install order is dependencies and Node.js 24 → NQ2 and PM2 → optional Nginx → optional Mosquitto → optional Zigbee2MQTT. The last three default to true; dependencies needed before the final Zigbee2MQTT download are prepared first. npm install runs for NQ2 on the target device. PM2 log rotation limits application logs to 10 MB per file, retaining seven compressed archives.

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.

Addresses and MQTT access

The IP address comes from your network/router; 192.168.1.100 is not hardcoded. Use your actual hostname. .local needs mDNS support on the client; native Windows installation does not advertise that name.

MQTT is local-only by default. To connect other computers or devices, answer yes to the MQTT access question or set mqtt_allow_remote: true before installation. Mosquitto then binds to 0.0.0.0 instead of 127.0.0.1, still requiring the configured username and password. Clients use mqtt://DEVICE_IP:1883; 0.0.0.0 is a listening address, not a client destination. Existing Linux firewall rules may also need to allow that port. Windows adds the MQTT rule only for the Private network profile and only with remote access enabled. This does not configure router port forwarding or public internet access.

Application download and updates

Every new installation downloads the NQ2 package available at download.zip. The fixed nq2_sha256 option is not used in config.yaml. The site’s checksum files describe published downloads; they are separate from installer settings.

The scripts do not automatically update an installed NQ2 application. See Apps for the application release and the installer download page for the automation bundle.

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.