Settings

The UNS Settings page lets you configure the two core infrastructure components that power the Unified Namespace: the Storage Backend that persists topics and time-series data, and the MQTT Broker that handles real-time message distribution. Both components ship with sensible embedded defaults so the system works out of the box, and both can be switched to external, production-grade alternatives at any time — without restarting the application.

Open the settings page from System Management > UNS tab.

tip

Zero-configuration start: MaestroHub starts with an embedded Pebble database and an embedded MQTT broker by default. You can begin ingesting and exploring data immediately and upgrade to external infrastructure later when your scale or availability requirements grow.

Operational Status

The top of the page shows a live health summary of both components. Three cards indicate the Overall Health, the Storage backend type and connection state, and the MQTT Broker mode and connection state. Use this bar to verify that a configuration change took effect or to spot connectivity issues at a glance.

Live health summary for storage and broker components.

Storage Backend

The Storage Backend determines where UNS topics and historical data records are persisted. Choose a backend from the Storage Type dropdown and click Save Storage to apply the change.

Storage Backend configuration with the default Pebble (Embedded) option selected.

Pebble (Embedded) — Default

Pebble is the default storage backend. It uses an embedded key-value database (CockroachDB Pebble) for time-series data and a local SQLite file for metadata such as topics, schemas, and dashboards. No external database is required.

Field	Description	Default
Database Path	Directory where time-series data files are stored	./data/unsdata
Metadata Path	Path to the SQLite metadata file	./data/uns.db
Retention	How long historical data is kept before automatic cleanup	24h0m0s

Pebble settings are managed through the application configuration file and are shown here as read-only. To change Pebble paths or retention you must update the config file and restart the application.

info

Pebble is ideal for single-node deployments, edge gateways, or evaluation environments where simplicity and fast startup matter more than horizontal scalability.

TimescaleDB (External)

TimescaleDB is a PostgreSQL extension purpose-built for time-series workloads. Select TimescaleDB from the Storage Type dropdown to connect to an external database instance.

Field	Description	Default
Host	Hostname or IP address of the TimescaleDB server	—
Port	TCP port	5432
Database	Database name	—
Username	Database user	—
Password	Database password (stored encrypted)	—
SSL Mode	Connection encryption — disable or require	disable
Chunk Time Interval	Hypertable chunk size — 1 day, 3 days, or 7 days	1 day
Retention Policy	Automatic data expiry — 1 day, 3 days, 7 days, or empty (keep forever)	7 days
Partition Strategy	How hypertables are partitioned — time or time_topic	time

Click Test Connection before saving to verify that the application can reach the database with the provided credentials. The test reports success or failure along with the measured latency.

info

TimescaleDB is recommended for production environments that require high-volume ingestion, long retention windows, SQL-based analytics, or high-availability configurations.

Changing Partition Strategy

Switching the partition strategy on an existing TimescaleDB deployment may require a data migration. Click Migrate Partition Strategy to open the migration dialog which will run a preflight check, report the number of affected records, and let you choose between preserving existing data or starting fresh.

MQTT Broker

The MQTT Broker is the messaging backbone of the UNS. Every data point published by connectors, pipelines, or external clients passes through the broker before reaching subscribers such as Data Explorer, dashboards, or downstream systems. Choose a mode from the Broker Mode dropdown and click Save Broker to apply.

MQTT Broker configuration with the default Embedded Broker option selected.

Embedded Broker — Default

MaestroHub ships with a built-in MQTT broker (Mochi-MQTT). It runs inside the application process and requires no external infrastructure.

Field	Description	Default
Bind Address	Network interface the broker listens on	0.0.0.0 (all interfaces)
TCP Port	MQTT listener port	1883

Read-Only Credentials

The embedded broker exposes a set of read-only credentials that you can share with external MQTT clients (dashboards, third-party tools, custom scripts). Clients that connect with these credentials can subscribe to UNS topics but cannot publish — this protects the namespace from accidental writes by external consumers.

Field	Description	Default
Username	Read-only username	uns_reader
Password	Auto-generated password (click the eye icon to reveal)	Auto-generated on first start

info

The embedded broker is ideal for single-node deployments and development environments. It starts automatically with zero configuration and supports all UNS features including retained messages, schema distribution, and real-time subscriptions.

External Broker

For production environments that require clustering, advanced access control, or integration with an existing MQTT infrastructure, select External Broker to connect to a remote broker such as EMQX or Mosquitto.

Field	Description	Default
Host	Hostname or IP of the external broker	—
Port	TCP port	1883
Client ID	Prefix for the MQTT client identifier (a unique suffix is appended automatically)	—
Username	Broker authentication username	—
Password	Broker authentication password (stored encrypted)	—

TLS Configuration

Enable TLS to encrypt the connection between MaestroHub and the external broker. When TLS is enabled the following fields become available:

Field	Description
CA Certificate	PEM-encoded certificate authority certificate
Client Certificate	PEM-encoded client certificate for mutual TLS
Client Key	PEM-encoded client private key (stored encrypted)
Insecure Skip Verify	Skip server certificate validation (not recommended for production)

Click Test Connection before saving to verify that MaestroHub can reach the external broker and authenticate successfully.

Hot-Swap: Switching Without Downtime

Both the storage backend and the MQTT broker support hot-swap — you can change the active component while the application is running without restarting or losing in-flight data.

How Storage Hot-Swap Works

1. The new backend connection is validated.
2. Active read and write operations are drained (the system waits up to 30 seconds for running operations to complete).
3. The active repositories are atomically swapped to the new backend.
4. The old backend is closed in the background.

Because storage switches may involve large amounts of data, the operation runs asynchronously. The Operational Status bar shows a switching indicator while the process is in progress. Once complete, the last switch result — including the number of migrated topics and records — is available in the status panel.

How Broker Hot-Swap Works

1. The new broker connection is validated.
2. All current topic subscriptions are captured.
3. The new broker is started.
4. Subscriptions are automatically re-established on the new broker.
5. The old broker is stopped.

Broker switches are synchronous and typically complete in a few seconds. After the switch, all live Data Explorer sessions and dashboard panels reconnect to the new broker automatically.

warning

During a storage hot-swap there is a brief window where write operations are paused while the swap completes. Plan storage migrations during low-traffic periods if possible.

Settings Persistence and Startup Behaviour

When you save settings through the UI, they are persisted to the application database. On subsequent startups the application loads these saved settings instead of the initial environment variables or configuration file values.

This means:

• First start — the application uses values from environment variables and the configuration file (e.g. config.yaml).
• After a UI save — the saved settings take precedence. Changes to environment variables or the config file for storage type and broker mode will have no effect unless the database settings are cleared.

This design ensures that infrastructure changes made through the UI survive restarts without requiring manual config file edits. If you need to reset to the original config-file values, clear the saved settings from the database and restart the application.

warning

If you change an environment variable or config file entry after settings have been saved through the UI, the config file change will be ignored. The UI-saved settings always take priority.