60 lines
2.5 KiB
Markdown
60 lines
2.5 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
|
|
```
|
|
|
|
## 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`.
|