# healthcheck-container

Small Flask service for remote devices (Raspberry Pi in Docker) that answers
`/alive` for container monitoring and, on top of that, watches the network the
device sits on: internet reachability, DNS, public IP changes, Wi-Fi link
quality, Wi-Fi networks in range, and host reboots. Metrics go to SQLite and
are shown on a dashboard at `/`. Optionally the same values are published to an
MQTT broker with Home Assistant discovery, so each device shows up in Home
Assistant as a device with sensors and no manual configuration.

## Endpoints

| Path | Purpose |
| --- | --- |
| `/alive` | Unchanged health check, returns `{"alive": true}` |
| `/` | Dashboard: status, Wi-Fi, graphs, timeline |
| `/api/status` | Latest state of every monitor as JSON |
| `/api/wifi` | Interface list, link details, last scan results |
| `/api/mqtt` | MQTT connection state, counters, last error, last published payload, last probe |
| `POST /api/mqtt/probe` | Run the broker connection probe now and return its result |
| `/api/events?limit=200` | Timeline events, newest first |
| `/api/samples?prefix=reach.&range=3600` | Bucketed samples for graphs |

## Running

The compose file pulls the published multi-arch image
`hiimmilan/health-check` (amd64, arm64, arm/v7):

```sh
docker compose pull && docker compose up -d
```

Then open `http://<device>:9999/`.

Wi-Fi needs two things from Docker:

- `network_mode: host`, otherwise the container has no wireless interface at all.
- `cap_add: NET_ADMIN`, otherwise link and interface info work but scanning fails
  with a permission error that is shown on the dashboard.

Without `WIFI_INTERFACE` the dashboard lists the interfaces it can see and
nothing is scanned. Set the variable to one of the listed wireless interfaces
and restart the container.

## Storage

Samples and events are stored in SQLite at `DB_PATH` (default
`/data/healthcheck.db`). The compose file mounts a named volume at `/data`, so
the database survives `docker compose down`, image rebuilds and `up -d`. Only
`docker compose down -v` or `docker volume rm` deletes it. A bind mount works
as well, for example `- /opt/healthcheck:/data`.

Samples older than `SAMPLE_RETENTION_DAYS` (default 7) are deleted hourly.
Events are kept. Wi-Fi scan results are held in memory only and never written.

## Configuration

All settings are environment variables. Intervals are in seconds.

| Variable | Default | Meaning |
| --- | --- | --- |
| `PORT` | `9999` | HTTP port |
| `DB_PATH` | `/data/healthcheck.db` | SQLite file |
| `SAMPLE_RETENTION_DAYS` | `7` | How long graph samples are kept |
| `DEVICE_NAME` | hostname | Shown on the dashboard and in Home Assistant |
| `DEVICE_ID` | slug of `DEVICE_NAME` | Used in MQTT topics and unique ids |
| `REACH_TARGETS` | `1.1.1.1:443,8.8.8.8:443,9.9.9.9:443` | TCP connect targets, `host:port` |
| `REACH_INTERVAL` | `30` | |
| `REACH_TIMEOUT` | `3` | Connect timeout per target |
| `DNS_NAME` | `cloudflare.com` | Name resolved through the system resolver |
| `DNS_INTERVAL` | `60` | |
| `PUBLIC_IP_URLS` | ipify, ifconfig.me, icanhazip | Tried in order, first answer wins |
| `PUBLIC_IP_INTERVAL` | `300` | |
| `PUBLIC_IP_TIMEOUT` | `5` | |
| `UPTIME_INTERVAL` | `60` | Reboot detection via `/proc/uptime` |
| `WIFI_INTERFACE` | empty | Wireless interface to use, empty disables Wi-Fi |
| `WIFI_LINK_INTERVAL` | `30` | Signal, bitrate, retries of the current link |
| `WIFI_SCAN_INTERVAL` | `60` | Scan for networks in range |
| `MQTT_HOST` | empty | Broker host, empty disables MQTT |
| `MQTT_PORT` | `1883` | |
| `MQTT_USERNAME` | empty | |
| `MQTT_PASSWORD` | empty | |
| `MQTT_DISCOVERY_PREFIX` | `homeassistant` | Must match the MQTT integration setting |
| `LOG_LEVEL` | `INFO` | |

## Events on the timeline

- Internet unreachable / reachable again (all targets failed, then any succeeded)
- DNS resolution failed / working again
- Public IP is X, Public IP changed from X to Y
- Wi-Fi connected, disconnected, roamed to another BSSID
- Host rebooted
- Health check service started
- MQTT connected, disconnected, cannot reach broker

## Home Assistant

Set `MQTT_HOST` (and credentials if the broker needs them). On connect the
service publishes retained discovery messages under
`homeassistant/<component>/healthcheck_<device_id>/<key>/config`, all pointing
to one device, then publishes state to `healthcheck/<device_id>/state` and
availability to `healthcheck/<device_id>/availability`. When Home Assistant
restarts it announces itself on `homeassistant/status` and the service
re-publishes discovery.

The dashboard has an MQTT card and a Home Assistant section showing the
connection state, when it last connected or failed, how many messages were
published or dropped, when discovery and availability were last sent, and the
last state payload. The same data is at `/api/mqtt`. Use it to tell an app-side
problem (not connected, publishes dropped) from a Home Assistant-side one
(connected and publishing, but the device is still unavailable).

When a connection attempt fails the service runs a probe from inside the
container, at most every two minutes: it resolves the broker name with the
system resolver, queries each nameserver from `/etc/resolv.conf` directly,
checks `/etc/hosts`, and tries a TCP connect to every address it found. The
result is shown as a summary and as raw JSON in the Home Assistant section, and
can be rerun from the dashboard. If the nameservers disagree about the broker
name, for example a local server that knows it and a public one that does not,
the probe says so. The image is Debian based, so glibc asks the nameservers in
resolv.conf order and only moves on when one does not answer.

Entities per device:

- Internet, DNS, Wi-Fi (binary sensors, `connectivity` class)
- Internet latency, DNS latency (ms)
- Public IP
- Host uptime
- Wi-Fi SSID, BSSID, channel, signal (dBm), TX bitrate (Mbit/s), networks in range

## Development

```sh
python3 -m unittest discover -s tests
DB_PATH=./data/hc.db python3 app.py
```

Publish a new image for all Raspberry Pi architectures:

```sh
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t hiimmilan/health-check:latest -t hiimmilan/health-check:2.3.0 --push .
```