Getting Started

60 seconds — that's all it takes to launch UMH-Core.

No kubectl, no Kubernetes setup, just a single Docker container. Anything that runs Docker works — from your MacBook terminal to enterprise edge boxes.

System requirements

Minimum:

• 2 vCPU

• 4 GB RAM

• 40 GB SSD

See also Sizing Guide for more information

Connecting to the Management Console (recommended)

1. Sign up at https://management.umh.app and create an Instance.

2. Copy the autogenerated one-liner docker run command (it already embeds your API token).

3. Run that script on the target machine.

From the Console you can :

• Control - start, stop, edit and version control

• Monitor - get access to state (active, idle, degraded, degraded_connection, etc.), logs and metrics

• Browse - watch real-time tags in the Topic Browser.

+ compliance features such as SSO, RBAC, 2FA, audit trails and more.

Quick start (CLI-only)

1. Create a working directory

   mkdir umh && cd umh

2. Write a minimal config.yaml

   agent:
     location: 
       0: "plant-A"
       1: "line-4"
   
   protocolConverter:
     - name: vibration-sensor-pc
       desiredState: active
       protocolConverterServiceConfig:
         location:
           2: "machine-7"
         template:
           connection:
             nmap:
               target:   "{{ .HOST }}"
               port:     "{{ .PORT }}"
           dataflowcomponent_read:
             benthos:
               input:
                 generate:
                     count: 0
                     interval: 1s
                     mapping: |
                         root = random_int(min:10, max:20)
               pipeline:
                 processors:
                     - tag_processor:
                         defaults: |
                           msg.meta.location_path = "{{ .location_path }}"; // auto-generated path from agent and protocol converter location
                           msg.meta.data_contract = "_raw"; // Use _raw for now
                           msg.meta.tag_name      = "random_int"; // Your tag name 
                           return msg;
         variables:
           HOST:   "localhost"
           PORT: "8080"   

3. Run the container

   sudo docker run -d --restart unless-stopped \
        --name umh-core -v $(pwd):/data \
        management.umh.app/oci/united-manufacturing-hub/umh-core:latest

Note for UMH Classic users: the former Helm/Kubernetes installation is no longer required. UMH Core ships as a single container; Kubernetes is purely optional if you need scaling or HA.

1. Watch it work

   Open the Topic Browser in the console; you should see random_int under plant-A.line-4.machine-7._raw.random_int

Quick troubleshooting

SELinux volume permissions On RHEL, Rocky, or other SELinux-enabled systems, append :z to the volume mount so Docker can relabel the directory:

-v "$(pwd)/umh-core-data:/data:z"

If you omit this, you might see chmod: /data/config.yaml: no such file or directory and the container fails to start.

TLS interception If your corporate network intercepts TLS traffic, follow the steps in Corporate Firewalls to add your CA certificate or, as a last resort, set allowInsecureTLS: true in config.yaml.

Migration from UMH Classic

UMH Classic users: See Migration from UMH Classic to UMH Core for complete migration instructions including data contract changes and configuration updates.

Next steps

• Add a real producer – point an OPC UA input at your PLC and let the tag_processor contextualize your data. See Producing Data 🚧 for examples.
• Add a consumer – create a second protocol converter that reads from umh.v1.plant-A.lineA.machine-7._raw.random_int and writes to MQTT or TimescaleDB. See Consuming Data 🚧 for patterns.
• Structure your data – move beyond _raw contracts to explicit Data Models 🚧 for enterprise-scale analytics.
• Scale your deployment – follow the Production guides for sizing, security, and monitoring.

Understanding the Configuration

The example above shows:

• protocolConverter: - Creates a Bridge (UI terminology) for device connectivity

• tag_processor 🚧 - Adds UNS metadata for proper topic construction (will be updated in next release to align with new data model)

• Location hierarchy - Combines agent.location + protocolConverter.location for hierarchical paths (supports ISA-95, KKS, or custom naming)

• Data contracts - _raw is the simplest contract for unprocessed data

For complete configuration syntax, see Configuration Reference.

Learn More

Core Concepts

• Unified Namespace Overview - Understand the messaging architecture
• Topic Convention - How UNS addresses data
• Payload Formats - Message structure standards

Educational Content

• The Rise of the Unified Namespace - Core UNS principles
• Industrial IoT Platforms vs. The Unified Namespace - Architectural comparison
• Connect ifm IO-Link Masters - Real-world connectivity example

Technical Deep Dives

• Why Most Manufacturing Software Sucks - UMH's architectural philosophy
• Benthos-UMH Documentation - Complete protocol and processor reference