Configuration

The four layers

Environment variables

The branch ConfigProvider reads defaults to prod in the production environment and dev elsewhere; override it with the myhab.config.branch property.

The configuration repository

One YAML document, versioned in git, cloned by the application at start and re-read by the configSync job. It is also editable in the UI under Settings → App configuration, which commits back to the repository.

MQTT

mqtt:
  hostname: mosquitto
  port: 1883
  username: myhab
  password: change-me
  topics: myhab/#        # subscription filter

The outbound topic prefix (myhab) is set separately in application.yml under mqtt.topic.prefix.

CORS

Only needed when the client is served from a different origin than the API — for example during development, or if you host the PWA separately.

cors:
  allowedOrigin:
    - https://home.example.com
    - http://localhost:10002

UI bindings

These tell the dashboard which entities to wire its fixed tiles to. Only keys under specialDevices., specialZones., ui., grafana. and surveillance. are exposed to the browser — the rest of the store never leaves the server for non-admin users.

specialZones:
  int:    { id: 1001 }   # "Interior" quick tile
  ext:    { id: 1003 }   # "Exterior" quick tile
  parter: { id: 1001 }   # ground floor
  etaj:   { id: 1007 }   # upper floor
  lan:    { id: 1005 }   # lawn irrigation
  garden: { id: 1006 }   # garden irrigation

specialDevices:
  doorLockMain:
    peripheral:
      id: 1234           # the gate the dashboard card operates

ui:
  meteo:
    locationName: My Town

Two optional integrations are wired the same way — an embedded Grafana dashboard for long-range charts, and a link to whatever surveillance UI you run:

grafana:
  url: https://grafana.example.com
  dashboard:
    solar:       { id: abc123 }
    temperature: { id: def456, panelId: 4 }

surveillance:
  url: https://cameras.example.com

Given https://grafana.example.com/d/abc123/solar-plant, set grafana.url to the origin and grafana.dashboard.solar.id to abc123. Without them the Solar Reports page explains what is missing instead of rendering a broken frame.

Heating

heat:
  thermostat:
    enabled: true
  temp:
    allDay: 21           # default setpoint in °C

Auto-import

admin:
  devices:
    autoimport: false    # create Device rows from unknown MQTT announcements
  ports:
    autoimport: false    # create DevicePort rows from unknown port topics

Useful when bringing a new controller online; turn it back off afterwards so a misbehaving device cannot spawn hundreds of rows.

Notifications

telegram:
  token: "<bot token>"
  chanelId: "<channel id>"
  bot1x1ChannelId: "<direct chat id>"

push:
  vapid:
    publicKey: "<vapid public key>"
    privateKey: "<vapid private key>"
    subject: "mailto:you@example.com"

opsgenie:
  url: https://api.opsgenie.com
  apiKey: "<key>"
  team: "<team>"
  recipientId: "<id>"
  alias: myhab
  email: alerts@example.com

All three degrade cleanly when absent: the Telegram bot stays off (it also has its own myhab.telegram.enabled switch), web push logs one warning and stays inactive, and OpsGenie keys are only read when an alert is actually raised.

Feature flags

Quartz job intervals

Every scheduled job can be enabled, disabled and re-timed from quartz.jobs.* without touching code. These live in application.yml and are typically overridden per deployment in ./config/application.yml.

# ./config/application.yml — enable the integrations you actually own
quartz:
  jobs:
    huaweiInfoSync:   { enabled: true,  interval: 300 }
    heatingControl:   { enabled: true,  interval: 120 }
    eventLogReader:   { enabled: true,  interval: 60 }
    nibeInfoSync:     { enabled: false }

Security settings

myhab:
  security:
    # Reverse proxies whose X-Real-IP we believe. Must be the proxy's own address.
    # Empty means no request arriving with forwarding headers is trusted.
    trustedProxies: []
    # Networks the anonymous device endpoints may be called from.
    lanCidrs:
      - 192.168.0.0/16
      - 10.0.0.0/8
      - 172.16.0.0/12
      - 127.0.0.0/8
      - ::1/128

Per-entity configuration

Many entities carry their own key/value sidecar, edited from that entity's screen rather than globally.

Settings in the app

Some things are per-user rather than per-installation, and live in the profile:

• Language — English or Romanian, or Automatic to follow the browser. The same choice drives voice recognition and spoken replies.
• Timezone — an IANA id used to render every stored UTC timestamp.
• Dashboard widgets — which cards appear, in what order.
• Favourites — jobs and scenarios pinned for one-tap execution.
• Avatar — a small PNG/JPEG stored on the account.