openremote - Moses Yebei

The Problem

Managing IoT devices at scale means juggling device connectivity, rule automation, user access, and data visualization—usually with a patchwork of separate tools. OpenRemote addresses this by bundling device management, protocol agents (MQTT, HTTP, and others), rule engines, multi-tenant access control, and a dashboard builder into one platform.

What This Does

This is a fork of the openremote/openremote project (1,875 stars upstream) and appears to be a near-complete copy with no local modifications visible in the file structure. The codebase is a monorepo containing eight self-contained projects, not a single application. The core Java backend lives in manager/ (171 files), with protocol agents in agent/ (493 files) and data models in model/ (399 files). The TypeScript frontend occupies ui/ (713 files) and includes a rules flow editor, map components, and a dashboard builder.

The system supports multi-tenancy via "realms," device auto-provisioning, and rule automation through visual flows, JavaScript, and Groovy. Deployment is container-first: docker-compose.yml at the root and deployment/Dockerfile handle the standard stack, while kubernetes/ (65 files) provides orchestration manifests.

How It Is Wired

The backend entry point is manager/src/main/java/org/openremote/manager/Main.java. The frontend has two entry points: ui/app/manager/src/index.ts and ui/app/insights/src/index.ts. The system is designed to run as Docker containers—the quickstart in the README pulls prebuilt images and runs docker compose up, which is the primary deployment path.

The static analysis mapped 391 internal modules with 588 import edges. The most connected frontend modules are ui/component/or-vaadin-components/src/util.ts and ui/component/storybook-utils.js, each with 25 modules depending on them—changes there have a wide blast radius. The ui/component/or-rules module has 110 modules inside circular dependencies, which makes refactoring the rules editor costly. The backend wiring has not been mapped in this analysis.

How To Use It

Setup: Requires Docker Desktop (v18+). Clone with git clone https://github.com/moses-y/openremote.

Running it: Download the compose file and start the stack:

docker compose pull
docker compose -p openremote up

Access the manager UI at https://localhost (accept the self-signed certificate). Default credentials are admin / secret. To change the host, set OR_HOSTNAME (e.g., OR_HOSTNAME=192.168.1.1 docker-compose -p openremote up -d).

Development: The repo uses Gradle for Java builds and Yarn for the UI. The README references IDE setup and UI development guides but does not document local build commands.

Real-World Use

A city operations team deploys OpenRemote to manage smart streetlights. They connect devices via the MQTT agent, define "when-then" rules in the flow editor to trigger maintenance alerts, organize assets by district using realms for multi-tenant access, and build a public dashboard in ui/app/insights to show live energy consumption.

Code Health & Issues

Static analysis found 407 findings (206 high, 180 medium, 21 low) across five categories: import cycle members (20), deep nesting (24), oversized files (4), high branching density (3), and hub modules (9). The most significant are concentrated in ui/component/or-rules and ui/component/or-mwc-components/src/or-mwc-input.ts (1,067 lines). These are frontend maintainability concerns, not runtime defects.

The code health audit found two high-severity issues:

High — Committed .env file at .ci_cd/env/.env. A tracked .env risks leaking live credentials. Remove it from tracking, rotate what it holds, and commit a .env.example.
High — continue-on-error on a correctness step in .github/workflows/ci_cd.yml (line 661), which can report a green check for a failing test suite.

Medium issues include missing GITHUB_TOKEN least-privilege permissions in three workflows, an unpinned alpine:latest base image in deployment/Dockerfile, no pre-commit secret gate, a 15.5MB devices.csv in test/load1/deployment3/, and persist-credentials not disabled in CI checkout. The repo has tests (335 files), CI, a license, and a lockfile.

The Bottom Line

OpenRemote is a mature, feature-complete IoT platform with a solid containerized deployment story. The codebase is large and the frontend has real maintainability debt, but for a team needing a self-hosted IoT platform with multi-tenancy and rule automation, it is a credible foundation. The fork itself adds no evident value over the upstream project—use the original unless this fork contains specific fixes you need.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

2,313 files

Java1028
TypeScript375
YAML144
JSON114
Protocol Buffers81
Markdown55

ReactDockerKubernetes

Module dependencies

The 10 most depended-upon modules of 391, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_r_vaadin_components_src_util["util"] n1_ui_component_storybook_utils["storybook-utils"] n2_iewer_components_flow_editor["flow-editor"] n3_n_viewer_or_rule_json_viewer["or-rule-json-viewer"] n4_der_src_util_widget_settings["widget-settings"] n5_component_or_rules_src_index["index"] n6_d_builder_src_util_or_widget["or-widget"] n7_der_src_util_or_asset_widget["or-asset-widget"] n8_ilder_src_util_widget_config["widget-config"] n9__viewer_node_structure_index["index"] n7_der_src_util_or_asset_widget --> n6_d_builder_src_util_or_widget n7_der_src_util_or_asset_widget --> n4_der_src_util_widget_settings n6_d_builder_src_util_or_widget --> n8_ilder_src_util_widget_config n6_d_builder_src_util_or_widget --> n4_der_src_util_widget_settings n4_der_src_util_widget_settings --> n8_ilder_src_util_widget_config n2_iewer_components_flow_editor --> n5_component_or_rules_src_index n2_iewer_components_flow_editor --> n9__viewer_node_structure_index n3_n_viewer_or_rule_json_viewer --> n5_component_or_rules_src_index classDef cyc stroke:#ef4444,stroke-width:2px; class n2_iewer_components_flow_editor,n3_n_viewer_or_rule_json_viewer,n5_component_or_rules_src_index cyc;

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them .ci_cd/env/.env, agent/src/main/proto/tts/ttn/lorawan/v3/secrets.proto, setup/src/load1/resources/org/openremote/setup/load1/ca.pem

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low1

Remove the committed .env and rotate what it holdshigh

.ci_cd/env/.env

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/ci_cd.yml

line 661 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/build-deployment-image.yml

3 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium

deployment/Dockerfile

alpine:latest (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Move large binaries to Git LFS or out of the repositorymedium

test/load1/deployment3/devices.csv

1 blobs over 5MB: devices.csv 15.5MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci_cd.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/deployment.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.