Quick Start

This guide walks you through running UNIHH-IOT locally end to end. Two options are provided:

  • Option 1: Docker Compose (recommended) — one command brings up every backend service and dependency, ideal for evaluation and standard deployment;
  • Option 2: Bare-metal JAR — build and start each module individually, ideal for edge gateways and fine-grained control.

Prerequisites

ComponentVersionPurpose
Docker20+ (with Compose v2)Run all services (Option 1)
JDK8 or 17Backend build (both options)
Maven3.6+Backend build
Node.js16+Frontend build and dev server
MySQL client8.0Only for manual DB init in Option 2

Hardware

Any 2-core / 4GB machine runs the full stack comfortably. Core services are tuned to 64–128MB heaps and drivers to 32–64MB — see Deployment.

The repository ships a docker-compose.yml orchestrating 8 services: MySQL, EMQX, the gateway, admin, data center and three protocol drivers. MySQL mounts db/unihh_iot.sql on first start and initializes the schema automatically.

Step 1: Build the Backend Modules

Images are packaged from locally compiled JARs (same artifacts as bare-metal):

# from the repository root
mvn clean package -DskipTests

Step 2: Build Images and Start

# Linux / macOS
bash build-docker.sh

# Windows
build-docker.bat

The script runs docker compose build, then start everything:

docker compose up -d

Step 3: Wait for Readiness

# all 8 containers should be healthy / running
docker compose ps

# tail logs and check for errors
docker compose logs -f

Services and ports:

ServiceContainerPortsPurpose
MySQL 8.0unihh-mysql3306Business DB unihh_iot (root / 123456, auto-initialized)
EMQX 5.xunihh-emqx1883 / 8083 / 8084 / 8883 / 18083MQTT bus and Dashboard (admin / public)
Gatewayunihh-gateway28000Unified REST entry
Adminunihh-admin28001Management service
Data centerunihh-data28002Rule engine and storage routing
Modbus driverunihh-driver-modbus28011Modbus TCP/RTU
S7 driverunihh-driver-s728012Siemens S7
OPC UA driverunihh-driver-opcua28013OPC UA

EMQX ports: 1883 MQTT TCP (bus), 8883 SSL/TLS, 8083 WebSocket, 8084 WSS, 18083 Dashboard console.

Step 4: Start the Frontend

The compose stack does not include a frontend container. Run it locally:

cd unihh-frontend
npm install    # or pnpm install
npm run dev

Open http://localhost:3000.

Production

npm run dev is for local development only. In production run npm run build and serve the output through Nginx with the API reverse-proxied — see Deployment → Nginx Reverse Proxy and Frontend Hosting.

Step 5: Sign In

EntryURLAccountDefault Password
UNIHH-IOT platformhttp://localhost:3000adminunihhiot
EMQX Dashboardhttp://localhost:18083adminpublic
MQTT bustcp://localhost:1883unihhunihh

Security

Change every default password before production. Platform passwords live in System → Users; MySQL and EMQX credentials are set in docker-compose.yml environment variables — see Deployment → Docker Compose.

Option 2: Bare-metal JAR

Ideal for edge gateways (Raspberry Pi / industrial PCs) or per-process control.

Step 1: Start the EMQX Message Bus

The official image ships with MQTT authentication preconfigured:

docker run -d --name unihh-emqx \
  -p 1883:1883 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 8883:8883 \
  -p 18083:18083 \
  registry.cn-shenzhen.aliyuncs.com/deversun/unihh-emqx:v20261009

Verify EMQX at http://localhost:18083 (admin / public).

Step 2: Initialize the Database

CREATE DATABASE unihh_iot DEFAULT CHARACTER SET utf8mb4;

# business data (required)
mysql -u root -p unihh_iot < db/unihh_iot.sql

# time-series storage (optional, for TDengine)
taos -s "CREATE DATABASE unihh_iot"
taos -u root -d unihh_iot < db/tdengine_schema.sql

Step 3: Build and Start the Backend

mvn clean package -DskipTests

Start core services in order:

# 1. Gateway :28000
java -jar unihh-gateway/target/unihh-gateway.jar

# 2. Admin :28001
java -jar unihh-admin/target/unihh-admin.jar

# 3. Data center :28002
java -jar unihh-data/target/unihh-data.jar

# 4. Drivers you need, e.g. Modbus :28011
java -jar drivers/unihh-driver-modbus/target/unihh-driver-modbus.jar

For production use the minimal-heap flags from Deployment.

Step 4: Start the Frontend

cd unihh-frontend
npm install    # or pnpm install
npm run dev

Open http://localhost:3000 and sign in with the accounts above.

Verify the Platform

After signing in, check the dashboard:

  1. Mounted protocol drivers > 0 and showing online;
  2. Connected devices matches your configured device count.

If a driver shows offline, run Channel Self-check in Driver Management or see the FAQ.

Next Steps