Home Information - Your home, your data, organized.
Python
Make docker compose the ongoing management surface (#382) (#394)
Tony C52999d9e99ec
diff --git a/.github/workflows/django-tests.yml b/.github/workflows/django-tests.ymlindex 9e2a1c0f..2218d456 100644--- a/.github/workflows/django-tests.yml+++ b/.github/workflows/django-tests.yml@@ -57,3 +57,7 @@ jobs:working-directory: ./srcrun: |flake8 . --config=.flake8-ci++ - name: Check Env-Var Drift+ run: |+ bash deploy/env-drift-check.shdiff --git a/Makefile b/Makefileindex 5d0488c9..bcffbb01 100644--- a/Makefile+++ b/Makefile@@ -1,6 +1,6 @@NOW_DATE := $(shell date -u +'%Y-%m-%dT%H:%M:%SZ')-SCRIPTS = deploy/env-generate.py deploy/run_container.sh+SCRIPTS = deploy/env-generate.py deploy/run_container.sh deploy/env-drift-check.sh.SECONDARY:@@ -18,7 +18,10 @@ lint:lint-strict:cd src && flake8 --config=.flake8 hi/ 2>/dev/null-check: lint test+env-drift-check:+ bash deploy/env-drift-check.sh++check: lint test env-drift-checkdocker-build: Dockerfile@HI_VERSION=$$(cat HI_VERSION); \@@ -48,7 +51,7 @@ env-build-dev: .private/env/development.sh fix-permissions.private/env/development.sh:-.PHONY: fix-permissions+.PHONY: fix-permissions env-drift-checkfix-permissions:@echo "Setting execute permissions for $(SCRIPTS)"diff --git a/README.md b/README.mdindex 08b0a4b7..4f0be9ec 100644--- a/README.md+++ b/README.md@@ -37,7 +37,7 @@ The install script automatically handles everything: Docker setup verification,**New to the interface?** Follow the [Getting Started Guide](docs/GettingStarted.md) for a walkthrough.-**Need more control?** See [Installation Guide](docs/Installation.md) for manual installation, deployment options, and troubleshooting.+**Need more control?** See the [Installation Guide](docs/Installation.md) and [Deployment Options](docs/Deployment.md) for more options.## What You Can Do@@ -108,12 +108,13 @@ For technical details, see our [Development Documentation](docs/Development.md).## Resources### Users-- [Installation](docs/Installation.md) - Complete setup instructions+- [Installation](docs/Installation.md) - Setup, day-to-day management, updates, troubleshooting- [Features](docs/Features.md) - Complete feature overview-- [FAQ](docs/FAQ.md) - Common questions and answers-- [Getting Started](docs/GettingStarted.md) - First-time user walkthrough+- [Getting Started](docs/GettingStarted.md) - First-time user walkthrough- [Layout Editor](docs/Editing.md) - Show how to use the layout editor- [Integrations](docs/Integrations.md) - Home Assistant and ZoneMinder setup+- [Deployment Options](docs/Deployment.md) - Network access, custom compose stacks, production configuration+- [FAQ](docs/FAQ.md) - Common questions and answers### Contributors- [Contributing](CONTRIBUTING.md) - How to get involveddiff --git a/deploy/env-drift-check.sh b/deploy/env-drift-check.shnew file mode 100755index 00000000..1cac01c2--- /dev/null+++ b/deploy/env-drift-check.sh@@ -0,0 +1,47 @@+#!/bin/bash+# Verify that install.sh, deploy/env-generate.py, and local.env.example all+# declare the same set of environment variable names. Drift in any direction+# indicates a missed update and is treated as a build failure.+#+# Compared as sets (sorted, unique) — values are ignored; only names matter.+set -euo pipefail++cd "$( dirname "${BASH_SOURCE[0]}" )/.."++extract_var_names_from_env_text() {+ # Read an env-file-shaped stream from stdin, emit just the variable names+ # (lines matching ^KEY=...). Comments and blank lines are dropped.+ grep -E '^[A-Z][A-Z0-9_]+=' | sed 's/=.*//' | sort -u+}++install_sh_names=$( bash install.sh --list-env-vars )+env_generate_names=$( python3 deploy/env-generate.py --example | extract_var_names_from_env_text )+example_file_names=$( extract_var_names_from_env_text < local.env.example )++show_diff_and_fail() {+ local label_a="$1" set_a="$2" label_b="$3" set_b="$4"+ echo+ echo "Env-var drift detected between ${label_a} and ${label_b}:"+ diff -u \+ <( printf '%s\n' "${set_a}" ) \+ <( printf '%s\n' "${set_b}" ) \+ | sed "s|^---.*|--- ${label_a}|; s|^+++.*|+++ ${label_b}|" || true+ echo+ echo "Fix: update whichever source is behind so all three declare the same set."+ exit 1+}++if [[ "${install_sh_names}" != "${env_generate_names}" ]]; then+ show_diff_and_fail \+ "install.sh --list-env-vars" "${install_sh_names}" \+ "deploy/env-generate.py --example" "${env_generate_names}"+fi++if [[ "${install_sh_names}" != "${example_file_names}" ]]; then+ show_diff_and_fail \+ "install.sh --list-env-vars" "${install_sh_names}" \+ "local.env.example" "${example_file_names}"+fi++count=$( printf '%s\n' "${install_sh_names}" | wc -l | tr -d '[:space:]' )+echo "env-drift-check: OK (${count} variables consistent across install.sh, env-generate.py, and local.env.example)"diff --git a/deploy/env-generate.py b/deploy/env-generate.pyindex 47aa9f45..2734362e 100755--- a/deploy/env-generate.py+++ b/deploy/env-generate.py@@ -118,6 +118,88 @@ class HiEnvironmentGenerator:MEDIA_SUBDIR = 'media'SH_FILE_SUFFIX = 'sh'+ # Canonical declaration of every env var this script writes. Seeds+ # `self._settings_map`, drives `--example` output, and is the reference+ # set validate_settings() compares against. Any new var must be added here+ # AND assigned a value during generate_env_file() — otherwise the run+ # fails. Entries are+ # ( section_heading, requirement_note, [ ( var_name, placeholder ) ] ).+ SETTING_SECTIONS = [+ ( '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', '[email protected]' ),+ ( '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', '' ),+ ] ),+ ]++ EXAMPLE_HEADER = (+ '# Home Information environment configuration — EXAMPLE\n'+ '#\n'+ '# Format: docker-compose env_file (KEY=value). No `export`, no shell quoting,\n'+ '# no ${VAR} interpolation. For developer shell-sourced env, run:\n'+ '# ./deploy/env-generate.py --env-name development\n'+ '#\n'+ '# If you are installing via install.sh, you do NOT need this file —\n'+ '# install.sh creates `~/.hi/env/local.env` for you with real values filled\n'+ '# in. Do not manually place this file at `~/.hi/env/local.env`; install.sh\n'+ '# will then treat your system as already-installed and refuse to proceed.\n'+ '# This file exists as a reference for the variables that real env file\n'+ '# will contain.\n'+ '#\n'+ '# If you are integrating Home Information into your own docker-compose stack\n'+ '# (bypassing install.sh), copy this file alongside your compose file, fill\n'+ '# in the placeholder values, and start the app.\n'+ '#\n'+ '# Required vs. optional is noted per section.\n'+ )++ @classmethod+ def _declared_var_names( cls ):+ return [ name for _h, _r, entries in cls.SETTING_SECTIONS for name, _v in entries ]++ @classmethod+ def print_example_env_file( cls ):+ sys.stdout.write( cls.EXAMPLE_HEADER )+ for heading, requirement, entries in cls.SETTING_SECTIONS:+ sys.stdout.write( f'\n# --- {heading} ({requirement}) ---\n' )+ for name, value in entries:+ sys.stdout.write( f'{name}={value}\n' )+ return+def __init__( self,env_name : str = 'local',verbose : bool = False ):@@ -125,27 +207,62 @@ class HiEnvironmentGenerator:if env_name not in [ 'development', 'local', 'staging', 'production' ]:self.print_warning( f'Non-standard environment name "{env_name}".'f' Ensure that the file "hi/settings/{env_name}.py" exists.' )-+self._env_name = env_nameself._env_config = EnvironmentConfig.get( self._env_name )self._verbose = verbose-- self._settings_map = {++ # Seed every declared var with None. The defaults below and the+ # interactive flow in generate_env_file() fill in real values;+ # validate_settings() catches both undeclared additions and missed+ # assignments.+ self._settings_map = { name: None for name in self._declared_var_names() }+ self._settings_map.update( {'DJANGO_SETTINGS_MODULE': f'hi.settings.{self._env_name}','DJANGO_SERVER_PORT': self._env_config.django_server_port,- 'HI_SUPPRESS_AUTHENTICATION':'true',+ 'HI_SUPPRESS_AUTHENTICATION': 'true','HI_REDIS_HOST': '127.0.0.1','HI_REDIS_PORT': '6379','HI_REDIS_KEY_PREFIX': self._env_config.redis_key_prefix,'HI_EMAIL_SUBJECT_PREFIX': self._env_config.redis_subject_prefix,'HI_EXTRA_HOST_URLS': '', # To be filled in manually if/when running beyond localhost'HI_EXTRA_CSP_URLS': '', # To be filled in manually if/when running beyond localhost- }+ } )self._destination_filename = os.path.join(self._env_config.secrets_directory,f'{self._env_name}.{self._env_config.secrets_suffix}',)return++ def validate_settings( self ):+ declared = set( self._declared_var_names() )+ actual = set( self._settings_map.keys() )++ extra = actual - declared+ if extra:+ raise RuntimeError(+ f'Internal drift: settings_map contains keys not declared in '+ f'SETTING_SECTIONS: {sorted( extra )}. Either add them to '+ f'SETTING_SECTIONS or fix the key name (a typo in the __init__ '+ f'overlay or in generate_env_file() can also surface here).'+ )++ missing = declared - actual+ if missing:+ raise RuntimeError(+ f'Internal drift: SETTING_SECTIONS declares keys not present in '+ f'settings_map: {sorted( missing )}. Either remove from '+ f'SETTING_SECTIONS or assign a value in generate_env_file().'+ )++ unset = sorted( k for k, v in self._settings_map.items() if v is None )+ if unset:+ raise RuntimeError(+ f'Internal drift: settings_map has unset (None) values: {unset}. '+ f'These keys are declared in SETTING_SECTIONS but never assigned '+ f'during generate_env_file().'+ )+ returndef generate_env_file( self ):@@ -193,7 +310,7 @@ class HiEnvironmentGenerator:self._settings_map['HI_EMAIL_PORT'] = str(email_settings.smtp_settings.port)self._settings_map['HI_EMAIL_USE_TLS'] = str(email_settings.smtp_settings.use_tls)self._settings_map['HI_EMAIL_USE_SSL'] = str(email_settings.smtp_settings.use_ssl)-+self._write_file()self.print_important( f'Review your settings file: {self._destination_filename}' )@@ -427,6 +544,11 @@ class HiEnvironmentGenerator:def _write_file( self ):+ # Validate at the act of writing so any code path that produces a file+ # (current or future) is guarded against internal drift between+ # SETTING_SECTIONS and the populated settings_map.+ self.validate_settings()+is_sh_file = self._destination_filename.endswith( self.SH_FILE_SUFFIX )# Use atomic write with temporary file for safety@@ -639,6 +761,11 @@ def parse_command_line_args():action = 'store_true',help = 'Enable verbose output for debugging purposes.',)+ parser.add_argument(+ '--example',+ action = 'store_true',+ help = 'Print an example env file (compose env_file format) to stdout and exit.',+ )args, unknown = parser.parse_known_args()@@ -657,9 +784,12 @@ def parse_command_line_args():if __name__ == '__main__':args = parse_command_line_args()+ if args.example:+ HiEnvironmentGenerator.print_example_env_file()+ sys.exit( 0 )generator = HiEnvironmentGenerator(env_name = args.env_name,verbose = args.verbose,)generator.generate_env_file()-+diff --git a/dev/init-claude.sh b/dev/init-claude.shnew file mode 100755index 00000000..96c82e68--- /dev/null+++ b/dev/init-claude.sh@@ -0,0 +1,23 @@+#!/bin/bash+# Launch Claude Code from the project root with the dev environment active.+# Activates the venv, loads dev env vars, ensures gh auth, then starts claude.++PROJ_ROOT="$( cd "$( dirname "${BASH_SOURCE[0]}" )/.." && pwd )"++export PATH="$HOME/.local/bin:$PATH"+cd "$PROJ_ROOT"+. "$PROJ_ROOT/dev/init-env-dev.sh"++# Check GitHub login status and re-auth if necessary.+if ! gh auth status --hostname github.com >/dev/null 2>&1; then+ if [[ -n "${GH_TOKEN:-${GITHUB_TOKEN:-}}" ]]; then+ printf '%s' "${GH_TOKEN:-$GITHUB_TOKEN}" | gh auth login --hostname github.com --with-token+ else+ # interactive web login+ gh auth login --hostname github.com --web+ fi+else+ echo "✓ GitHub Authorization"+fi++claudediff --git a/dev/init-env-dev.sh b/dev/init-env-dev.shnew file mode 100644index 00000000..62ead84b--- /dev/null+++ b/dev/init-env-dev.sh@@ -0,0 +1,31 @@+# Source this script (do not execute it) to activate the project venv and+# load development environment variables. Idempotent — safe to source+# multiple times in the same shell.++PROJ_ROOT="$( cd "$( dirname "${BASH_SOURCE[0]}" )/.." && pwd )"++# Only activate virtual environment if not already active.+# This prevents shell prompt nesting and makes the script idempotent.+if [ -z "$VIRTUAL_ENV" ]; then+ if [ -f "$PROJ_ROOT/venv/bin/activate" ]; then+ . "$PROJ_ROOT/venv/bin/activate"+ echo "✓ Virtual environment activated"+ else+ echo "ERROR: Virtual environment not found at $PROJ_ROOT/venv/bin/activate"+ echo "Please create it first: python3.11 -m venv venv"+ return 1+ fi+else+ echo "✓ Virtual environment already active: $VIRTUAL_ENV"+ echo " (Hint: run 'deactivate' first if you need to switch environments)"+fi++# Source development environment variables+if [ -f "$PROJ_ROOT/.private/env/development.sh" ]; then+ . "$PROJ_ROOT/.private/env/development.sh"+ echo "✓ Development environment variables loaded"+else+ echo "ERROR: Environment file not found at $PROJ_ROOT/.private/env/development.sh"+ echo "Please create it first: make env-build-dev"+ return 1+fidiff --git a/docker-compose.example.yml b/docker-compose.example.ymlnew file mode 100644index 00000000..e5ee08e1--- /dev/null+++ b/docker-compose.example.yml@@ -0,0 +1,36 @@+# Home Information — example docker-compose file+#+# This is a TEMPLATE, not a live config. It is named `.example.yml` so that+# `docker compose` does not auto-discover it. To use:+#+# 1. Copy this file to where you want to manage the app from+# (e.g. `cp docker-compose.example.yml docker-compose.yml`)+# 2. Copy `local.env.example` to `local.env` and fill in the placeholders+# (or generate values via `deploy/env-generate.py` or `install.sh`)+# 3. Adjust the volume host paths to your data directory+# 4. `docker compose up -d`+#+# If you ran install.sh, your live config is at `~/.hi/docker-compose.yml` —+# edit that, not this. This file is here only as a reference for users who want+# to integrate Home Information into their own compose stack.+#+# No `healthcheck:` stanza is declared — the Dockerfile already defines one+# (HEALTHCHECK on /health) and a compose-level stanza would override it,+# creating drift. `docker compose ps` shows the container's health using the+# Dockerfile's healthcheck.++services:+ hi:+ image: ghcr.io/cassandra/home-information:latest+ container_name: hi+ restart: unless-stopped+ ports:+ - "9411:8000"+ env_file:+ - ./local.env+ volumes:+ # Edit these paths to point at where you want HI's data stored.+ # Defaults match install.sh's location (~/.hi/) for consistency, using+ # $HOME because tilde (~) does not reliably expand in compose volume paths.+ - $HOME/.hi/database:/data/database+ - $HOME/.hi/media:/data/mediadiff --git a/docs/Deployment.md b/docs/Deployment.mdnew file mode 100644index 00000000..200903ca--- /dev/null+++ b/docs/Deployment.md@@ -0,0 +1,84 @@+<img src="../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">++# Deployment Options++Production configuration and self-hosting options beyond a single-machine localhost install. This guide assumes you already have a working installation per the [Installation Guide](Installation.md).++## Network Access Configuration++By default, the app only accepts requests addressed to `localhost`. To access it from another device on your network (by IP address or hostname), edit `~/.hi/env/local.env` and add the URLs you'll use:++```shell+# Example: accessing via IP address and hostname+HI_EXTRA_HOST_URLS="http://192.168.1.100:9411 http://home-server:9411"+```++Multiple URLs are space-separated. After saving, restart the app: `docker restart hi`.++If you see `Invalid HTTP_HOST header` errors in the logs, this is the setting you need.++## Auto-Start on Reboot++The Docker container is configured to restart automatically (`--restart unless-stopped`), but Docker itself needs to start on boot:++**macOS (Docker Desktop):**++```+Docker Desktop → Settings → General → "Start Docker Desktop when you log in"+```++**Linux (Ubuntu/systemd):**++```shell+# Check if enabled+systemctl is-enabled docker++# Enable if needed+sudo systemctl enable docker+```++## User Management++If you enabled user authentication, create user accounts via the Django admin interface:++1. Sign in at [http://localhost:9411/admin/](http://localhost:9411/admin/) using:+ - Email: `DJANGO_SUPERUSER_EMAIL` (from your env file)+ - Password: `DJANGO_SUPERUSER_PASSWORD` (from your env file)++2. Add users at: [http://localhost:9411/admin/custom/customuser/add/](http://localhost:9411/admin/custom/customuser/add/)++**Requirements:** Email configuration must be working (users receive "magic code" login links).++## Using docker compose directly++If you already use docker compose to manage your services, you may prefer compose verbs over the `docker logs hi` / `docker stop hi` commands documented in the Installation Guide. They are equivalent — `install.sh` generates a compose file at `~/.hi/docker-compose.yml`, so you can use either set of commands interchangeably.++```shell+cd ~/.hi+docker compose ps # status+docker compose logs -f # follow logs+docker compose restart # restart+docker compose down # stop and remove the container+docker compose up -d # bring it back+docker compose pull && docker compose up -d # update to latest image+```++If `docker compose` was not installed when you first ran `install.sh`, you can install it later and start using these commands immediately — the compose file is written either way.++## Integrating into your own compose stack++If you already manage your services with a single docker compose file (or directory of files), you can run Home Information from that stack instead of using `install.sh`.++Reference files in the repository root:++- [`docker-compose.example.yml`](../docker-compose.example.yml) — minimal service definition for the published image, with volumes and env file+- [`local.env.example`](../local.env.example) — the full env-var surface with placeholder values and inline documentation++Copy both files into your stack, fill in the placeholder values in `local.env`, then start the app with your usual compose commands.++**Important format note:** docker compose's `env_file` parser is **not** the same as shell-sourced env files. No `export`, no shell-style quoting (single or double quotes), no `${VAR}` interpolation. `local.env.example` is in the correct format; do not adapt a shell-sourced env file by hand without removing those features.++## Integrations++Connect Home Information with your existing home automation, security and document systems. See the [Integrations Guide](Integrations.md) for setup instructions.+diff --git a/docs/Installation.md b/docs/Installation.mdindex 87ceb6e0..e665c957 100644--- a/docs/Installation.md+++ b/docs/Installation.md@@ -2,7 +2,7 @@# Installation Guide-Complete installation instructions for Home Information, from quick setup to advanced deployment.+How to install Home Information and manage your installation day-to-day. For deployment beyond localhost (network access, custom compose stacks, production configuration), see [Deployment Options](Deployment.md).## Prerequisites@@ -30,190 +30,62 @@ curl -fsSL https://raw.githubusercontent.com/cassandra/home-information/master/i- Database: `~/.hi/database/`- Files: `~/.hi/media/`-### Updates--```shell-curl -fsSL https://raw.githubusercontent.com/cassandra/home-information/master/update.sh | bash-```--This preserves all your data while updating to the latest version.--### Environment Variable Changes--If you used the one-liner `install.sh` script and need to change your environment variables, you'll need to re-run in docker to pick up the changes. The install script runs docker with this command:-```-docker run -d \- --name "${CONTAINER_NAME}" \- --restart unless-stopped \- --env-file "${ENV_FILE}" \- -v "${DATABASE_DIR}:/data/database" \- -v "${MEDIA_DIR}:/data/media" \- -p "${EXTERNAL_PORT}:8000" \- "${DOCKER_IMAGE}:${DOCKER_TAG}"-```-Where the environment variables you need are:-```-CONTAINER_NAME="hi"-HI_HOME="${HOME}/.hi"-ENV_DIR="${HI_HOME}/env"-ENV_FILE="${ENV_DIR}/local.env"-DATABASE_DIR="${HI_HOME}/database"-MEDIA_DIR="${HI_HOME}/media"-EXTERNAL_PORT="9411"-DOCKER_IMAGE="ghcr.io/cassandra/home-information"-DOCKER_TAG="${1:-latest}"-```--## Manual Installation--For users who want full control over the installation process or need to customize the setup.--### Before You Start--**Default configuration** is designed for simplicity - no user authentication, no email alerts. You can enable these later by modifying the environment file.--**Optional features to consider:**-- **Email alerts** - Get notifications when away from home (requires email provider configuration)-- **User authentication** - Require login via emailed "magic codes" (requires email configuration)--Both can be configured during manual setup or added later by editing `~/.hi/env/local.env`.--### Step-by-Step Manual Installation--#### 1. Download and Extract--Choose your project directory:-```shell-PROJ_DIR="proj"-mkdir -p $PROJ_DIR && cd $PROJ_DIR-```--Download latest release from: https://github.com/cassandra/home-information/releases/latest+## Next Steps-Extract the code:-```shell-# Download method depends on your preference-curl -L https://github.com/cassandra/home-information/releases/latest/download/home-information.zip -o home-information.zip-unzip home-information.zip && cd home-information*+With your installation running, see the [Getting Started Guide](GettingStarted.md) to:+- Create your first home layout+- Add devices and information+- Set up monitoring and alerts-# Alternative: tarball-# tar zxvf ~/Downloads/home-information-*.tar.gz && cd home-information*-```+## Managing your installation-#### 2. Configure Environment+Manage the running app with standard Docker commands:-Generate environment configuration (includes secure admin credentials):```shell-make env-build+docker logs hi # view logs (add -f to follow)+docker stop hi # stop the app+docker start hi # start it again+docker restart hi # restart (e.g. after changing the env file)+docker ps | grep hi # status / health```-This creates: `$HOME/.hi/env/local.env` with all necessary settings and credentials.+**Your files:**-#### 3. Build and Run--Build the Docker image:-```shell-make docker-build-```+- Configuration: `~/.hi/env/local.env`+- Database: `~/.hi/database/`+- Uploaded media: `~/.hi/media/`-Start the application:-```shell-# Foreground (recommended for first run - shows errors)-make docker-run-fg+## Updates-# OR background-make docker-run-```+Run the update script — it pulls the latest image and recreates the container, preserving your data:-Stop when needed:```shell-make docker-stop+curl -fsSL https://raw.githubusercontent.com/cassandra/home-information/master/update.sh | bash```-#### 4. Access Your Installation--**URL:** [http://localhost:9411](http://localhost:9411)--**Credentials:** Found in `$HOME/.hi/env/local.env`--**Data location:**-- Database: `$HOME/.hi/database/hi.sqlite3`-- Files: `$HOME/.hi/media`+## Environment Variable Changes-### Manual Installation Updates+Edit your configuration file at `~/.hi/env/local.env`, then restart the app to pick up the changes:-**Easiest:** Use the update script (works for any installation type):```shell-curl -fsSL https://raw.githubusercontent.com/cassandra/home-information/master/update.sh | bash+docker restart hi```-**Manual steps:**-```shell-cd $PROJ_DIR/home-information*--# Get latest code (download new release)-# Then rebuild and restart:-make docker-build-make docker-stop && make docker-run-```+If you changed network settings such as `HI_EXTRA_HOST_URLS`, see the [Deployment Options](Deployment.md) guide for related configuration.-## Production Deployment+## Removing your installation-Ready to deploy beyond localhost? Here's what you need to configure.--### Network Access Configuration--Edit `$HOME/.hi/env/local.env` to add your deployment URLs:```shell-# Example: accessing via IP address and hostname-HI_EXTRA_HOST_URLS="http://192.168.1.100:9411 http://home-server:9411"+docker stop hi+docker rm hi```-### Auto-Start on Reboot--The Docker container is configured to restart automatically, but Docker itself needs to start on boot:+To also remove your data and configuration (this is permanent):-**macOS (Docker Desktop):**-```-Docker Desktop → Settings → General → "Start Docker Desktop when you log in"-```--**Linux (Ubuntu/systemd):**```shell-# Check if enabled-systemctl is-enabled docker--# Enable if needed-sudo systemctl enable docker+rm -rf ~/.hi/```-### User Management (Optional)--If you enabled user authentication, you'll need to create user accounts manually via the Django admin interface:--1. Sign in at [http://localhost:9411/admin/](http://localhost:9411/admin/) using:- - Email: `DJANGO_SUPERUSER_EMAIL` (from your env file)- - Password: `DJANGO_SUPERUSER_PASSWORD` (from your env file)--2. Add users at: [http://localhost:9411/admin/custom/customuser/add/](http://localhost:9411/admin/custom/customuser/add/)--**Requirements:** Email configuration must be working (users receive "magic code" login links)--### Integrations--Connect Home Information with your existing home automation and security systems. See the [Integrations Guide](Integrations.md) for setup instructions:-- **Home Assistant** - Device control and monitoring-- **ZoneMinder** - Security camera management-- **HomeBox** - Home inventory management--## Next Steps--### First-Time Setup-With your installation running, see the [Getting Started Guide](GettingStarted.md) for:-- Creating your first home layout-- Adding devices and information-- Setting up monitoring and alerts-## Troubleshooting### Common Issues@@ -225,7 +97,7 @@ By default, the app only accepts requests to `localhost`. To access it from othe- Set `HI_EXTRA_HOST_URLS` to the URL(s) you'll use to access the app, including the scheme and port- Example: `HI_EXTRA_HOST_URLS="http://192.168.1.100:9411"` (use your server's actual IP)- Multiple URLs can be space-separated: `HI_EXTRA_HOST_URLS="http://192.168.1.100:9411 http://myserver.local:9411"`-- For standalone Docker: edit `$HOME/.hi/env/local.env` and restart with `make docker-stop && make docker-run`+- For standalone Docker: edit `$HOME/.hi/env/local.env` and run `docker restart hi`- For unRAID: set the "Extra Host URLs" field under "Show more settings"If you see `Invalid HTTP_HOST header` errors in the logs, this is the setting you need.@@ -246,5 +118,6 @@ HI_EMAIL_USE_TLS=true### More Help+- **Deployment beyond localhost** (network access, auto-start, custom compose stack, user management): [Deployment Options](Deployment.md)- **Detailed troubleshooting:** [FAQ](FAQ.md)- **Feature questions:** [Features](Features.md)diff --git a/docs/dev/shared/environment-variables.md b/docs/dev/shared/environment-variables.mdnew file mode 100644index 00000000..beb6688d--- /dev/null+++ b/docs/dev/shared/environment-variables.md@@ -0,0 +1,46 @@+# Environment Variables++Adding (or removing, or renaming) an environment variable that the app reads touches **four** files. The cross-source drift check covers three of them automatically; the fourth — the app-side dataclass — relies on code review.++## When to read this++Any time you add a new env-var dependency in app code: new integration credentials, a new feature flag, a new config knob. If the app reads it from `os.environ` (directly or via `EnvironmentSettings`), the ritual below applies.++## Files to update++In recommended order:++1. **`src/hi/environment/server.py`** — `EnvironmentSettings` dataclass. Add a field with type and default. Use `= None` for required vars (absence raises `ImproperlyConfigured`); use an empty/zero/false default for optional.++ Field names are intentionally **not** required to match env-var names — `EnvironmentSettings.SECRET_KEY` reads `DJANGO_SECRET_KEY`, `EnvironmentSettings.REDIS_HOST` reads `HI_REDIS_HOST`, etc. The mapping (prefix-stripping and any explicit rename) is handled inside `EnvironmentSettings`. Pick a field name that reads naturally in app code; the env-var name follows the project's `HI_` / `DJANGO_` convention.++2. **`deploy/env-generate.py`** — two edits in the same file:+ - Add an entry to `SETTING_SECTIONS` under the appropriate section (or add a new section). Include a placeholder value and inline guidance on required vs. optional.+ - Assign a real value for the var, either in the `__init__` overlay (`self._settings_map.update(...)`) for vars with a fixed default, or in `generate_env_file()` for vars filled in by interactive prompts.++ `validate_settings()` fails the run if a var is declared in `SETTING_SECTIONS` but never assigned (or vice versa), so this step is self-checking the moment you run `make env-build`.++3. **`install.sh`** — the heredoc between `<< INSTALL_ENV_FILE_EOF` and `INSTALL_ENV_FILE_EOF` (the unique terminator lets `install.sh --list-env-vars` extract names unambiguously). Add a `KEY=value` line. Use a literal default for fixed-value vars or `${SHELL_VAR}` interpolation for generated values (e.g. `DJANGO_SECRET_KEY=${DJANGO_SECRET_KEY}`).++4. **`local.env.example`** at the repo root — **do not hand-edit**. Regenerate from `env-generate.py`:++ ```shell+ python3 deploy/env-generate.py --example > local.env.example+ ```++## Verification++After the four edits, run the drift check:++```shell+make env-drift-check+```++It compares the variable-name sets across `install.sh`, `deploy/env-generate.py`, and `local.env.example` and fails with a labeled diff on mismatch. Also wired into `make check` and the `Check Env-Var Drift` step in `.github/workflows/django-tests.yml`.++## What drift-check does *not* cover++- **`EnvironmentSettings` (server.py)** — field names diverge from env-var names by design, so a structural cross-check would either be lossy or require a rename map per field. Verifying the dataclass change matches the env-var change is a **code-review responsibility**.+- **Other code paths that read `os.environ` directly** — app code should route env access through `EnvironmentSettings`, but nothing enforces it. If a contributor adds an `os.environ.get('HI_SOMETHING_NEW')` call elsewhere, only review catches it.++If a var reaches production without `install.sh` and the example file knowing about it, users won't have it set. The drift check is the first line; code review is the second.diff --git a/init-claude.sh b/init-claude.shdeleted file mode 100755index 3da97318..00000000--- a/init-claude.sh+++ /dev/null@@ -1,20 +0,0 @@-#!/bin/bash--export PATH="~/.local/bin:$PATH"-cd ~/proj/hi-. ./init-env-dev.sh--# Check GitHub login status and re-auth if necessary.-# gh auth login-if ! gh auth status --hostname "$host" >/dev/null 2>&1; then- if [[ -n "${GH_TOKEN:-${GITHUB_TOKEN:-}}" ]]; then- printf '%s' "${GH_TOKEN:-$GITHUB_TOKEN}" | gh auth login --hostname "$host" --with-token- else- # interactive web login- gh auth login --hostname "$host" --web- fi-else- echo "✓ GitHub Authorization"-fi--claudediff --git a/init-env-dev.sh b/init-env-dev.shdeleted file mode 100644index 4e830e8f..00000000--- a/init-env-dev.sh+++ /dev/null@@ -1,25 +0,0 @@-# Only activate virtual environment if not already active-# This prevents shell prompt nesting and makes the script idempotent-if [ -z "$VIRTUAL_ENV" ]; then- if [ -f "venv/bin/activate" ]; then- . venv/bin/activate- echo "✓ Virtual environment activated"- else- echo "ERROR: Virtual environment not found at venv/bin/activate"- echo "Please create it first: python3.11 -m venv venv"- return 1- fi-else- echo "✓ Virtual environment already active: $VIRTUAL_ENV"- echo " (Hint: run 'deactivate' first if you need to switch environments)"-fi--# Source development environment variables-if [ -f ".private/env/development.sh" ]; then- . .private/env/development.sh- echo "✓ Development environment variables loaded"-else- echo "ERROR: Environment file not found at .private/env/development.sh"- echo "Please create it first: make env-build-dev"- return 1-fidiff --git a/install.sh b/install.shindex c5d6c4fc..66c54f6d 100755--- a/install.sh+++ b/install.sh@@ -15,6 +15,8 @@ ENV_DIR="${HI_HOME}/env"DATABASE_DIR="${HI_HOME}/database"MEDIA_DIR="${HI_HOME}/media"ENV_FILE="${ENV_DIR}/local.env"+COMPOSE_FILE="${HI_HOME}/docker-compose.yml"+HAS_COMPOSE=0 # Set by check_docker_compose; 1 if `docker compose` is available.# Colors for outputRED='\033[0;31m'@@ -61,6 +63,22 @@ check_docker() {print_success "Docker is installed and running"}+# Probe for `docker compose` (v2 plugin). Sets HAS_COMPOSE=1 when present.+# Detection only; we do not offer to install the plugin — users without compose+# stay on the legacy `docker run` path. The compose file is still written either+# way so it is available the moment compose is installed.+check_docker_compose() {+ print_info "Checking for docker compose..."++ if docker compose version &> /dev/null; then+ HAS_COMPOSE=1+ print_success "docker compose detected"+ else+ HAS_COMPOSE=0+ print_info "docker compose not detected — will use legacy docker run flow"+ fi+}+# Check if Python3 is installed (needed for secure secret generation)check_python() {print_info "Checking Python 3 installation..."@@ -72,12 +90,15 @@ check_python() {print_success "Python 3 is installed"}-# Generate cryptographically secure Django secret key+# Generate cryptographically secure Django secret key.+# Charset excludes characters that can confuse docker compose's env_file parser+# (quotes, backslash, dollar, hash, equals, backtick) so the generated value+# round-trips cleanly through both docker run --env-file and compose env_file.generate_secret_key() {python3 -c "import secretsimport string-chars = string.ascii_letters + string.digits + string.punctuation+chars = string.ascii_letters + string.digits + '!@%^&*()-_+[]{}<>?,./:;|~'print(''.join(secrets.choice(chars) for _ in range(50)))"}@@ -138,8 +159,10 @@ create_env_file() {DJANGO_SECRET_KEY=$(generate_secret_key)DJANGO_ADMIN_PASSWORD=$(generate_admin_password)- # Create environment file- cat > "${ENV_FILE}" << EOF+ # Create environment file.+ # The unique heredoc terminator INSTALL_ENV_FILE_EOF lets `--list-env-vars`+ # extract the variable names from this exact block without ambiguity.+ cat > "${ENV_FILE}" << INSTALL_ENV_FILE_EOF# Home Information Environment Configuration# Generated by install.sh on $(date)@@ -178,7 +201,7 @@ HI_EMAIL_USE_SSL=false# Network Configuration (for localhost only)HI_EXTRA_HOST_URLS=HI_EXTRA_CSP_URLS=-EOF+INSTALL_ENV_FILE_EOF# Secure the env filechmod 600 "${ENV_FILE}"@@ -189,6 +212,60 @@ EOFADMIN_PASSWORD="${DJANGO_ADMIN_PASSWORD}"}+# Write a fully-resolved docker-compose.yml to ~/.hi/. Always written, even+# when compose is not available, so it is ready for use the moment the user+# installs the compose plugin. Container name `hi` matches the legacy+# `docker run --name hi` invocation so management commands like `docker logs+# hi`, `docker stop hi`, and `docker start hi` work identically across both+# code paths. No `healthcheck:` stanza — the Dockerfile already defines one,+# and a compose-level stanza would override it.+create_compose_file() {+ print_info "Writing ${COMPOSE_FILE}..."++ # Back up any hand-edited compose file (e.g. reverse-proxy labels, custom+ # networks) before regenerating. Same pattern as create_env_file.+ if [[ -f "${COMPOSE_FILE}" ]]; then+ local timestamp+ timestamp=$(date "+%Y%m%d_%H%M%S")+ local backup_file="${COMPOSE_FILE}.BAK.${timestamp}"+ cp "${COMPOSE_FILE}" "${backup_file}"+ print_info "Existing compose file backed up: ${backup_file}"+ fi++ cat > "${COMPOSE_FILE}" << INSTALL_COMPOSE_FILE_EOF+# Home Information — generated by install.sh+#+# This file is the live config for managing your installation. To use it:+# cd ${HI_HOME}+# docker compose ps # status+# docker compose logs -f # follow logs+# docker compose restart # restart+# docker compose down # stop+#+# Updates: re-run install.sh's companion update.sh script (it detects this+# file and uses compose). Or run \`docker compose pull && docker compose up -d\`+# from ${HI_HOME}.+#+# Re-running install.sh will overwrite this file with regenerated values.++services:+ ${CONTAINER_NAME}:+ image: ${DOCKER_IMAGE}:${DOCKER_TAG}+ container_name: ${CONTAINER_NAME}+ restart: unless-stopped+ ports:+ - "${EXTERNAL_PORT}:8000"+ env_file:+ - ${ENV_FILE}+ volumes:+ - ${DATABASE_DIR}:/data/database+ - ${MEDIA_DIR}:/data/media+INSTALL_COMPOSE_FILE_EOF++ chmod 600 "${COMPOSE_FILE}"+ print_success "Compose file written: ${COMPOSE_FILE}"+}+# Pull Docker imagepull_docker_image() {print_info "Pulling Home Information Docker image..."@@ -210,19 +287,26 @@ stop_existing_container() {fi}-# Start the container+# Start the container. Branches on HAS_COMPOSE: compose users get compose-managed+# containers; everyone else gets the original `docker run` invocation. Both+# paths produce a container named `hi`, so post-install management commands+# documented in show_success() work identically.start_container() {print_info "Starting Home Information container..."-- docker run -d \- --name "${CONTAINER_NAME}" \- --restart unless-stopped \- --env-file "${ENV_FILE}" \- -v "${DATABASE_DIR}:/data/database" \- -v "${MEDIA_DIR}:/data/media" \- -p "${EXTERNAL_PORT}:8000" \- "${DOCKER_IMAGE}:${DOCKER_TAG}"-++ if (( HAS_COMPOSE == 1 )); then+ docker compose -f "${COMPOSE_FILE}" up -d+ else+ docker run -d \+ --name "${CONTAINER_NAME}" \+ --restart unless-stopped \+ --env-file "${ENV_FILE}" \+ -v "${DATABASE_DIR}:/data/database" \+ -v "${MEDIA_DIR}:/data/media" \+ -p "${EXTERNAL_PORT}:8000" \+ "${DOCKER_IMAGE}:${DOCKER_TAG}"+ fi+print_success "Container started successfully"}@@ -267,19 +351,40 @@ show_success() {echo -e " View logs: docker logs hi"echo -e " Stop: docker stop hi"echo -e " Start: docker start hi"+ echo -e " Restart: docker restart hi"+ echo -e " Update: curl -fsSL https://raw.githubusercontent.com/cassandra/home-information/master/update.sh | bash"echoecho -e "${GREEN}IMPORTANT: Save your admin credentials securely!${NC}"echo}+# Print the sorted, unique set of env var names this script writes.+# Used by deploy/env-drift-check.sh to detect drift between install.sh,+# deploy/env-generate.py, and local.env.example without running any+# installation steps. Extracts names from the heredoc body itself so the+# listing cannot drift from what the script actually generates.+list_env_vars() {+ local self="${BASH_SOURCE[0]}"+ if [[ ! -f "${self}" ]]; then+ echo "Error: cannot locate install.sh source for --list-env-vars" >&2+ exit 1+ fi+ sed -n '/<< INSTALL_ENV_FILE_EOF$/,/^INSTALL_ENV_FILE_EOF$/p' "${self}" \+ | grep -E '^[A-Z][A-Z0-9_]+=' \+ | sed 's/=.*//' \+ | sort -u+}+# Main installation functionmain() {print_header-+check_docker+ check_docker_composecheck_pythoncreate_directoriescreate_env_file+ create_compose_filepull_docker_imagestop_existing_containerstart_container@@ -287,5 +392,11 @@ main() {show_success}+# CLI dispatch: --list-env-vars is a non-installing introspection mode.+if [[ "${1:-}" == "--list-env-vars" ]]; then+ list_env_vars+ exit 0+fi+# Run main functionmain "$@"\ No newline at end of filediff --git a/local.env.example b/local.env.examplenew file mode 100644index 00000000..5728da1f--- /dev/null+++ b/local.env.example@@ -0,0 +1,54 @@+# 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_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=diff --git a/src/hi/environment/server.py b/src/hi/environment/server.pyindex e0aed365..fee6efa6 100644--- a/src/hi/environment/server.py+++ b/src/hi/environment/server.py@@ -11,6 +11,10 @@ from django.core.exceptions import ImproperlyConfiguredclass EnvironmentSettings:"""Encapsulates the parsing of the environment variables that are needed.++ Adding, removing, or renaming a field here also requires changes to+ deploy/env-generate.py, install.sh, and local.env.example. See+ docs/dev/shared/environment-variables.md for the full ritual."""# If the default value is "None" then the variable is required and itsdiff --git a/update.sh b/update.shindex 1fa58c91..f93260af 100755--- a/update.sh+++ b/update.sh@@ -14,6 +14,8 @@ HI_HOME="${HOME}/.hi"ENV_FILE="${HI_HOME}/env/local.env"DATABASE_DIR="${HI_HOME}/database"MEDIA_DIR="${HI_HOME}/media"+COMPOSE_FILE="${HI_HOME}/docker-compose.yml"+HAS_COMPOSE=0 # Set by check_docker_compose; 1 if `docker compose` is available.# Colors for outputGREEN='\033[0;32m'@@ -66,6 +68,32 @@ check_prerequisites() {print_success "Prerequisites verified"}+# Probe for `docker compose` (v2 plugin). Sets HAS_COMPOSE=1 when present.+check_docker_compose() {+ if docker compose version &> /dev/null; then+ HAS_COMPOSE=1+ else+ HAS_COMPOSE=0+ fi+}++# Update via docker compose. Used when both compose is available AND the+# install.sh-generated compose file exists at ~/.hi/docker-compose.yml.+# `pull` fetches the latest image; `up -d` recreates the container with it.+update_via_compose() {+ print_info "Pulling latest image via docker compose..."+ if ! docker compose -f "${COMPOSE_FILE}" pull; then+ print_error "Failed to pull latest image. Please check your internet connection."+ fi+ print_success "Latest image pulled successfully"++ print_info "Recreating container..."+ if ! docker compose -f "${COMPOSE_FILE}" up -d; then+ print_error "docker compose up -d failed."+ fi+ print_success "Container recreated"+}+# Pull latest Docker imagepull_latest_image() {print_info "Pulling latest Docker image..."@@ -145,11 +173,22 @@ show_success() {# Main update functionmain() {print_header-+check_prerequisites- pull_latest_image- stop_old_container- start_new_container+ check_docker_compose++ # Use the compose path only when both compose is available AND the+ # install.sh-generated compose file exists. A pre-Phase-2 install has no+ # compose file even on a host where compose is installed; those users+ # continue managing via the legacy `docker run` recreation flow.+ if (( HAS_COMPOSE == 1 )) && [[ -f "${COMPOSE_FILE}" ]]; then+ update_via_compose+ else+ pull_latest_image+ stop_old_container+ start_new_container+ fi+wait_for_appshow_success}