boban
/
homeos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: README — Ring add-on setup, PWA install, full services table 

Document the opt-in ring-mqtt bridge flow (gen-passwd → --profile addons →
ring-mqtt web UI login → Add-ons install), the PWA install-to-home-screen, and
the previously-undocumented mqtt-listener / mosquitto / discovery / ring-mqtt
services with their ports.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat/phase-1-bootstrap
HomeOS Bootstrap 2026-07-18 02:10:47 +02:00
parent 68e2708ff6
commit 9c566492ab
1 changed files with 33 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
README.md
View File

@ -46,13 +46,45 @@ docker compose exec app php artisan test # test suite
docker compose logs -f app # logs
```
## Add-ons
On-demand integrations, managed under **Add-ons** in the sidebar.
### Ring (cloud, opt-in)
Ring has no local API, so HomeOS bridges it via [ring-mqtt](https://github.com/tsightler/ring-mqtt),
which runs as an **opt-in** container (it never starts on a Ring-less setup):
```bash
bash docker/mosquitto/gen-passwd.sh # seeds the least-privileged `ring` broker account
docker compose --profile addons up -d ring-mqtt # start the bridge
```
Then:
1. Open **http://<host>:${RING_UI_PORT:-55123}** (ring-mqtt's own web UI) and sign in with your
Ring account (email + password + 2FA). It mints and stores the refresh token — HomeOS never
handles Ring's OAuth itself.
2. In HomeOS → **Add-ons → Ring → Install**, then **Connect account**.
3. Ring devices (doorbell, cameras, sensors) appear automatically under **Devices**, tagged **Cloud**.
## Install as an app (PWA)
HomeOS ships a web manifest + service worker, so it installs to a tablet/phone home screen
("Add to Home Screen") and runs full-screen. Use the **Steuerung** (`/panel`) tab as the tablet
control surface. Install requires HTTPS in production (localhost is exempt for testing).
## Services & ports
| Service | Role | Host port |
|---|---|---|
| `app` | php-fpm + nginx + supervisor | `${APP_PORT:-80}` |
| `reverb` | websockets (proxied same-origin via nginx `/app`) | `${REVERB_HOST_PORT:-6001}` |
| `horizon` · `scheduler` | queue workers · cron | — |
| `horizon` · `scheduler` | queue workers · cron (presence, metrics, automations) | — |
| `mqtt-listener` | subscribes the bus, dispatches ingest jobs | — |
| `mosquitto` | MQTT broker (auth + per-client ACLs) | `${MQTT_HOST_PORT:-1883}` |
| `discovery` | mDNS/SSDP sidecar (host network) | — |
| `ring-mqtt` | Ring bridge — **opt-in** (`--profile addons`) | `${RING_UI_PORT:-55123}` |
| `db` | PostgreSQL 17 + TimescaleDB | `127.0.0.1:${DB_HOST_PORT:-5432}` |
| `redis` | cache / queue | — |