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 · conventions: rules.md · guide: CLAUDE.md.

First-run setup

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)

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.