beez miniBMS documentation

Installation

The one file installation (recommended)

For a fresh machine, run install-everything.bat from the extracted package (double click; it asks for administrator rights itself). First login admin / admin; a new password is forced immediately. No other step exists.

Since 2026.08.8-34 it runs in six stages, and nothing is registered on the machine until the platform has been proven to start on it:

  1. Inspect the system. Windows build, PowerShell version, administrator rights, free disk, package completeness, the Python it found and its version, Mosquitto, whether ports 8000 and 1883 are free, and which of our services already exist. This stage changes nothing at all; it only reports.
  2. Install every dependency. Python 3.12 if absent (all users, never per user), then this installation's own virtual environment in .venv, then the Python packages into it, then Mosquitto and NSSM. The packages are verified by actually importing them with the interpreter that will run the service, because pip reporting success is not the same fact.
  3. Configure the machine. Folders, the Windows Firewall (inbound TCP 8000 for the console and UDP 47808 to 47820 for BACnet, plus program rules for the platform and the broker), disabling the stock mosquitto service so it cannot fight ours for port 1883, and clearing ports 8000 and 1883.
  4. Preflight. The platform is started in the foreground with its output captured, and the installer waits for the console to answer. If it cannot start, the real error is printed on the spot and nothing is registered.
  5. Register the services. beez-mqtt and beez-minibms, autostart, only now that stage 4 has proven they can work.
  6. Verify. The console is polled again, both services are reported, and the summary names every log path.

Port 1883 is deliberately never opened in the firewall: the trial broker listens on loopback only.

Requirements

Windows 10 or 11, Python 3.12 or newer (the installer brings 3.12 if missing), and Mosquitto (the installer brings it too). Keep the installation path free of special characters; C:\Dev\beez-minibms is the reference layout.

Everything this platform runs, in a window or as a service, runs from one interpreter: the virtual environment at .venv inside the installation folder. That is deliberate and it is what makes service mode reliable. A virtual environment belongs to the machine rather than to a user account, so the LocalSystem account the services run under can always read it; it cannot be disturbed by a Python installed or removed later; and it is the same interpreter run.bat uses, so console mode and service mode can never disagree about what is installed. It is created by the installer, kept by updates, and never travels inside a package.

Recommended: the one-shot installer (service mode)

Right click installer\install-windows.ps1 and Run with PowerShell; this is exactly what install-everything.bat launches, and it runs the six stages above. The services beez-mqtt and beez-minibms are registered through NSSM, stored under installer\vendor, with unbuffered output so the service logs in data\ actually contain what the processes wrote. Pass -SkipPreflight to skip stage 4 on a machine already known good; it is on by default because it is what turns a silent service failure into a readable error.

The result survives reboots with no window open. installer\uninstall-windows.ps1 removes the services again and finishes with a process sweep, so the folder can be renamed or deleted immediately afterwards (data stays). stop-all.bat does the stop without removing the services.

Portable alternative: console mode

Unzip anywhere clean and double click run.bat. On first start it creates the .venv, installs dependencies, and launches the platform in the window. You manage Mosquitto yourself in this mode (or keep the beez-mqtt service from a previous installer run). Do not combine with service mode on the same machine.

First login

A fresh installation starts with one account, admin / admin, and you are required to set a new password the moment you sign in, there is no setup command to run first. From there, create real accounts per person under Admin, Users; roles are viewer, operator, admin (tenant scope), and superadmin (platform scope). A superadmin can create another superadmin. Every new user defaults to requiring a password change at their own first login too (a checkbox on the create form, on by default), and each account can carry security rules: disabled, a shorter session length, or a list of networks it may sign in from.

Reaching it from the network

The server binds 0.0.0.0:8000, so colleagues on the LAN or VPN reach it at http://<machine-ip>:8000. Allow it in the Windows Firewall prompt on first start. There is no TLS termination built in; keep it on trusted networks.

Securing the MQTT broker

The MQTT broker is the spine that carries every point value and every point name from site gateways to the platform, so its posture matters. The shipped broker/mosquitto.conf is already set up correctly; the deployment steps are:

Bind the broker to a private interface. The default is listener 1883 127.0.0.1, which is right when the platform and broker share one box (the usual field case). If a bridge runs on a different machine, change that line to this host's VPN adapter IP, never 0.0.0.0, and firewall port 1883 to the VPN address range, so the broker is unreachable from outside the VPN.

Keep authentication on and give each gateway its own credential. The config keeps allow_anonymous false and points at a password_file. Create one credential per edge gateway and one for the backend with mosquitto_passwd, unique per site, and rotate them on staff changes.

Enforce per gateway topic isolation. The config points at an acl_file; broker/acl.example is a ready template. Each gateway credential is confined to exactly its own project namespace, so one compromised gateway can neither read another building's data nor publish values or names into another building's topics. This is what keeps tenants isolated on the wire and closes the cross site name path behind the console's escaping.

Enable TLS as a second layer where practical. The config carries a commented TLS listener on 8883; point it at real certificates, bind it to the VPN adapter, and have gateways connect on 8883 so telemetry and credentials are encrypted even on the VPN.

Onboarding the first building

Hand the site's EDE 2.3 export to the miniBMS onboarding Claude Project and import the returned bundle zip in the Admin tab (Import project bundle), then connect the project to a BACnet bridge (Connect a project to a bridge) and restart that bridge. The wizard onboard-customer.bat and the onboard command are the scripted fallbacks. Details and the graphics contract are in the team guide at /help.html.

Packaging for distribution

For building a standalone setup executable there is an Inno Setup definition (installer\beez-minibms.iss) and installer\build.bat (PyInstaller onedir build with run_server.py as the entry point). Day-to-day installs do not need them.