苹果健康数据中心

Manual quick-start (without `setup.sh`)

```bash cp .env.example .env

Updating Existing Installs

Fresh installs load db/schema.sql automatically. Existing Docker volumes keep their original schema, so the Compose stack runs the migration service before the API, worker, agents, or Home Assistant bridge start:

docker compose up -d --build

To run the same migration pass explicitly:

docker compose run --rm migrate

The runner records applied files in schema_migrations, so re-runs are safe. Migration files still live in db/migrations/ for review and manual recovery. The current set starts at db/migrations/001_audit_hardening.sql and includes later additive upgrades such as db/migrations/002_analysis_tables.sql and db/migrations/008_oauth_tokens.sql; files apply in filename order.

Add to docker-compose.yml

caddy: image: caddy:2-alpine ports: - "443:443" volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro

Quick start

You need Docker installed and running, plus a terminal. On Windows, run this inside WSL2 - setup.sh is a bash script.

git clone https://github.com/umutkeltek/health-data-hub.git
cd health-data-hub
./setup.sh

That's it. setup.sh:

1. Generates secure passwords and writes a .env for you
2. Asks if you want the AI briefing system, then detects your RAM + GPU and recommends the right Ollama model (you can override)
3. Brings the whole stack up with docker compose up -d

When it finishes, run ./setup.sh doctor to confirm every service is healthy. The doctor prints the exact iOS-app URL to paste into HealthSave under Settings → Server Sync.

Re-running ./setup.sh is safe - it preserves passwords and updates only the AI-related config based on your answers.

Edit .env to set OLLAMA_MODEL=<new-tag>

docker compose exec ollama ollama pull <new-tag> docker compose restart api ```

The tier table above is a starting point - any Ollama model tag works. Browse ollama.com/library for the full list.

./setup.sh doctor says a service isn't running.

Run docker compose logs <service> (e.g. docker compose logs api) to see why. Most first-time failures are Docker not having enough memory allocated - bump it in Docker Desktop's preferences and re-run ./setup.sh.

---

Edit .env with your passwords

