kirpi4ik/myhab repository overview

⁠myHAB

Self-hosted home automation backend, under the LGPLv3. MQTT device control, solar and heat-pump monitoring, floor-plan dashboards, scenario automation, an LLM voice assistant and tokenised guest links — running on your own hardware, with no vendor cloud in the control path.

One JVM process, one PostgreSQL database, one MQTT broker. That is the whole system.

📖 myhab.org⁠ · 📚 Documentation⁠ · 💻 Source⁠ · 🚀 Live demo⁠

⁠Try it before you install it

A complete, fully interactive installation runs at demo.myhab.org⁠ with simulated devices answering on a real MQTT broker.

Data is shared between visitors and resets when idle.

⁠Tags

Platform: linux/amd64 only. There is no arm64 image, so a Raspberry Pi or an Apple Silicon host needs to build its own (./gradlew buildImage on the target, or docker buildx build --platform linux/arm64).

⁠What is in the image

The web client (Vue 3 + Quasar PWA) is bundled in the same jar and served from the same port — there is no separate frontend container.

⁠Quick start

myHAB needs three things: a PostgreSQL database, an MQTT broker, and a git repository holding its runtime configuration.

⁠1. Create the configuration repository

Configuration lives in git rather than in the image, so you can change broker credentials, feature flags and dashboard bindings without rebuilding or restarting anything — and you get a history of every change. Create a private repository (it holds credentials) with one branch per environment; production reads prod by default.

mkdir myhab-config && cd myhab-config
git init -b prod
cat > config.yaml <<'YAML'
mqtt:
  hostname: mosquitto
  port: 1883
  username: myhab
  password: change-me
  topics: myhab/#

cors:
  allowedOrigin:
    - https://home.example.com

ui:
  meteo:
    locationName: My Town
YAML
git add . && git commit -m "Initial myHAB configuration"
git push origin prod

⁠2. Start the stack

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: myhab
      POSTGRES_USER: myhab
      POSTGRES_PASSWORD: change-me
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  mosquitto:
    image: eclipse-mosquitto:2
    volumes:
      - ./mosquitto:/mosquitto/config
    ports:
      - "1883:1883"
    restart: unless-stopped

  myhab:
    image: kirpi4ik/myhab:2.8.12   # pin a version; the badge above shows the newest
    depends_on: [postgres, mosquitto]
    ports:
      - "8181:8181"
    environment:
      GRAILS_ENV: production
      TZ: Europe/Bucharest
      DB_URL: jdbc:postgresql://postgres:5432/myhab
      DB_USERNAME: myhab
      DB_PASSWORD: change-me
      JWT_SECRET: <a long random string>
      CFG_REPO_URI: https://github.com/you/myhab-config.git
      CFG_USERNAME: <git user>
      CFG_PASSWORD: <git token>
    volumes:
      - ./config:/app/config
    restart: unless-stopped

volumes:
  pgdata:

docker compose up -d

The schema is created on first start by Hibernate (dbCreate = update): it adds tables and columns as the model grows, and never drops anything. Give it a minute, then check http://localhost:8181/actuator/healthcheck.

⁠3. Create the first account

There is no default admin user — nothing is seeded, so nobody can log in until you insert an account. Generate a BCrypt hash:

htpasswd -bnBC 10 "" 'your-password' | tr -d ':\n'

Then, against the myhab database:

INSERT INTO sec_roles (id, version, authority) VALUES
  (1, 0, 'ROLE_USER'),
  (2, 0, 'ROLE_ADMIN')
ON CONFLICT DO NOTHING;

-- note: `users` has no version column
INSERT INTO users (id, username, password, first_name, last_name, email,
                   enabled, account_locked, account_expired, password_expired,
                   ts_created, ts_updated, en_type, language, timezone)
VALUES (1, 'admin', '<bcrypt hash>', 'Site', 'Admin', '[email protected]',
        true, false, false, false, now(), now(), 'USER', 'en', 'UTC');

INSERT INTO sec_user_roles (user_id, role_id) VALUES (1, 1), (1, 2);

The join table is sec_user_roles, not users_sec_roles. Log in at http://localhost:8181/ and create the rest of your users in the UI.

⁠Environment variables

Anything else — job intervals, trusted proxies, vendor integrations — goes either in the configuration repository or in an application.yml inside the /app/config volume, which Spring Boot layers over the image's defaults.

⁠Behind a reverse proxy

Terminate TLS at nginx/Caddy/Traefik and proxy to 8181. Tell myHAB which proxy it can believe, or every audited action will be attributed to the proxy's own address — in /app/config/application.yml:

myhab:
  security:
    trustedProxies:
      - 172.18.0.1

WebSocket upgrades must be passed through: real-time port state, dashboards and the voice assistant all use STOMP over WebSocket.

⁠Upgrading

docker compose pull && docker compose up -d

Schema changes are applied at startup and are not reversible — back up the database first. Read the release notes for the versions you are skipping: github.com/kirpi4ik/myhab/releases⁠.

⁠Companion image

kirpi4ik/myhab-demo carries the assets for the public demo sandbox built from the same commit: the MQTT device simulator, the seed dataset and the configuration seed. It is only useful if you are running a demo installation of your own — a normal deployment does not need it.

⁠Licence

myHAB is developed under the GNU Lesser General Public License v3 (LGPLv3) — gnu.org/licenses/lgpl-3.0.html⁠.

Run it, modify it and deploy it freely, commercially included. Distributing a modified myHAB means releasing those modifications under the LGPLv3 as well; software that merely links against it keeps its own licence.

⁠Documentation

Issues and pull requests: github.com/kirpi4ik/myhab⁠.