Configuration

MaestroHub Lite can be configured using a YAML configuration file, environment variables, or a combination of both.

Configuration File

MaestroHub Lite ships with a bundled config.yaml that covers the most common settings pre-filled with their default values. You can use this file as a starting point and adjust the sections relevant to your deployment. For a full list of available fields, see the reference tables below.

At startup, MaestroHub Lite looks for a config.yaml in the same directory as the binary. To use a different location, pass the --config flag:

maestrohub-lite --config /path/to/config.yaml

Environment Variables

Every configuration key can be set via an environment variable using the MAESTROHUB_ prefix. The dotted YAML path is converted to uppercase with dots replaced by underscores:

• http.port → MAESTROHUB_HTTP_PORT
• modules.auth.jwt.accessSecret → MAESTROHUB_MODULES_AUTH_JWT_ACCESSSECRET

Precedence

When the same setting is defined in multiple places, the following precedence applies (highest to lowest):

1. Environment variables
2. Configuration file
3. Built-in defaults

Reference

The tables below list every configuration field grouped by section.

http

Configures the built-in HTTP server that serves the API and UI.

Key	Type	Default	Description
host	string	localhost	The network address to listen on.
port	int	8080	The TCP port to listen on.
readTimeout	duration	30s	The maximum duration for reading an entire request including the body.
writeTimeout	duration	30s	The maximum duration for writing a response.
shutdownTimeout	duration	30s	The maximum duration to wait for in-flight requests during graceful shutdown.
corsOrigins	[]string	[*]	The list of allowed origins for cross-origin requests. Use "*" to allow all.

Default YAML example

http:
  host: localhost
  port: 8080
  readTimeout: 30s
  writeTimeout: 30s
  shutdownTimeout: 30s
  corsOrigins: [*]

infrastructure

Configures connections to external services such as NATS. These connections are created once at startup and shared across all components.

Key	Type	Default	Description
enabled	bool	false	Activates external infrastructure connections. When disabled, all components fall back to local in-memory implementations.
nats.url	string	nats://localhost:4222	The NATS server address.
nats.username	string	""	For NATS authentication.
nats.password	string	""	For NATS authentication.
nats.name	string	maestrohub-lite	The client name sent to the NATS server for identification.
nats.maxReconnects	int	-1	The maximum number of reconnection attempts. Use -1 for unlimited.
nats.reconnectWait	duration	2s	The delay between reconnection attempts.

Default YAML example

infrastructure:
  enabled: false
  nats:
    url: nats://localhost:4222
    username: ""
    password: ""
    name: maestrohub-lite
    maxReconnects: -1
    reconnectWait: 2s

messenger

Configures the internal messaging layer used for request-reply communication between components.

Key	Type	Default	Description
type	string	local	Selects the messenger backend: local for in-memory or nats for distributed.
nats.queueGroup	string	maestrohub	The NATS queue group name for load balancing across replicas.
nats.requestTimeout	duration	30s	The maximum duration to wait for a reply.

Default YAML example

messenger:
  type: local
  nats:
    queueGroup: maestrohub
    requestTimeout: 30s

eventbus

Configures the event bus used for publishing and subscribing to domain events across components.

Key	Type	Default	Description
enabled	bool	true	Activates the event bus.
type	string	local	Selects the event bus backend: local for in-memory or nats for distributed.
nats.serviceName	string	maestrohub	The prefix used for NATS JetStream stream naming.
nats.handlerTimeout	duration	5s	The maximum duration allowed for a single event handler execution.
local.bufferSize	int	10000	The capacity of the internal event queue.
local.maxWorkers	int	100	The maximum number of concurrent event handler goroutines.
local.handlerTimeout	duration	20s	The maximum duration allowed for a single event handler execution.

Default YAML example

eventbus:
  enabled: true
  type: local
  nats:
    serviceName: maestrohub
    handlerTimeout: 5s
  local:
    bufferSize: 10000
    maxWorkers: 100
    handlerTimeout: 20s

