* Add docker compose templates and env-var drift check (#382)
Phase 1 of issue #382 (docker compose support):
Repo-root templates for users integrating HI into their own compose stack:
- docker-compose.example.yml — published image, container_name: hi, $HOME/.hi
volume defaults; no healthcheck stanza (Dockerfile's HEALTHCHECK applies)
- local.env.example — generated from env-generate.py --example; preamble
explicitly warns install.sh users not to drop it at ~/.hi/env/local.env
Drift prevention across the three env-var sources:
- install.sh gains --list-env-vars, extracting names from its own heredoc via
a unique terminator (INSTALL_ENV_FILE_EOF) so the listing cannot drift from
what the script actually writes
- env-generate.py gains a SETTING_SECTIONS canonical declaration that seeds
self._settings_map and drives --example output; validate_settings() runs
before _write_file() and fails the run on undeclared keys or unset values
- deploy/env-drift-check.sh compares the three name sets and prints a clean
labeled diff on mismatch
- Wired into make env-drift-check, make check, and a CI step in
django-tests.yml
install.sh SECRET_KEY charset narrowed to exclude characters that can confuse
docker compose's env_file parser (\", ', \\, \$, #, =, \`).
* Add docker compose path to install.sh and update.sh (#382)
Phase 2 of issue #382 (docker compose support):
install.sh:
- check_docker_compose probes `docker compose version` (no install offer,
no platform branching)
- create_compose_file writes a fully-resolved compose file to
~/.hi/docker-compose.yml with container_name: hi so legacy
`docker logs/stop/start hi` work identically across both code paths
- Existing compose file is backed up to .BAK.<timestamp> before overwriting
(protects hand-edits for reverse-proxy labels, custom networks, etc.)
- start_container branches on HAS_COMPOSE: compose up -d when available,
original docker run when not
- show_success adds docker restart hi and the update.sh canonical update path
update.sh:
- Same check_docker_compose pattern
- update_via_compose runs `docker compose pull` then `up -d`
- Branches when both compose is available AND ~/.hi/docker-compose.yml
exists (pre-Phase-2 installs stay on the legacy recreation flow)
Container is named `hi` on both paths so post-install management commands
documented in `docs/Installation.md` work uniformly regardless of which
code path created the install.
* Split Installation.md into a simple-user doc and a Deployment.md (#382)
Phase 3 of issue #382 (docker compose support):
docs/Installation.md (290 → 123 lines):
- Quick Installation → Next Steps (moved from the bottom) → Managing your
installation → Updates → Environment Variable Changes → Removing your
installation → Troubleshooting
- "Managing your installation" fills the post-install management gap and
uses only legacy `docker logs/stop/start/restart hi` commands, which work
for both install-time code paths (the compose file is generated either
way and container_name: hi is set on both paths)
- Manual Installation section removed entirely; docs/dev/Setup.md already
covers `make docker-build/run` for the from-source/developer audience
- More Help points users at Deployment.md for advanced topics
docs/Deployment.md (new, 87 lines):
- Network Access Configuration
- Auto-Start on Reboot
- User Management
- Using docker compose directly (compose verbs as an equivalent alternative
to legacy docker commands)
- Integrating into your own compose stack (with the env-file format gotcha
spelled out: no export, no shell quoting, no ${VAR} interpolation)
- Pointer to the Integrations Guide
README.md:
- "Need more control?" updated to point at both Installation.md and
Deployment.md
- Resources → Users list adds Deployment Options
* Code-review polish and add env-var ritual doc (#382)
deploy/env-generate.py:
- validate_settings() moved from generate_env_file() into _write_file()
so any future code path that writes the env file is guarded
- Spacing fixes for project convention (inner spaces in update( { ... } ),
sorted( extra ) / sorted( missing ))
- "extra" error wording hints at typo in __init__ overlay as a possible
cause, not just "add to SETTING_SECTIONS"
- Drive-by colon spacing on the pre-existing HI_SUPPRESS_AUTHENTICATION
overlay key
docs/dev/shared/environment-variables.md (new):
- Documents the 4-place ritual when adding an env var dependency:
EnvironmentSettings (server.py), SETTING_SECTIONS + value assignment
(env-generate.py), install.sh heredoc, regenerated local.env.example
- Explains what make env-drift-check covers (three sources) and
what it deliberately does not (server.py — field names diverge by
design; other os.environ.get callers — caught only by review)
src/hi/environment/server.py:
- Pointer comment on EnvironmentSettings dataclass referencing the new doc
* Move dev init scripts into dev/ and make them self-locating
Two top-level scripts (init-env-dev.sh, init-claude.sh) carried hardcoded
personal paths that made them effectively unusable for other contributors,
and their visibility at the repo root suggested otherwise. Moved into
dev/ and rewritten to be portable:
dev/init-env-dev.sh:
- Computes PROJ_ROOT via BASH_SOURCE so absolute paths to
venv/bin/activate and .private/env/development.sh resolve regardless
of the caller's working directory
- Header comment now states the script must be sourced (the `return 1`
failure paths only behave correctly when sourced)
dev/init-claude.sh:
- Self-locates PROJ_ROOT the same way; the previous `cd ~/proj/hi`
personal hardcode is gone
- `export PATH="~/.local/bin:..."` → `export PATH="$HOME/.local/bin:..."`
(tilde inside double quotes does not expand)
- `gh auth status --hostname "$host"` → `--hostname github.com` (the
prior `$host` was undefined)
Unrelated to issue #382; bundled on this branch for convenience.
* More comment fixes.
* Refined comments for: src/hi/integrations/importer/*
* Comment refinements for: src/hi/integrations/referencer/
* Comment improvement pass on integrations templates.
* Cleaned up comments in src/hi/apps/weather/*.py
* Comment cleanup for src/hi/apps/weather/weather_sources
* Comment cleanup for src/hi/apps/profiles
* Some cleanup around claude files.
* Fixed some typos in variable names in weather module.
* MInor code consistency cleanup.
Developer docs mentioned Redis as a requirement without distinguishing
between local development (where you install it yourself) and Docker
deployment (where it is bundled and managed by supervisord). This caused
confusion for a user who set up an external Redis server not realizing
the Docker image already includes one.
Closes#241
* finished Items and Locations
* finish maintenance, labels and start notifier
* finish v1 of HomeBox Client API
* sync now creates and updates entities and entities attributes
* create sync for homebox item attachments
* finish homebox integration
* finish test implementation
* Improve Homebox API client quality and pattern conformance
Align the Homebox integration with patterns established by the existing
Home Assistant (HASS) integration, and fix several minor issues found
during code review of PR #249:
- Assert required API options in HbClient.__init__ instead of silently
logging a warning, matching the HASS client's defensive pattern
- Add warning log when login response lacks a token to aid debugging
- Translate Portuguese log message to English for consistency
- Reference HbClient constants in factory instead of magic strings
- Initialize all cache lists in HomeBoxManager.__init_singleton__
- Update factory test to work with constant references on mock class
* Fix sync bugs and remove dead code in Homebox converter
- Fix attachment order_id overlap: fields and attachments each
enumerated from 0 independently, causing interleaved display since
EntityAttribute orders by order_id. Attachments now start after the
last field index.
- Fix variable shadowing in _sync_helper_entity_attributes where the
loop variable 'hb_attachment' was immediately reassigned by tuple
unpacking on the next line.
- Remove unused _create_entity_attributes_from_hb_fields method, which
was superseded by the sync code using hb_item_to_attribute_field_list.
* Fix entity edit dialog for externally managed entities
HomeBox entities have non-editable attributes with disabled HTML form
fields. Browsers omit disabled fields from POST data, which caused
AttributeForm.clean() to see empty values and raise spurious validation
errors when updating the EntityType.
- Skip validation for non-editable attributes in AttributeForm.clean(),
since save() already short-circuits without writing for these
- Add suppress_add_new property to AttributeForm to control whether the
"Add New" attribute card is shown, following the existing pattern of
display-hint properties (suppress_history, show_as_editable, etc.)
- Pass can_add_custom_attributes through form_kwargs in the entity
formset so the form can suppress the add-new card for externally
managed entities even after a bound form re-render
* Add HomeBox integration to documentation
Add HomeBox alongside Home Assistant and ZoneMinder across all
user-facing and developer documentation: Integrations guide, Features,
FAQ, Installation, architecture overview, integration guidelines, and
service patterns.
Also remove stale reference to non-existent hi.services.weather module
from integration guidelines example list.
---------
Co-authored-by: Anthony Cassandra <github@cassandra.org>
* Bug fix and some documentation improvements.
* Addd model diagrams.
* Documentation Updates and DB utility scripts added.
* Updated documentation.
* Documentation refinements.
* Added new screenshot images and updated docs.
* Added linkk to helper data export scripts.
* Document design workflow process and update CLAUDE.md
- Add comprehensive design workflow documentation in docs/dev/workflow/design-workflow.md
- Update CLAUDE.md with design work documentation workflow section
- Establishes data/design/issue-{number}/ pattern for local work
- Documents GitHub issue attachment vs comment organization
- Provides reusable process for future design-focused issues
- Maintains repository cleanliness while enabling design iteration
* Snapshpt fo semi-working new entity and attribute edit modal.
* Refactored new forms to remove duplication. Fixed some textarea bugs.
* Fixed textarea attributes to prevent data corruption.
* Fixed new attribute validation error handling.
* Moved Entity attribute formset non-file filtering closer to def.
* Styling impovements.
* Added attribute value history browsing and restoring.
* Fixed styling on new entity edit modal header area.
* Refactored the messy and confusing new entity edit modal.
* Fixed icon in new attruibute form.
* Attribute Edit style changes.
* Fixed bad claude factoring. Fixed CSRF file upload issue.
* Added scroll-to in antinode.js whic helped fix file upload UX issue.
* Fixed styling of the add new attribute card for the 'mark as secret'.
* Added modified field forms styling for new entity edit modal.
* Fixed bug in secret attribute readonly editing logic.
* Added file attribute value editing to new entity edit modal.
* Removed legacy EntityEditView and related code.
* Refactor to remove EntityEditData.
* Refactor to rename: EntityDetailsData -> EntityEditModeData
* More refactoring for name change from "details" to "edit mode"
* Removed debug log messages. Doc typo fix.
* Refactored entity views to add helper classes.
* Coded cleanup and test fixes.
* Refactored to replace use of hardcoded DOM ids, classes, selectors.
* Refactorings: better naming removed debug messages.
* Renamed "property" to "attribute".
* Fixed unit test gaps.
* Replaced hardcoded form field prefixes with common access.
* Added EntityTransitionType to replace brittle "magic" strings.
* Tweaks on display names for entity edit modal.
* Added missing __init__.py to nested test dirs. (New failures found.)
* Working on fixing unit tests: checkpoint. WIP
* Fixed units tests
* Removed mocking from soem unit tests.
* Removed partial V2 implementation mistake from entity edit work.
* Added testing doc about lessons learned.
* Added a bunch of testing-related documentation.
* Fixed test expectation for LocationAttributeUploadView invalid upload
Updated test to expect 200 status with modal form response instead of 400 error, aligning with new form error handling behavior from entity attribute redesign.
