# 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
```

## 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 | — |
| `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`.