92 lines
4.0 KiB
Markdown
92 lines
4.0 KiB
Markdown
# HomeOS
|
|
|
|
Self-built smart-home control plane — single household, self-hosted, LAN-first.
|
|
Laravel 13 · Livewire v3 · Tailwind v4 · PostgreSQL 17 + TimescaleDB · Redis/Horizon · Reverb.
|
|
|
|
Everything runs in Docker; the host needs **only Docker** (no PHP/Composer/Node).
|
|
Authoritative spec: [`handoff.md`](handoff.md) · conventions: [`rules.md`](rules.md) · guide: [`CLAUDE.md`](CLAUDE.md).
|
|
|
|
## First-run setup
|
|
|
|
```bash
|
|
cp .env.example .env # dev defaults work as-is
|
|
docker compose build # build the app image
|
|
docker compose run --rm app bash docker/app/bootstrap.sh # deps + key + assets + migrate/seed
|
|
bash docker/mosquitto/gen-passwd.sh # broker credentials (fills empty MQTT_*_PASSWORD)
|
|
docker compose up -d # start the full stack
|
|
```
|
|
|
|
> `docker compose up` alone is **not** the first command — `vendor/`, `node_modules`,
|
|
> `public/build` and the Mosquitto passwd file are not committed, so the steps above
|
|
> must run first.
|
|
|
|
Then open **http://localhost** and sign in with the seeded dev admin:
|
|
|
|
- **admin@homeos.local** / **homeos-dev** ← change this for anything but local dev.
|
|
|
|
### Production
|
|
|
|
`.env.example` ships **development** defaults. For a real deployment you **must**:
|
|
|
|
- set `APP_ENV=production` and `APP_DEBUG=false` (otherwise exceptions are exposed
|
|
and the demo household is seeded into your real database);
|
|
- set strong values for `DB_PASSWORD`, the `REVERB_APP_*` keys and
|
|
`HOMEOS_ADMIN_PASSWORD` (seeding aborts if the admin password is unset outside
|
|
local/testing), and run `php artisan key:generate`.
|
|
|
|
The demo seeder (`DemoHomeSeeder`) only runs in local/testing.
|
|
|
|
## Everyday commands (in-container, R8)
|
|
|
|
```bash
|
|
docker compose exec app php artisan … # artisan
|
|
docker compose exec app composer … # composer
|
|
docker compose exec app npm run build # rebuild assets (or `npm run dev` for HMR)
|
|
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 (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 | — |
|
|
|
|
All ports and `HOST_UID`/`HOST_GID` are env-driven in `.env`.
|