coordination

Configures distributed coordination for multi-replica deployments, including leader election. Only needed when running more than one instance.

Key	Type	Default	Description
enabled	bool	false	Activates distributed coordination.
type	string	local	Selects the coordination backend: local for single-instance or nats for distributed.
nats.bucket	string	coordination	The NATS KV bucket name used for coordination state.
nats.replicaId	string	maestrohub-lite	The unique identifier for this replica in the cluster.
nats.leaderTtl	duration	30s	How long a leader lease is valid before it must be renewed.
nats.leaderRenewInterval	duration	10s	How often the current leader renews its lease.

Default YAML example

coordination:
  enabled: false
  type: local
  nats:
    bucket: coordination
    replicaId: maestrohub-lite
    leaderTtl: 30s
    leaderRenewInterval: 10s

metrics

Configures application metrics collection and export.

Key	Type	Default	Description
enabled	bool	true	Activates metrics collection.
mode	string	prometheus	Selects the metrics backend: prometheus.
prometheus.namespace	string	maestrohub	The prefix added to all exported metric names.

Default YAML example

metrics:
  enabled: true
  mode: prometheus
  prometheus:
    namespace: maestrohub

queue

Configures the execution queue used for pipeline processing.

Key	Type	Default	Description
type	string	local	Selects the queue backend: local for in-memory.
local.workerCount	int	100	The number of concurrent workers processing queued pipelines.
local.pollInterval	duration	10ms	How often idle workers check for new work.
local.handlerTimeout	duration	5m	The maximum execution time allowed per pipeline run.

Default YAML example

queue:
  type: local
  local:
    workerCount: 100
    pollInterval: 10ms
    handlerTimeout: 5m

logging

Configures structured logging output including console, database, and file destinations.

Key	Type	Default	Description
level	string	info	Sets the minimum log level: debug, info, warn, error
console.enabled	bool	true	Controls whether logs are written to stdout
console.json	bool	false	Outputs logs as JSON instead of human-readable format. Enable when logs are parsed by external collectors (Fluentd, ELK).
database.type	string	sqlite	Selects the database storage type: sqlite or disabled.
database.enabled	bool	true	Controls whether logs are stored in a local database. Set true for standalone deployments, false when using external collectors. Ignored when Type is "memory".
database.path	string	./data/logs.db	To the SQLite database file
database.table	string	logs	The database table name for storing log entries.
database.bufferSize	int	1024	The number of log entries to buffer before flushing to the database.
database.retentionDuration	duration	24h	How long to keep logs before automatic cleanup.
file.enabled	bool	false	Controls whether logs are written to a file
file.path	string	""	To the log file
file.maxSizeMB	int	0	The maximum log file size in megabytes before rotation.
file.maxBackups	int	0	The number of rotated log files to retain.
file.maxAgeDays	int	0	The maximum number of days to retain rotated log files.
file.compress	bool	false	Enables gzip compression of rotated files
fields	map[string]string	{}	Key-value pairs added to every log entry

Default YAML example

logging:
  level: info
  console:
    enabled: true
    json: false
  database:
    type: sqlite
    enabled: true
    path: ./data/logs.db
    table: logs
    bufferSize: 1024
    retentionDuration: 24h
  file:
    enabled: false
    path: ""
    maxSizeMB: 0
    maxBackups: 0
    maxAgeDays: 0
    compress: false
  fields: {}

ui

Controls whether the embedded web UI is served alongside the API.

Key	Type	Default	Description
enabled	bool	true	Activates the embedded web UI.

Default YAML example

ui:
  enabled: true

mcp

Configures the Model Context Protocol (MCP) server endpoint.

Key	Type	Default	Description
enabled	bool	true	Activates the MCP endpoint.
path	string	/mcp	The HTTP path where the MCP endpoint is served.

Default YAML example

mcp:
  enabled: true
  path: /mcp

modules.auth

