# Hearth Hub

Hearth Hub is a self-hosted home-automation service that connects lights, switches, sensors, thermostats, and other smart devices behind one local interface. It provides a web dashboard, automation engine, and REST API while keeping routine control available when the internet is down.

## Features

- Local-first device control and automation
- Responsive web dashboard
- Rules based on time, device state, presence, and sensor values
- Scenes for coordinating multiple devices
- MQTT device discovery and messaging
- Zigbee support through Zigbee2MQTT
- REST API and webhooks
- Event history and configurable data retention
- Multiple users with administrator and household roles
- Optional remote access through a reverse proxy
- Docker-based deployment with automatic health checks

## Requirements

- Docker Engine 24 or later
- Docker Compose v2
- An MQTT broker such as Mosquitto
- Optional: Zigbee coordinator supported by Zigbee2MQTT

## Installation

Clone the repository:

```bash
git clone https://github.com/example/hearth-hub.git
cd hearth-hub
```

Create the local configuration files:

```bash
cp .env.example .env
cp config.example.yaml config.yaml
```

Edit `.env` and set a strong application secret:

```dotenv
HEARTH_SECRET=replace-with-a-long-random-value
```

Start the hub:

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

Open `http://localhost:8080` and follow the setup wizard to create the first administrator account.

Check service status with:

```bash
docker compose ps
docker compose logs -f hearth
```

## Usage

### Add a device

Open **Settings → Devices → Add device** and select an integration. MQTT devices that publish supported discovery messages appear automatically.

For manual MQTT devices, provide:

- A unique device ID
- State and command topics
- Device type, such as `light`, `switch`, or `sensor`
- Payload mappings when the device does not use standard values

### Create an automation

Open **Automations → New automation**, then define a trigger, optional conditions, and one or more actions.

For example, this rule turns on the hallway light when motion is detected after sunset:

```yaml
automations:
  - id: hallway_motion
    name: Hallway light after dark
    trigger:
      type: device_state
      device: hallway_motion
      state: detected
    conditions:
      - type: sun
        after: sunset
    actions:
      - service: light.turn_on
        target: hallway_light
        data:
          brightness: 70
      - delay: 5m
      - service: light.turn_off
        target: hallway_light
```

After editing `config.yaml`, validate and reload it:

```bash
docker compose exec hearth hearth config check
docker compose exec hearth hearth config reload
```

### Activate a scene

Scenes can be activated from the dashboard or API:

```bash
curl -X POST http://localhost:8080/api/v1/scenes/evening/activate \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Create API tokens under **Settings → Account → API Tokens**. Treat tokens as passwords and avoid committing them to source control.

## Configuration

Hearth Hub loads its main configuration from `/app/config/config.yaml` inside the container. The default Compose file mounts the project-level `config.yaml` at that location.

```yaml
server:
  host: 0.0.0.0
  port: 8080
  timezone: America/Toronto
  public_url: http://localhost:8080

mqtt:
  host: mosquitto
  port: 1883
  username: hearth
  password_env: MQTT_PASSWORD
  discovery_prefix: homeassistant
  reconnect_interval: 5s

storage:
  database: /app/data/hearth.db
  event_retention: 30d

logging:
  level: info
  format: json
```

Sensitive values should be stored in `.env` and referenced with an `_env` configuration field where supported:

```dotenv
MQTT_PASSWORD=replace-with-your-broker-password
```

Common environment variables include:

| Variable | Default | Description |
| --- | --- | --- |
| `HEARTH_SECRET` | None | Required secret used to sign sessions and tokens |
| `HEARTH_CONFIG` | `/app/config/config.yaml` | Path to the main configuration file |
| `HEARTH_LOG_LEVEL` | `info` | Logging level: `debug`, `info`, `warn`, or `error` |
| `MQTT_PASSWORD` | None | MQTT broker password referenced by `password_env` |
| `TZ` | `UTC` | Container timezone |

Restart the service when changing environment variables:

```bash
docker compose up -d --force-recreate hearth
```

## Updating

Pull the latest image and recreate the containers:

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

Back up `config.yaml`, `.env`, and the `data` volume before major upgrades. Review the release notes for configuration migrations and breaking changes.

## Security

Hearth Hub is intended to run on a trusted local network. If exposing it remotely, place it behind an HTTPS reverse proxy, enable authentication, restrict inbound traffic, and keep the host and containers updated. Never expose MQTT or the application database directly to the public internet.

## License

Licensed under the MIT License. See `LICENSE` for details.