Skip to content
  • There are no suggestions because the search field is empty.

Install Humly Sensor Gateway on Linux

This article explains how to install Humly Sensor Gateway (HSG) on Ubuntu or Debian. The installer sets up Node.js, the Mosquitto MQTT broker and a systemd service.

In this article

Before you start

  • A server that meets the requirements: Ubuntu 20.04, 22.04 or 24.04 LTS, or Debian 11, on x86-64.
  • A regular user account with sudo. The installer refuses to run as root.
  • Internet access from the server during installation.
  • The installation archive, hsg_installation_v<version>.tar.gz.
  • HSG must not run on the same server as Humly Control Panel.

Install HSG

  1. Copy the archive to the server and extract it: 
    tar -xzf hsg_installation_v<version>.tar.gz
cd v<version>
  2. Run the installer: 
    sudo bash install.sh
  3. The installer asks for a dashboard admin account and the Humly Control Panel details. All answers are optional. Leave a field empty to set it up in the dashboard later.
  4. Wait for the installer to finish. It prints the dashboard address.

Installer options

You can pass options to install.sh, for example for an unattended install.

Option Meaning
-p, --port Dashboard port. Default 3100.
-l, --log_level error, warn, info or debug. Default info.
-m, --memory_limit Memory limit for HSG in MB. Default 512.
-u, --server_url Humly Control Panel address, for automatic pairing.
--username, --password The Humly Control Panel integration user.
--admin_username, --admin_password Creates the dashboard admin on first start. No setup token is needed.
-s, --silent Runs without questions.

Example of a fully unattended install:

sudo bash install.sh -s -u https://humly.example.com --username hsg-integration --password '<password>' --admin_username facility-admin --admin_password '<password>'

Open the firewall

The installer does not change the firewall. If ufw is active, allow the dashboard and MQTT ports:

sudo ufw allow 3100/tcp
sudo ufw allow 1883/tcp

After installation

  1. Open http://<server>:3100 in a browser.
  2. If you created an admin during installation, sign in.
  3. If not, run hsg.sh logs and copy the setup token from the log.
  4. Continue with Humly Sensor Gateway - First-time setup.

Manage the service

Command What it does
hsg.sh status Shows whether HSG is running.
hsg.sh logs Shows the HSG log, including the setup token.
hsg.sh restart Restarts HSG.
hsg.sh stop / hsg.sh start Stops or starts HSG.

HSG runs as the systemd service humly-hsg, under the user hsg_user. The MQTT broker runs as the mosquitto service.

Folders and logs

Item Location
Program folder /home/<user>/Humly/SensorGateway, where <user> is the account that ran the installer
Data folder /home/<user>/Humly/SensorGateway/application_data. Holds the database, secrets and certificates.
Settings HSG reads application_data/humly-hsg.env
HSG log The systemd journal: hsg.sh logs or sudo journalctl -u humly-hsg
Broker log sudo journalctl -u mosquitto, and the dashboard Logs page

Change the dashboard port

  1. Edit HSG_PORT in application_data/humly-hsg.env.
  2. Edit PORT in application.config.json to the same value. This keeps the change after the next update.
  3. Run hsg.sh restart.
  4. Open the new port in the firewall, and update the webhook address in your network server.

Uninstall HSG

sudo bash /home/<user>/Humly/SensorGateway/dependencies/uninstall.sh
  • The uninstaller removes the HSG service and its broker settings.
  • It copies the database, settings and certificates to a backup folder under /tmp.
  • It then asks whether to delete the data folder and the hsg_user account.
  • Mosquitto and Node.js stay installed.

To install a newer version, do not uninstall. See Update Humly Sensor Gateway.

Humly Sensor Gateway guide

Get started

Install and set up

Connect sensors

Manage and troubleshoot