docker compose up -d ```

This starts: - TimescaleDB on port 5432 - FastAPI on port 8000 - Grafana on port 3000 (default login: admin / your GRAFANA_PASSWORD)

The database port is bound to 127.0.0.1 by default so it is available for local tooling without being exposed on your LAN.

To opt into Ollama manually, copy docker-compose.override.yml.example to docker-compose.override.yml, copy config.yaml.example to config.yaml, set analysis.daily_briefing.enabled and analysis.anomaly_detection.enabled to true, and set OLLAMA_MODEL in .env to the tag you want.

API Endpoints

/api/apple/status intentionally returns top-level metric objects, not a wrapped {"status":"ok","counts":...} payload. See API.md for the compatibility contract.

Home Assistant Integration

There are two supported Home Assistant paths:

1. MQTT bridge (recommended): Health Data Hub reads TimescaleDB and publishes retained Home Assistant MQTT discovery + state topics. This keeps Home Assistant out of the database and works even when Grafana is deployed separately.
2. Direct SQL package (legacy/example): Home Assistant queries TimescaleDB directly using integrations/home-assistant/healthsave-package.yaml.

The bridge publishes in two layers each cycle:

Aggregate parent device (one device, one state topic, the legacy shape):

• Retained state topic: healthsave/sensor/state
• Discovery topics: homeassistant/sensor/healthsave/<metric>/config
• Availability: healthsave/status

Six entities on the parent device by default:

• sensor.healthsave_heart_rate
• sensor.healthsave_hrv_7d_avg
• sensor.healthsave_steps_today
• sensor.healthsave_last_sleep_hours
• sensor.healthsave_source_model
• sensor.healthsave_room_health_state

Per-source sub-devices (one device per distinct source_id seen in recent data — Apple Watch, Whoop, iPhone, etc.):

• Retained state topic: healthsave/source/<slug>/state (one JSON payload per source)
• Discovery topics: homeassistant/sensor/healthsave_<slug>/<metric>/config
• Linked to the parent via Home Assistant's via_device so HA nests sub-devices under the parent.
• Metrics carried per sub-device: heart_rate, hrv_latest_ms, steps_today, last_sleep_hours. Only metrics with a recent non-null value get a discovery message, so HA never sees ghost entities.

Example: a household running both an Apple Watch and a Whoop sees: - sensor.healthsave_apple_watch_heart_rate, _hrv_latest_ms, _steps_today, _last_sleep_hours - sensor.healthsave_whoop_heart_rate, _hrv_latest_ms, _last_sleep_hours (no _steps_today if Whoop hasn't logged any).

Source attribution comes from source_id on the ingestion tables (added to daily_activity and sleep_sessions in migration 009; native to heart_rate / hrv since v1). Rows with NULL source_id collapse to a single sensor.healthsave_unknown_* sub-device so legacy data never fragments into empty entities.

Both layers share healthsave/status so HA marks every sub-device offline together if the bridge stops.

Legacy MQTT namespace migration. Fresh installs should keep the primary HA_MQTT_STATE_TOPIC_PREFIX, HA_MQTT_DEVICE_IDENTIFIER, and HA_MQTT_DEVICE_NAME values on healthsave / HealthSave. If an existing Home Assistant install still has dashboards or automations on an older namespace, set HA_MQTT_LEGACY_STATE_TOPIC_PREFIX plus the matching legacy device identifier/name. The bridge then publishes both shapes from the same Data Hub service so Home Assistant can be migrated one entity at a time.

HA_MQTT_STATE_TOPIC_PREFIX=healthsave
HA_MQTT_DEVICE_IDENTIFIER=healthsave
HA_MQTT_DEVICE_NAME=HealthSave
HA_MQTT_LEGACY_STATE_TOPIC_PREFIX=<old-prefix>
HA_MQTT_LEGACY_DEVICE_IDENTIFIER=<old-device-id>
HA_MQTT_LEGACY_DEVICE_NAME=<old-display-name>

Enable it with Docker Compose. Two patterns:

(a) Bring your own broker. Point the bridge at an MQTT server you already run:

HA_MQTT_ENABLED=true \
HA_MQTT_BROKER=<your-mqtt-host> \
HA_MQTT_USERNAME=<optional-user> \
HA_MQTT_PASSWORD=<optional-password> \
docker compose --profile home-assistant up -d homeassistant-mqtt

(b) Use the bundled broker. Add the mosquitto profile and the stack runs an eclipse-mosquitto:2 container alongside the bridge. The bridge's default HA_MQTT_BROKER=mqtt resolves through docker DNS, and host port 1883 is published so a Home Assistant install on the same LAN can also connect by host IP. Persistence is on a docker volume so retained messages survive restarts.

HA_MQTT_ENABLED=true \
docker compose --profile mosquitto --profile home-assistant up -d

The bundled broker defaults to anonymous-on-LAN. To require auth, overlay a docker-compose.override.yml that flips allow_anonymous false and mounts a password file — the conf at deploy/mosquitto/mosquitto.conf is read-only so the override is the right seam.

Useful defaults:

• Discovery prefix: homeassistant
• State prefix: healthsave
• Device identifier: healthsave
• Publish interval: 60 seconds

Direct SQL example files remain available for setups that prefer DB polling: - integrations/home-assistant/healthsave-package.yaml - integrations/home-assistant/secrets.example.yaml

Troubleshooting

The Ollama container won't start.

docker compose logs ollama

The most common causes are: not enough free RAM (Ollama refuses to load a model that won't fit), the override file missing (re-run ./setup.sh - it copies the example), or another process holding port 11434 (stop it, or edit docker-compose.override.yml to bind a different port).

My briefing came back empty (or said "not enough data").

Two things to check:

1. Has HealthSave actually synced? Hit http://localhost:8000/api/apple/status - if the table counts are all zero, sync from your phone first.
2. How much history do you have? The statistical engine needs at least ~24 hours of heart-rate data to compute anything. Newly-installed users typically see a real briefing on day 2.

I want to change the model after setup.

Edit the OLLAMA_MODEL= line in your .env, then pull the new tag and restart:

```bash