{"id":43090998,"url":"https://github.com/petoadam/homenavi","last_synced_at":"2026-05-23T03:15:24.100Z","repository":{"id":288546467,"uuid":"968378541","full_name":"PetoAdam/homenavi","owner":"PetoAdam","description":"A smart home platform for developers, by developers. Modern, microservice-based, and built to be extended.","archived":false,"fork":false,"pushed_at":"2026-04-22T15:06:34.000Z","size":11008,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-22T15:23:19.276Z","etag":null,"topics":["raspberry-pi","smart-home","smarthome","zigbee"],"latest_commit_sha":null,"homepage":"https://homenavi.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PetoAdam.png","metadata":{"files":{"readme":"README.md","changelog":"history-service/Dockerfile","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-18T01:40:47.000Z","updated_at":"2026-04-22T14:47:19.000Z","dependencies_parsed_at":"2025-04-18T19:31:30.106Z","dependency_job_id":"3f652b74-b950-49e2-9e3c-33b760c1524a","html_url":"https://github.com/PetoAdam/homenavi","commit_stats":null,"previous_names":["petoadam/homenavi"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/PetoAdam/homenavi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PetoAdam%2Fhomenavi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PetoAdam%2Fhomenavi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PetoAdam%2Fhomenavi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PetoAdam%2Fhomenavi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PetoAdam","download_url":"https://codeload.github.com/PetoAdam/homenavi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PetoAdam%2Fhomenavi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32205942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T01:12:49.758Z","status":"online","status_checked_at":"2026-04-24T02:00:07.115Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["raspberry-pi","smart-home","smarthome","zigbee"],"created_at":"2026-01-31T16:13:33.186Z","updated_at":"2026-04-24T02:01:14.678Z","avatar_url":"https://github.com/PetoAdam.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"frontend/public/icons/icon-192x192.png\" alt=\"Homenavi\" width=\"72\" height=\"72\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\" style=\"margin-bottom: 0;\"\u003e\n\t\u003cspan style=\"font-family: 'Manrope', 'Montserrat', 'Inter', 'Segoe UI', Arial, sans-serif; letter-spacing: 0.18em; text-transform: uppercase;\"\u003eHomenavi\u003c/span\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eA smart home platform for developers, by developers. Modern, microservice-based, and built to be extended.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e •\n\t\u003ca href=\"doc/architecture_diagram.md\"\u003eArchitecture\u003c/a\u003e •\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/issues\"\u003eIssues\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/frontend_docker_build.yaml\"\u003e\u003cimg alt=\"Build Frontend Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/frontend_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/user_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build User Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/user_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/api_gateway_docker_build.yaml\"\u003e\u003cimg alt=\"Build API Gateway Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/api_gateway_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/auth_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build Auth Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/auth_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/device_hub_docker_build.yaml\"\u003e\u003cimg alt=\"Build Device Hub Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/device_hub_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/email_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build Email Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/email_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/profile_picture_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build Profile Picture Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/profile_picture_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/echo_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build Echo Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/echo_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/history_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build History Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/history_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/zigbee_adapter_docker_build.yaml\"\u003e\u003cimg alt=\"Build Zigbee Adapter Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/zigbee_adapter_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/thread_adapter_docker_build.yaml\"\u003e\u003cimg alt=\"Build Thread Adapter Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/thread_adapter_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/automation_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build Automation Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/automation_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/entity_registry_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build Entity Registry Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/entity_registry_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/weather_service_docker_build.yaml\"\u003e\u003cimg alt=\"Build Weather Service Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/weather_service_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/PetoAdam/homenavi/actions/workflows/integration_proxy_docker_build.yaml\"\u003e\u003cimg alt=\"Build Integration Proxy Docker Image\" src=\"https://github.com/PetoAdam/homenavi/actions/workflows/integration_proxy_docker_build.yaml/badge.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nWelcome to Homenavi — your open, hackable smart home solution. Built with a modern microservices architecture, Homenavi is designed for tinkerers, makers, and pros who want full control and easy extensibility.\n\n---\n\n\n## Table of Contents\n1. 🚀 Why Homenavi\n2. 🧩 Architecture Overview\n3. 🔮 Smart Home Vision (Current + Upcoming)\n4. 🐳 Quickstart\n5. 📂 Service Directory\n6. 🔒 Security \u0026 Auth\n7. 📊 Observability\n8. ⚡ WebSockets \u0026 Real‑Time\n9. 🔌 Extending the Platform\n10. 🗺️ Roadmap\n11. ⚙️ Configuration \u0026 Environment\n12. 📦 CI/CD\n13. 🤝 Contributing \u0026 Community\n14. ❓ FAQ\n15. 📜 License\n\n---\n\n## 1. 🚀 Why Homenavi\n- **Microservice-first:** Each core feature is its own service – scale, swap, or extend as you like.\n- **Modern stack:** Go, React, Python, Docker, and more.\n- **Dev-friendly:** Easy to run, hack, and contribute.\n- **Open \u0026 Transparent:** 100% open source, MIT licensed.\n- **Cloud or Home:** Run it on your Raspberry Pi, your server, or in the cloud.\n- **Observability built-in:** Prometheus metrics, Jaeger tracing, and request/correlation IDs for easy debugging and monitoring.\n- **WebSocket support:** Real-time communication with cookie-based JWT authentication.\n- **Extensible by design:** Add new device protocols, automations, and integrations with minimal friction.\n\n---\n\n## 2. 🧩 Architecture Overview\n\nFurther reading:\n* [ERS / HDP / Device Hub — How it works (current)](doc/ers_hdp_devicehub_overview.md)\n* [Architecture diagram (current)](doc/architecture_diagram.md)\n\nCurrent Core:\n* API Gateway (Go): Routing, JWT verification, rate limit, WebSocket upgrade.\n* Device Hub (Go): Central device inventory and **HDP-only** adapter bridge over MQTT.\n* History Service (Go): Persists HDP device state into Postgres and serves query endpoints for charts.\n* Automation Service (Go): Automation/workflow orchestration (graph builder UI backend).\n* Weather Service (Go): Cached weather API used by the frontend via the gateway.\n* Auth Service (Go): Login, password management, 2FA (email now, TOTP coming), lockout logic.\n* User Service (Go): Profile, roles, administrative user actions.\n* Dashboard Service (Go): Stores per-user dashboards and widget configuration.\n* Marketplace API (Go, external): Integration catalog + downloads/trending stats (consumed by frontend and integration-proxy).\n* Entity Registry Service (Go): Home inventory primitives (rooms/tags/devices) and discovery surface.\n* Email Service (Go): Outbound verification \u0026 notification emails.\n* Profile Picture Service (Python): Image handling (avatars, basic processing).\n* Echo Service (Python): Real-time WebSocket demo \u0026 test surface.\n* Frontend (React + Vite + PWA): Auth flows, user management, device UI, dashboards.\n* Adapters:\n\t* Zigbee Adapter (Go): Zigbee2MQTT bridge that emits HDP state/metadata/events and consumes HDP commands.\n\t* Thread Adapter (Go): Placeholder implementation that emits HDP hello/status/pairing and acks commands.\n* Infrastructure: PostgreSQL, Redis, Nginx, Prometheus, Jaeger, (Grafana ready).\n\nKey Design Principles:\n* Clear separation of auth vs user domain.\n* Stateless services (use Redis / DB for state persistence \u0026 coordination).\n* Consistent JSON error schema across services.\n* Incremental addition of domain (devices, automations, adapters) without core rewrites.\n* SPA frontend with history fallback (direct links work out of the box).\n\nCurrent Features (Implemented):\n* **Device abstraction via HDP v1:** adapters translate protocol payloads into a single internal contract consumed by core services. See `doc/hdp.md`.\n* **Adapters (today):** Zigbee2MQTT → HDP bridge (plus pairing/commands); Thread adapter placeholder using the same HDP surfaces.\n* **ERS + Device Hub boundary:** ERS owns names/rooms/tags/map metadata; device-hub owns realtime telemetry, pairing, commands. See `doc/ers_hdp_devicehub_overview.md`.\n* **Customizable UI dashboards:** widget-based Home dashboard with Edit mode + per-user persistence via Dashboard Service. See `doc/dashboard_ui_functional_spec.md`.\n* **Integration marketplace flow:** frontend queries the Marketplace API directly for catalog + stats, posts download increments on successful installs, and integration-proxy installs using runtime-resolved `deployment_artifacts` from marketplace metadata.\n* **Automation engine + scheduling:** rule/workflow engine with manual triggers and **cron schedule triggers**, plus run tracking and live run stream via websocket. (APIs documented in `doc/external_api_surface.md`.)\n\n---\n\n## 3. 🔮 Smart Home Vision (Current + Upcoming)\nHomenavi’s “vision” is already partially implemented (dashboards, HDP-based adapters, automations). The next steps are about **expanding capabilities** and **hardening extensibility**:\n\nUpcoming focus areas:\n* **More adapters / protocol coverage:** Matter, Z-Wave, BLE, and cloud integrations.\n* **Automation evolution:** versioned deployments, richer trigger/action/condition library, improved editor UX, and safe integration-provided automation steps.\n* **Smarter scheduling:** beyond cron (sunrise/sunset and other home-aware schedules).\n* **Scene \u0026 Mode Management:** grouped device state snapshots and home modes (Away / Night / Eco).\n* **Presence \u0026 Energy modules:** occupancy inference; energy usage aggregation.\n* **Integration marketplace model:** verified/unverified integrations, secure sandboxing for third-party widgets.\n* **Edge nodes:** lightweight agents pushing device state/events to the core cluster.\n\nContributions and feedback on these modules are welcome!\n\n---\n\n\u003ca id=\"quickstart\"\u003e\u003c/a\u003e\n## 4. 🐳 Quickstart\n\n```sh\ngit clone https://github.com/PetoAdam/homenavi.git\ncd homenavi\ncp .env.example .env   # adjust secrets / paths\ndocker compose up --build\n```\n\nIf you have a physical Zigbee USB adapter connected and configured, include the optional hardware profile:\n\n```sh\ndocker compose --profile zigbee-hardware up --build\n```\n\nBy default, the stack now uses **EMQX** as the main MQTT broker. If you need to connect Homenavi to an external MQTT deployment, load one or more bridge snippets from `emqx/bridge.d/*.hocon`. A fully commented starter lives at `emqx/bridge.d/homenavi-bridge.example.hocon`. See [doc/mqtt_broker_topologies.md](doc/mqtt_broker_topologies.md).\n\nEntry Points:\n* Frontend: http://localhost (served via Nginx)\n* API Gateway (REST): http://localhost/api\n* Prometheus: http://localhost:9090\n* Jaeger UI: http://localhost:16686\n* (Grafana optional) http://localhost:3000\n\nSee `doc/local_build.md` and `doc/nginx_guide.md` for deeper setup details.\n\n---\n\n\n## 5. 📂 Service Directory\n| Service | Path | Purpose | Docker Build Tag |\n|---------|------|---------|------------------|\n| API Gateway | `api-gateway/` | Request routing, auth verification, rate limiting, WS proxy | `homenavi-api-gateway:latest` |\n| Auth Service | `auth-service/` | Credentials, tokens, 2FA, lockout logic | `homenavi-auth-service:latest` |\n| User Service | `user-service/` | User profiles, roles, admin operations | `homenavi-user-service:latest` |\n| Dashboard Service | `dashboard-service/` | Per-user dashboards + widget persistence | `homenavi-dashboard-service:latest` |\n| Entity Registry Service | `entity-registry-service/` | Home inventory primitives and discovery surface | `homenavi-entity-registry-service:latest` |\n| Device Hub | `device-hub/` | Device inventory, HDP bridge over MQTT, metadata/state fan-out | `homenavi-device-hub:latest` |\n| History Service | `history-service/` | HDP device state persistence + query API for charts | `homenavi-history-service:latest` |\n| Automation Service | `automation-service/` | Automations/workflows service | `homenavi-automation-service:latest` |\n| Weather Service | `weather-service/` | Cached weather API (OpenWeather) | `homenavi-weather-service:latest` |\n| Email Service | `email-service/` | Sending verification / notification emails | `homenavi-email-service:latest` |\n| Profile Picture | `profile-picture-service/` | Avatar upload \u0026 processing | `homenavi-profile-picture-service:latest` |\n| Echo Service | `echo-service/` | WebSocket echo \u0026 diagnostic tool | `homenavi-echo-service:latest` |\n| Zigbee Adapter | `zigbee-adapter/` | Zigbee2MQTT adapter emitting/consuming HDP | `homenavi-zigbee-adapter:latest` |\n| Thread Adapter | `thread-adapter/` | Thread adapter placeholder (HDP hello/status/pairing) | `homenavi-thread-adapter:latest` |\n| Frontend | `frontend/` | SPA \u0026 PWA client | `homenavi-frontend:latest` |\n\nSupport:\n* `nginx/` reverse proxy templates.\n* `prometheus/` scrape config.\n* `emqx/` broker configuration, including gitignored bridge snippets loaded from `emqx/bridge.d/`.\n* `keys/` (DO NOT COMMIT PRIVATE KEYS IN PRODUCTION REPOS).\n* `doc/` guides and design docs.\n\n---\n\n## 6. 🔒 Security \u0026 Auth\nImplemented:\n* RS256 JWT (private signing in Auth Service, public verification at gateway).\n* Email-based 2FA workflow (TOTP planned).\n* Account \u0026 2FA attempt lockouts (structured 423 responses with remaining time).\n* Rate limiting (per-route \u0026 global) with Redis.\n* Standard JSON error format: `{ \"error\": string, \"code\"?: int, ... }` plus optional `reason`, `lockout_remaining`, `unlock_at`.\n\n---\n\n## 7. 📊 Observability\n* Metrics: Prometheus scrape (gateway, Go runtime, device hub, etc.).\n* Tracing: Jaeger via OpenTelemetry exporters.\n* Correlation: Request IDs / correlation IDs propagated across hops.\n* Health: Expose `/health` (liveness/readiness separation recommended for prod).\n* Device Hub exports its own `/metrics` endpoint and participates in the same trace pipeline.\n\n---\n\n## 8. ⚡ WebSockets \u0026 Real‑Time\n* Gateway upgrades authenticated using existing JWT (cookie-based flow supported).\n* Echo service demonstrates publishing \u0026 latency characteristics.\n* Device Hub uses MQTT topics for adapter input/output and connects via WebSockets to the UI.\n* Foundation for future real-time device state, automation events, and notifications.\n\nTest: `python3 test-websocket.py` (see root script).\n\n---\n\n## 9. 🔌 Extending the Platform\nIntegrations are **containers** that expose a manifest and optional UI surfaces:\n\n- The integration runs in the same Docker network as the stack.\n- `integration-proxy` reads `integrations/config/installed.yaml` and proxies `/integrations/\u003cid\u003e/...`.\n- The dashboard catalog merges integration widgets from `GET /integrations/registry.json`.\n\nTemplate repository (source of truth):\n\n- https://github.com/PetoAdam/homenavi-integration-template\n\nCurrent runtime model:\n\n- Integrations publish `/.well-known/homenavi-integration.json` (manifest).\n- UI surfaces are rendered in sandboxed iframes (tab + widget).\n- Same‑origin assets are served under `/integrations/\u003cid\u003e/...` via the proxy.\n- Automation actions execute by calling the integration container directly on the internal Docker network (not via `/integrations/\u003cid\u003e/...`).\n\n### Third-party integration development\n\nThird-party integrations should be built in their own repos using the official template:\n\n- https://github.com/PetoAdam/homenavi-integration-template\n\nDesign references for next-gen integrations (devices + automations + UI):\n\n- `doc/integration_device_and_automation_extensions.md`\n- `doc/poc_lg_thinq_integration_v2.md`\n\nRecommended workflow:\n\n1) Implement your integration and keep metadata in `marketplace/metadata.json`.\n2) Add the centralized CI actions from this repo:\n\t- Verify: `PetoAdam/homenavi/.github/actions/integration-verify@main`\n\t- Release: `PetoAdam/homenavi/.github/actions/integration-release@main`\n3) Tag a release (`vX.Y.Z`). The release workflow builds the image and publishes to the marketplace.\n\nRelease hardening (CI):\n\n- `verify.yml` is the primary quality gate (manifest/structure checks, tests, `go vet`, `gosec`, Docker build, and Trivy scan).\n- `release.yml` runs `verify.yml` as a required stage before publishing.\n- The shared `PetoAdam/homenavi/.github/actions/integration-release@main` action also enforces a central verify gate (`integration-verify` + `go vet` + `gosec`) so release validation cannot be bypassed by repo-local workflow edits.\n- Before marketplace publish, release enforces uniqueness checks, emits SBOM + provenance, and signs image digests with keyless Cosign.\n\nMarketplace publishing uses GitHub OIDC tokens (no repo secrets). The marketplace validates:\n\n- The OIDC token is from GitHub Actions for the tagging workflow.\n- The tag matches the payload `version` and `release_tag`.\n- The repo has a successful `verify.yml` workflow run for the tagged commit.\n\nMake sure your integration repo includes a `verify.yml` workflow and grants `id-token: write` in the release workflow so the OIDC token can be requested.\n\nSecurity note: when compose-managed installs are enabled, `integration-proxy` runs with Docker socket access and elevated privileges. Treat it as a high‑trust service and restrict access accordingly.\n\nJWT bootstrap behavior:\n\n- Docker Compose runs a one-shot `jwt-bootstrap` service before JWT-consuming services start. It verifies `keys/jwt_private.pem` and `keys/jwt_public.pem`, and generates them if needed via [scripts/ensure-jwt-keys.sh](scripts/ensure-jwt-keys.sh).\n- Helm/Kubernetes can do the same in-cluster: if no JWT secret is supplied, the pre-install/pre-upgrade hook in [helm/homenavi/templates/jwt-bootstrap-job.yaml](helm/homenavi/templates/jwt-bootstrap-job.yaml) creates the secret on first install and reuses it on later upgrades.\n\n### Integration proxy installation (recommended)\n\nUse the Admin → Integrations UI to install integrations from the marketplace and manage secrets. The proxy updates [integrations/config/installed.yaml](integrations/config/installed.yaml) automatically.\n\nRuntime policy: use one integration lifecycle runtime per environment.\n\n- Compose-based environment: manage integrations via Compose.\n- Kubernetes/Helm-based environment: manage integrations via Helm/Kubernetes artifacts.\n- Mixed runtime installs in a single environment are not supported.\n\nFirst-party integrations (for example Spotify and LG ThinQ) publish both `deployment_artifacts.compose` and `deployment_artifacts.helm` so install/update behavior is parity-first across Compose and Helm runtime modes.\n\nThe Helm chart defaults marketplace-backed integration installs to the public Homenavi marketplace at `marketplace.homenavi.org`. End users do not need to run the marketplace in their own cluster for normal installs. If you want Helm installs to resolve metadata from a local marketplace deployment for development, override `INTEGRATIONS_MARKETPLACE_API_BASE` as shown in [doc/minikube_helm_mvp_runbook.md](doc/minikube_helm_mvp_runbook.md).\n\nInstalled integrations track their installed `version` (and `auto_update` policy) in `installed.yaml`. Homenavi compares the installed version to the marketplace version (semver) to surface **Update available** and to support **Auto-update**.\n\nIf you run custom integrations manually, ensure the container is on the same Docker network and then use Admin → Integrations to add or refresh the entry.\n\n### Integration updates (admin-managed)\n\n- The Admin → Integrations UI shows installed vs latest marketplace version and provides an Update button.\n- Updates run asynchronously (queued) and the UI shows progress via the same status surface used during installs.\n- Auto-update can be enabled per integration; `integration-proxy` periodically checks the marketplace and applies updates when available.\n\n### Helm installation\n\nAn initial Helm chart scaffold is available at [helm/homenavi](helm/homenavi).\n\nReleased Helm charts are published to GHCR as OCI artifacts. For tagged releases, install directly from:\n\n- `oci://ghcr.io/petoadam/charts/homenavi`\n\nExample:\n\n```bash\nhelm install homenavi oci://ghcr.io/petoadam/charts/homenavi \\\n\t--version X.Y.Z \\\n\t-n homenavi --create-namespace\n```\n\nThe release chart defaults service image tags to the chart `appVersion`, so a chart release and its container images stay aligned by default.\n\nFor the current MVP goal (local Minikube Helm for core + marketplace), use the runbook at [doc/minikube_helm_mvp_runbook.md](doc/minikube_helm_mvp_runbook.md).\n\nThe local marketplace deployment in that runbook is for development and end-to-end testing only. In normal homelab installs, Homenavi uses the central marketplace service.\n\nFor single-namespace MVP deployment in one step, run [scripts/deploy-minikube.sh](scripts/deploy-minikube.sh).\n\nThe script supports Kubernetes-native secret ingestion from env files, installs the CloudNativePG operator when needed, and can inject a local EMQX bridge snippet into the Helm release:\n\n```bash\n./scripts/deploy-minikube.sh --env-file ./.env\n./scripts/deploy-minikube.sh --bridge-config-file ./emqx/bridge.d/20-external-bridge.hocon\n./scripts/deploy-minikube.sh --start-port-forwards\n```\n\nFor broker topology guidance, including the preferred direct-bridge pattern and EMQX bridge snippet layout, see [doc/mqtt_broker_topologies.md](doc/mqtt_broker_topologies.md).\n\nFor a safe starter template, use [k8s/secrets/homenavi.env.example](k8s/secrets/homenavi.env.example).\n\nDefault port-forward targets from the deploy script are stable for easier testing:\n\n- frontend: `http://localhost:50001`\n- marketplace: `http://localhost:50010`\n\nLegacy alias [scripts/deploy-minikube-planes.sh](scripts/deploy-minikube-planes.sh) now redirects to the current single-namespace deploy script.\n\nQuick start:\n\n```bash\nhelm upgrade --install homenavi ./helm/homenavi -n homenavi --create-namespace\n```\n\nValidation:\n\n```bash\nhelm lint ./helm/homenavi\nhelm template homenavi ./helm/homenavi \u003e /tmp/homenavi-rendered.yaml\n```\n\n### GitOps note for Kubernetes (ArgoCD/Flux)\n\nFor Kubernetes GitOps deployments, manage Homenavi and integrations in your GitOps repository (for example ArgoCD/Flux manifests/apps) and let reconciliation apply changes.\n\nIn this mode, do not use the marketplace install/update actions in the Homenavi UI as your source of truth.\n\nThis approach works when your GitOps repository includes the required integration artifacts/references and desired release configuration for each integration.\n\n### Integration secrets (admin-managed)\n\nIntegrations can declare the secrets they require in the manifest via a `secrets` array. The Admin → Integrations page uses this list to render write-only secret fields and sends values to each integration’s admin endpoint.\n\nIntegrations may also expose a **setup UI** flow (in addition to or instead of secrets) via `/api/admin/setup`.\n\nEach integration stores secrets in its own file (default `config/integration.secrets.json` in the integration repo/container, configurable with `INTEGRATION_SECRETS_PATH`). This prevents integrations from seeing each other’s secrets.\n\nSee the detailed architecture/roadmap: [doc/dashboard_widgets_integrations_marketplace_roadmap.md](doc/dashboard_widgets_integrations_marketplace_roadmap.md).\n\n---\n\n## 10. 🗺️ Roadmap (Condensed)\n\nMid Term:\n* More adapters (Matter/Z-Wave/BLE) and cloud integrations\n* Automation: versioning, richer step library, editor UX improvements\n* Scheduling upgrades (sunrise/sunset and other home-aware schedules)\n* Scenes \u0026 home modes (Away / Night / Eco)\n* Third-party integrations groundwork (catalog, sandboxing, verification model)\n* AI assistant service (local or cloud) for docs/config/dev support\n\nLong Term:\n* Edge node agent \u0026 secure tunneling\n* Energy analytics \u0026 occupancy inference\n* Plugin SDK + extension marketplace\n\n---\n\n## 11. ⚙️ Configuration \u0026 Environment\nEnvironment variables (selected):\n* `JWT_PRIVATE_KEY_PATH` / `JWT_PUBLIC_KEY_PATH`\n* Integrations / marketplace:\n\t* `INTEGRATIONS_MARKETPLACE_API_BASE` (defaults to `https://marketplace.homenavi.org`)\n\t* `INTEGRATIONS_UPDATE_CHECK_INTERVAL` (defaults to `15m`; set `0` to disable periodic checks)\n\t* `INTEGRATIONS_COMPOSE_ENABLED` (enables compose-managed install/update)\n\t* `INTEGRATIONS_COMPOSE_PULL_TIMEOUT` (defaults to `2m`, used for slow pulls)\n\t* `INTEGRATIONS_RUNTIME_MODE` (example: `compose`, `helm`, or `gitops` depending on deployment model)\n* Database connection vars (PostgreSQL)\n* Redis host/port\n* Email provider / SMTP credentials (for Email Service)\n* Weather:\n\t* `OPENWEATHER_API_KEY` (required for real weather data)\n\t* `WEATHER_CACHE_TTL_MINUTES` (optional, defaults to 15)\n\nExample: `cp .env.example .env` then edit. In production avoid storing secrets directly in env files—use a secrets manager.\n\nKey Management:\n```sh\nmkdir -p keys\nopenssl genpkey -algorithm RSA -out keys/jwt_private.pem -pkeyopt rsa_keygen_bits:2048\nopenssl rsa -pubout -in keys/jwt_private.pem -out keys/jwt_public.pem\n```\n\n---\n\n## 12. 📦 CI/CD\n* GitHub Actions per-service Docker build pipelines.\n* Builds produce Docker images and upload them as artifacts (image tarballs) for download/testing.\n* Future: Add lint (golangci-lint), security scanning (gosec, trivy), frontend tests.\n\n---\n\n## 13. 🤝 Contributing \u0026 Community\nContributions welcome:\n1. Fork \u0026 branch\n2. Make focused changes (tests appreciated)\n3. Open PR with rationale \u0026 scope\n\nDiscussions / Discord: (coming soon)\nIssues: https://github.com/PetoAdam/homenavi/issues\n\n---\n\n## 14. ❓ FAQ\n**Can I run it on a Raspberry Pi?** Yes—multi-arch images are the target; optimize build flags if needed.\n\n**Is it production ready?** Homenavi is under active development. The core authentication and user management features are stable, and device + automation layers are implemented, but the platform is still evolving—review the code for your specific use case.\n\n**Can I add my own device protocol now?** Yes, via a custom service publishing REST/WS endpoints through the gateway. The platform is designed to support new adapters and integrations with minimal changes.\n\n**Does it support real-time updates?** Yes—WebSockets already integrated; domain events layer planned.\n\n**Can I build my own automation engine or dashboard?** Yes—extend the platform with custom services, frontend modules, or plugins. The architecture is intentionally open for extension.\n\n**How do I contribute or request a feature?** Open an issue or PR on GitHub, or join the upcoming Discord community.\n\n**How do I run integration tests?** See `test/` for Python scripts covering device, auth, and WebSocket flows. Most tests require a running stack (`docker compose up`).\n\n---\n\n## 15. License\nMIT License © 2025 Adam Peto — See [LICENSE](LICENSE).\n\n### Icon attribution\n\nFont Awesome Free icons are used in the UI. Font Awesome is licensed under CC BY 4.0: https://fontawesome.com/license/free\n\n---\n\n\u003e This README describes current capabilities and the forward-looking smart home direction. Features marked “planned” are not yet implemented but inform architectural choices.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetoadam%2Fhomenavi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetoadam%2Fhomenavi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetoadam%2Fhomenavi/lists"}