Configures authentication including JWT tokens, password policies, and user storage.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or postgres.
sqlite.path	string	./data/auth.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.
jwt.accessSecret	string	""	The secret key for signing access tokens. Required.
jwt.refreshSecret	string	""	The secret key for signing refresh tokens. Required.
jwt.passwordResetSecret	string	""	The secret key for signing password reset tokens. Required.
jwt.accessTokenDuration	duration	15m	The lifetime of access tokens.
jwt.refreshTokenDuration	duration	24h	The lifetime of refresh tokens.
jwt.rememberMeRefreshDuration	duration	168h	The extended lifetime when "remember me" is enabled.
jwt.passwordResetDuration	duration	30m	The lifetime of password reset tokens.
password.minLength	int	8	The minimum password length required.
password.bcryptCost	int	12	The cost factor for bcrypt hashing (higher = more secure but slower).
password.requireUppercase	bool	true	Requires at least one uppercase letter.
password.requireLowercase	bool	true	Requires at least one lowercase letter.
password.requireNumber	bool	true	Requires at least one digit.
password.requireSpecial	bool	false	Requires at least one special character.
authorization.enableAudit	bool	true	Enables logging of authorization decisions.
authorization.cachePermissions	bool	true	Enables caching of user permissions.
authorization.cacheTTL	duration	5m	The time-to-live for cached permissions.
authorization.defaultDenyMessage	string	Access denied: insufficient permissions	The message shown when access is denied.
oidc.enabled	bool	true	Determines whether OIDC authentication is active.
ldap.enabled	bool	true	Determines whether LDAP authentication is active.
saml.enabled	bool	true	Determines whether SAML authentication is active.
passwordResetURL	string	""	The base URL for password reset links.

Default YAML example

modules:
  auth:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/auth.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5
    jwt:
      accessSecret: ""
      refreshSecret: ""
      passwordResetSecret: ""
      accessTokenDuration: 15m
      refreshTokenDuration: 24h
      rememberMeRefreshDuration: 168h
      passwordResetDuration: 30m
    password:
      minLength: 8
      bcryptCost: 12
      requireUppercase: true
      requireLowercase: true
      requireNumber: true
      requireSpecial: false
    authorization:
      enableAudit: true
      cachePermissions: true
      cacheTTL: 5m
      defaultDenyMessage: Access denied: insufficient permissions
    oidc:
      enabled: true
    ldap:
      enabled: true
    saml:
      enabled: true
    passwordResetURL: ""

modules.authz

Configures role-based access control (RBAC) and permission storage.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or postgres.
sqlite.path	string	./data/authz.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.
modelType	string	default	Determines which Casbin model to use: default, ownership, or simple.
initializeBuiltInRoles	bool	true	Creates built-in roles on startup.

Default YAML example

modules:
  authz:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/authz.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5
    modelType: default
    initializeBuiltInRoles: true

modules.oauth2

Configures OAuth2 and OpenID Connect (OIDC) authentication providers.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
issuer	string	""	The OAuth2/OIDC issuer URL.
secret	string	""	The fosite system secret for HMAC operations (must be 32+ bytes).
storageType	string	sqlite	Selects the storage backend: sqlite.
sqlite.path	string	./data/oauth2.db	The path to the SQLite database file.
accessTokenTTL	duration	1h	The lifetime of access tokens.
refreshTokenTTL	duration	24h	The lifetime of refresh tokens.
authCodeTTL	duration	10m	The lifetime of authorization codes.

Default YAML example

modules:
  oauth2:
    enabled: true
    issuer: ""
    secret: ""
    storageType: sqlite
    sqlite:
      path: ./data/oauth2.db
    accessTokenTTL: 1h
    refreshTokenTTL: 24h
    authCodeTTL: 10m

modules.connectors

