Homenavi

Quickstart

Get a working Homenavi instance in a few minutes with Docker Compose. The quickstart uses prebuilt release images, so no local build is required.

Prerequisites

  • Docker and Docker Compose
  • Git
  • Ports 80/443 available on your machine

1. Clone the repository

git clone https://github.com/PetoAdam/homenavi.git
cd homenavi

2. Configure environment

cp .env.example .env

The defaults are enough for a first run. Set HN_VERSION=vX.Y.Z in .env to pin a specific release.

3. Start the stack

docker compose pull
docker compose up -d

This starts the platform: nginx ingress, API gateway, auth, user, dashboard, device-hub, entity registry, history, automation, weather, integration-proxy, Mosquitto, PostgreSQL, Valkey, and SeaweedFS.

4. Open the app

docker compose ps

Once the edge services are running, open http://localhost in your browser and create an account.

Optional profiles

  • Mock adapter — opt-in profile that seeds fake devices so you can explore dashboards and automations without hardware.
  • Zigbee2MQTT — opt-in through the hardware profile. It is disabled by default so a local evaluation never claims a USB coordinator.

Next steps

Next guide: Deployment guide →