# HearthHub

HearthHub is a local-first home-automation hub for controlling lights, switches, sensors, climate devices, cameras, and scenes from one dashboard. It is designed to run on a Raspberry Pi, mini PC, NAS, or home server and keeps automations running locally even when the internet is unavailable.

## Features

- Local web dashboard for rooms, devices, scenes, and automations
- MQTT device support, including Zigbee2MQTT and custom sensors
- Rule engine with triggers, conditions, schedules, and actions
- Scene management for common routines like `Movie Night` or `Away`
- REST API and WebSocket event stream
- Optional integrations for weather, presence, and webhooks
- Role-based user accounts
- Encrypted secrets file for tokens and passwords
- Backup and restore for configuration, database, and automation rules

## Install

### Requirements

- Docker 24+ and Docker Compose v2, or Node.js 20+
- 1 GB RAM minimum, 2 GB recommended
- MQTT broker such as Mosquitto for MQTT-based devices
- Persistent storage for configuration and event history

### Docker Compose

Create a project directory:

```bash
mkdir hearthhub
cd hearthhub
```

Create `docker-compose.yml`:

```yaml
services:
  hearthhub:
    image: ghcr.io/example/hearthhub:latest
    container_name: hearthhub
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config:/config
      - ./data:/data
    environment:
      HEARTHHUB_CONFIG: /config/config.yaml

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

Start the hub:

```bash
docker compose up -d
```

Open the dashboard at:

```text
http://localhost:8080
```

On first launch, HearthHub prompts you to create the owner account.

### From Source

```bash
git clone https://github.com/example/hearthhub.git
cd hearthhub
npm install
npm run build
npm start
```

## Usage

### Add Devices

Open the dashboard, go to **Devices**, and select **Discover**. HearthHub listens for supported MQTT discovery messages and shows newly discovered devices for review before adding them.

For Zigbee devices, pair devices through Zigbee2MQTT first, then enable MQTT discovery in HearthHub.

### Create an Automation

Example: turn on the hallway light when motion is detected after sunset.

```yaml
id: hallway-motion-evening
name: Hallway Motion After Sunset
enabled: true
trigger:
  platform: state
  entity: sensor.hallway_motion
  to: "active"
conditions:
  - platform: sun
    after: sunset
actions:
  - service: light.turn_on
    entity: light.hallway
    data:
      brightness: 70
  - delay: 00:03:00
  - service: light.turn_off
    entity: light.hallway
```

Automations can be created from the dashboard or stored as YAML files in the configured automation directory.

### API

Get all devices:

```bash
curl http://localhost:8080/api/devices \
  -H "Authorization: Bearer $HEARTHHUB_TOKEN"
```

Subscribe to live events:

```bash
wscat -c ws://localhost:8080/api/events \
  -H "Authorization: Bearer $HEARTHHUB_TOKEN"
```

## Configuration

HearthHub reads configuration from `config/config.yaml` by default.

```yaml
server:
  host: 0.0.0.0
  port: 8080
  public_url: http://home.local:8080

storage:
  database: /data/hearthhub.db
  backups: /data/backups
  retention_days: 30

mqtt:
  enabled: true
  host: mosquitto
  port: 1883
  username: hearthhub
  password_secret: mqtt_password
  discovery_prefix: homeassistant

automation:
  directory: /config/automations
  reload_on_change: true

security:
  session_timeout_minutes: 120
  require_mfa: false
  trusted_proxies:
    - 192.168.1.10

logging:
  level: info
  format: text
```

### Configuration Reference

| Key | Description | Default |
| --- | --- | --- |
| `server.host` | Interface the web server binds to | `0.0.0.0` |
| `server.port` | HTTP port for the dashboard and API | `8080` |
| `server.public_url` | External URL used for callbacks and links | unset |
| `storage.database` | SQLite database path | `/data/hearthhub.db` |
| `storage.backups` | Backup output directory | `/data/backups` |
| `mqtt.enabled` | Enable MQTT integration | `true` |
| `mqtt.host` | MQTT broker hostname | `localhost` |
| `mqtt.port` | MQTT broker port | `1883` |
| `mqtt.discovery_prefix` | Discovery topic prefix | `homeassistant` |
| `automation.directory` | Directory for YAML automation files | `/config/automations` |
| `security.session_timeout_minutes` | Web session lifetime | `120` |
| `logging.level` | Log level: `debug`, `info`, `warn`, or `error` | `info` |

### Secrets

Secrets are stored separately from `config.yaml` in `config/secrets.yaml`:

```yaml
mqtt_password: change-this-password
weather_api_key: optional-api-key
```

Reference secrets from configuration with the `_secret` suffix, such as `password_secret: mqtt_password`.

### Environment Variables

Environment variables override file-based configuration.

| Variable | Description |
| --- | --- |
| `HEARTHHUB_CONFIG` | Path to the main configuration file |
| `HEARTHHUB_DATA_DIR` | Directory for database, logs, and backups |
| `HEARTHHUB_LOG_LEVEL` | Runtime log level |
| `HEARTHHUB_TOKEN` | API token for CLI and scripts |

## Backup and Restore

Create a backup:

```bash
docker compose exec hearthhub hearthhub backup create
```

Restore a backup:

```bash
docker compose exec hearthhub hearthhub backup restore /data/backups/hearthhub-2026-07-11.tar.gz
```

Backups include configuration, automations, scenes, users, and event history. Secrets are included only when `storage.backup_secrets` is enabled.