Configures connector management and storage for external system integrations.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or postgres.
sqlite.path	string	./data/connectors.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.
encryptionKey	string	""	The AES key for encrypting connection secrets at rest. Required. Must be exactly 16, 24, or 32 bytes (for AES-128, AES-192, or AES-256).
runtimeEnabled	bool	true	Controls whether connection runtime management is active
autoStartConnections	bool	true	Controls whether connections auto-start on module init
ownershipEnabled	bool	false	Controls whether ownership checking is enforced. When false, all connections run on all replicas (single-binary mode). When true, exclusive connections are coordinated via the OwnershipManager.

Default YAML example

modules:
  connectors:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/connectors.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5
    encryptionKey: ""
    runtimeEnabled: true
    autoStartConnections: true
    ownershipEnabled: false

modules.dependencies

Configures dependency tracking between resources.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or postgres.
sqlite.path	string	./data/dependencies.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.

Default YAML example

modules:
  dependencies:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/dependencies.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5

modules.email

Configures the email notification service and template storage.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or postgres.
sqlite.path	string	./data/email.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.

Default YAML example

modules:
  email:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/email.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5

modules.license

Configures license management and enforcement.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or postgres.
sqlite.path	string	./data/license.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.

Default YAML example

modules:
  license:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/license.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5

modules.logs

Configures structured log collection and storage for pipeline execution and system events.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
provider	string	sqlite	Specifies which log provider to use: memory, sqlite, postgres, or elasticsearch
sqlite.path	string	./data/logs.db	The path to the SQLite database file
sqlite.tableName	string	logs	The name of the logs table.
sqlite.maxLogsWindow	int	10000	The maximum result window for pagination.
postgres.host	string	localhost	The database server hostname
postgres.port	int	5432	The database server port
postgres.database	string	maestrohub_logs	The database name
postgres.username	string	postgres	The database user
postgres.password	string	""	The database password
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full)
postgres.maxOpenConns	int	10	The maximum number of open connections
postgres.maxIdleConns	int	5	The maximum number of idle connections
postgres.tableName	string	logs	The name of the logs table.
postgres.maxLogsWindow	int	10000	The maximum result window for pagination.
elasticsearch.url	string	http://localhost:9200	The Elasticsearch server URL
elasticsearch.indexPattern	string	logs-*	The pattern for log indices (e.g., "logs-*")
elasticsearch.username	string	""	For authentication (optional)
elasticsearch.password	string	""	For authentication (optional)
elasticsearch.apiKey	string	""	For authentication (optional, alternative to username/password)
elasticsearch.tlsSkipVerify	bool	false	Skips TLS certificate verification (not recommended for production)

Default YAML example

modules:
  logs:
    enabled: true
    provider: sqlite
    sqlite:
      path: ./data/logs.db
      tableName: logs
      maxLogsWindow: 10000
    postgres:
      host: localhost
      port: 5432
      database: maestrohub_logs
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5
      tableName: logs
      maxLogsWindow: 10000
    elasticsearch:
      url: http://localhost:9200
      indexPattern: logs-*
      username: ""
      password: ""
      apiKey: ""
      tlsSkipVerify: false

modules.organizations

Configures multi-tenant organization management.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or postgres.
sqlite.path	string	./data/organizations.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.

Default YAML example

modules:
  organizations:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/organizations.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5

modules.phonehome

Configures anonymous usage telemetry reporting.

Key	Type	Default	Description
enabled	bool	true	Activates this module.

Default YAML example

modules:
  phonehome:
    enabled: true

modules.pipelineEngine

Configures the pipeline execution engine and run history storage.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite, postgres, or memory.
sqlite.path	string	./data/pipeline.db	The path to the SQLite database file.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.
executionRepository.type	string	sqlite	Selects the execution repository backend: memory or sqlite.
executionRepository.memory.maxItems	int	10000	The maximum number of executions to keep. When the limit is reached, the oldest completed/failed executions are evicted. Set to 0 for unlimited.
executionRepository.sqlite.path	string	./data/execution.db	The path to the SQLite database file for execution history.
executionRepository.sqlite.retention	duration	24h	The duration to retain execution history. Executions older than this will be automatically deleted. Set to 0 for unlimited retention.

Default YAML example

