mirror of
https://github.com/cassandra/home-information.git
synced 2026-06-11 09:05:00 -04:00
52999d9e99
* 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.
55 lines
1.9 KiB
Plaintext
55 lines
1.9 KiB
Plaintext
# Home Information environment configuration — EXAMPLE
|
|
#
|
|
# Format: docker-compose env_file (KEY=value). No `export`, no shell quoting,
|
|
# no ${VAR} interpolation. For developer shell-sourced env, run:
|
|
# ./deploy/env-generate.py --env-name development
|
|
#
|
|
# If you are installing via install.sh, you do NOT need this file —
|
|
# install.sh creates `~/.hi/env/local.env` for you with real values filled
|
|
# in. Do not manually place this file at `~/.hi/env/local.env`; install.sh
|
|
# will then treat your system as already-installed and refuse to proceed.
|
|
# This file exists as a reference for the variables that real env file
|
|
# will contain.
|
|
#
|
|
# If you are integrating Home Information into your own docker-compose stack
|
|
# (bypassing install.sh), copy this file alongside your compose file, fill
|
|
# in the placeholder values, and start the app.
|
|
#
|
|
# Required vs. optional is noted per section.
|
|
|
|
# --- Core Django (required) ---
|
|
DJANGO_SETTINGS_MODULE=hi.settings.local
|
|
DJANGO_SERVER_PORT=8000
|
|
DJANGO_SECRET_KEY=<replace-with-50-char-random-string>
|
|
|
|
# --- Admin user (required) ---
|
|
DJANGO_SUPERUSER_EMAIL=admin@example.com
|
|
DJANGO_SUPERUSER_PASSWORD=<replace-with-strong-password>
|
|
|
|
# --- Data paths inside the container (required; leave at defaults for the standard install) ---
|
|
HI_DB_PATH=/data/database
|
|
HI_MEDIA_PATH=/data/media
|
|
|
|
# --- Redis (required; defaults are correct for the bundled in-container Redis) ---
|
|
HI_REDIS_HOST=127.0.0.1
|
|
HI_REDIS_PORT=6379
|
|
HI_REDIS_KEY_PREFIX=
|
|
|
|
# --- Authentication (optional; "true" disables login for simple single-user setups) ---
|
|
HI_SUPPRESS_AUTHENTICATION=true
|
|
|
|
# --- Email / alerts (optional; leave HI_EMAIL_HOST empty to disable email notifications) ---
|
|
HI_EMAIL_SUBJECT_PREFIX=
|
|
HI_DEFAULT_FROM_EMAIL=
|
|
HI_SERVER_EMAIL=
|
|
HI_EMAIL_HOST=
|
|
HI_EMAIL_PORT=587
|
|
HI_EMAIL_HOST_USER=
|
|
HI_EMAIL_HOST_PASSWORD=
|
|
HI_EMAIL_USE_TLS=false
|
|
HI_EMAIL_USE_SSL=false
|
|
|
|
# --- Network (optional; needed when accessing beyond localhost) ---
|
|
HI_EXTRA_HOST_URLS=
|
|
HI_EXTRA_CSP_URLS=
|