modules:
  pipelineEngine:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/pipeline.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5
    executionRepository:
      type: sqlite
      memory:
        maxItems: 10000
      sqlite:
        path: ./data/execution.db
        retention: 24h

modules.scheduler

Configures the cron-based pipeline scheduler.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
replicaId	string	maestrohub-lite	The unique identifier for this scheduler instance. Used for leader election (distributed mode) and execution request tracking. Falls back to hostname if not specified.

Default YAML example

modules:
  scheduler:
    enabled: true
    replicaId: maestrohub-lite

modules.universalSearch

Configures full-text search across all resources.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storageType	string	sqlite	Selects the storage backend: sqlite or elasticsearch.
sqlite.path	string	./data/search.db	The path to the SQLite database file. Use ":memory:" for an in-memory database.
sqlite.walMode	bool	false	Enables Write-Ahead Logging for better concurrency.
postgres.host	string	localhost	The database server hostname.
postgres.port	int	5432	The database server port.
postgres.database	string	maestrohub	The database name.
postgres.username	string	postgres	The database user.
postgres.password	string	""	The database password.
postgres.sslMode	string	disable	The SSL mode (disable, require, verify-ca, verify-full).
postgres.maxOpenConns	int	10	The maximum number of open connections.
postgres.maxIdleConns	int	5	The maximum number of idle connections.
elasticsearch.urls	[]string	[http://localhost:9200]	A list of Elasticsearch node URLs. Example: ["http://localhost:9200"]
elasticsearch.index	string	maestrohub_search	The name of the Elasticsearch index to use.
elasticsearch.username	string	""	For basic authentication (optional).
elasticsearch.password	string	""	For basic authentication (optional).
elasticsearch.apiKey	string	""	For API key authentication (optional, alternative to username/password).
elasticsearch.cloudId	string	""	For Elastic Cloud deployments (optional).
elasticsearch.tls.enabled	bool	false	Determines whether TLS is enabled.
elasticsearch.tls.insecureSkipVerify	bool	false	Skips certificate verification (not recommended for production).
elasticsearch.tls.caCertPath	string	""	The path to the CA certificate file.
elasticsearch.tls.certPath	string	""	The path to the client certificate file.
elasticsearch.tls.keyPath	string	""	The path to the client key file.

Default YAML example

modules:
  universalSearch:
    enabled: true
    storageType: sqlite
    sqlite:
      path: ./data/search.db
      walMode: false
    postgres:
      host: localhost
      port: 5432
      database: maestrohub
      username: postgres
      password: ""
      sslMode: disable
      maxOpenConns: 10
      maxIdleConns: 5
    elasticsearch:
      urls: [http://localhost:9200]
      index: maestrohub_search
      username: ""
      password: ""
      apiKey: ""
      cloudId: ""
      tls:
        enabled: false
        insecureSkipVerify: false
        caCertPath: ""
        certPath: ""
        keyPath: ""

modules.uns

Configures the Unified Namespace for real-time data collection via MQTT and OPC UA.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
storage.type	string	pebble	Selects the storage backend: memory, timescale, or pebble.
storage.timescale.host	string	localhost	The database server hostname.
storage.timescale.port	int	5432	The database server port.
storage.timescale.database	string	uns	The database name.
storage.timescale.username	string	""	For authentication.
storage.timescale.password	string	""	For authentication.
storage.timescale.sslMode	string	disable	The SSL mode: disable, require
storage.timescale.maxOpenConns	int	50	The maximum number of open connections in the pool.
storage.timescale.chunkTimeInterval	string	1 day	The time interval for hypertable chunks. Valid values: 1 day, 3 days, 7 days
storage.timescale.retentionPolicy	string	7 days	The data retention period. Valid values: 1 day, 3 days, 7 days, `` (no retention)
storage.timescale.partitionStrategy	string	time	Determines how data is partitioned. Valid values: time (partition by time only), time_topic (partition by time and topic)
storage.pebble.path	string	data/unsdata	The directory path for PebbleDB data storage.
storage.pebble.metadataPath	string	data/uns.db	The directory path for SQLite metadata storage.
storage.pebble.retention	duration	24h	The data retention duration.
mqtt.mode	string	embedded	Selects the MQTT mode: embedded, external, or disabled.
mqtt.embedded.tcpPort	int	1883	The TCP listener port for MQTT connections.
mqtt.embedded.host	string	0.0.0.0	The address to bind to.
mqtt.embedded.auth.enabled	bool	false	Determines whether authentication is required.
mqtt.embedded.auth.username	string	""	For authentication.
mqtt.embedded.auth.password	string	""	For authentication.
mqtt.embedded.auth.allowAnonymous	bool	false	Allows connections without credentials when auth is enabled.
mqtt.external.url	string	tcp://localhost:1883	The broker connection URL. Examples: "tcp://broker:1883", "ssl://broker:8883", "ws://broker:8083/mqtt"
mqtt.external.clientId	string	""	The MQTT client ID.
mqtt.external.username	string	""	For authentication (optional).
mqtt.external.password	string	""	For authentication (optional).
mqtt.external.tls.enabled	bool	false	Determines whether TLS is enabled.
mqtt.external.tls.insecureSkipVerify	bool	false	Skips certificate verification (not recommended for production).
mqtt.external.tls.caCertPath	string	""	The path to the CA certificate file.
mqtt.external.tls.certPath	string	""	The path to the client certificate file.
mqtt.external.tls.keyPath	string	""	The path to the client key file.
mqtt.external.keepAlive	int	60	The keep-alive interval in seconds.
mqtt.external.cleanSession	bool	true	Determines whether to start a clean session.
mqtt.external.autoReconnect	bool	true	Enables automatic reconnection.
encryptionKey	string	""	The AES key for encrypting sensitive fields at rest. Required. Must be exactly 16, 24, or 32 bytes (for AES-128, AES-192, or AES-256).

Default YAML example

modules:
  uns:
    enabled: true
    storage:
      type: pebble
      timescale:
        host: localhost
        port: 5432
        database: uns
        username: ""
        password: ""
        sslMode: disable
        maxOpenConns: 50
        chunkTimeInterval: 1 day
        retentionPolicy: 7 days
        partitionStrategy: time
      pebble:
        path: data/unsdata
        metadataPath: data/uns.db
        retention: 24h
    mqtt:
      mode: embedded
      embedded:
        tcpPort: 1883
        host: 0.0.0.0
        auth:
          enabled: false
          username: ""
          password: ""
          allowAnonymous: false
      external:
        url: tcp://localhost:1883
        clientId: ""
        username: ""
        password: ""
        tls:
          enabled: false
          insecureSkipVerify: false
          caCertPath: ""
          certPath: ""
          keyPath: ""
        keepAlive: 60
        cleanSession: true
        autoReconnect: true
    encryptionKey: ""

modules.websocket

Configures WebSocket support for real-time client notifications and live updates.

Key	Type	Default	Description
enabled	bool	true	Activates this module.
writeWait	duration	10s	The time allowed to write a message to the peer.
pongWait	duration	1m	The time allowed to read the next pong message from the peer.
pingPeriod	duration	54s	The interval for sending ping messages.
maxMessageSize	int64	65536	The maximum size in bytes of incoming messages.
sendChannelBuffer	int	256	The buffer size for the send channel.
readBufferSize	int	4096	The size of the read buffer for WebSocket connections.
writeBufferSize	int	16384	The size of the write buffer for WebSocket connections.
enableSmartSubscriptions	bool	true	Enables subscribing to EventBus only when clients are interested.

Default YAML example

modules:
  websocket:
    enabled: true
    writeWait: 10s
    pongWait: 1m
    pingPeriod: 54s
    maxMessageSize: 65536
    sendChannelBuffer: 256
    readBufferSize: 4096
    writeBufferSize: 16384
    enableSmartSubscriptions: true