Skip to content

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.yml
index 9e2a1c0f..2218d456 100644
--- a/.github/workflows/django-tests.yml
+++ b/.github/workflows/django-tests.yml
@@ -57,3 +57,7 @@ jobs:
working-directory: ./src
run: |
flake8 . --config=.flake8-ci
+
+ - name: Check Env-Var Drift
+ run: |
+ bash deploy/env-drift-check.sh
diff --git a/Makefile b/Makefile
index 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-check
docker-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-check
fix-permissions:
@echo "Setting execute permissions for $(SCRIPTS)"
diff --git a/README.md b/README.md
index 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 involved
diff --git a/deploy/env-drift-check.sh b/deploy/env-drift-check.sh
new file mode 100755
index 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.py
index 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_name
self._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().'
+ )
+ return
def 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.sh
new file mode 100755
index 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
+
+claude
diff --git a/dev/init-env-dev.sh b/dev/init-env-dev.sh
new file mode 100644
index 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
+fi
diff --git a/docker-compose.example.yml b/docker-compose.example.yml
new file mode 100644
index 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/media
diff --git a/docs/Deployment.md b/docs/Deployment.md
new file mode 100644
index 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.md
index 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.md
new file mode 100644
index 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.sh
deleted file mode 100755
index 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
-
-claude
diff --git a/init-env-dev.sh b/init-env-dev.sh
deleted file mode 100644
index 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
-fi
diff --git a/install.sh b/install.sh
index 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 output
RED='\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 secrets
import 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 file
chmod 600 "${ENV_FILE}"
@@ -189,6 +212,60 @@ EOF
ADMIN_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 image
pull_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"
echo
echo -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 function
main() {
print_header
-
+
check_docker
+ check_docker_compose
check_python
create_directories
create_env_file
+ create_compose_file
pull_docker_image
stop_existing_container
start_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 function
main "$@"
\ No newline at end of file
diff --git a/local.env.example b/local.env.example
new file mode 100644
index 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.py
index e0aed365..fee6efa6 100644
--- a/src/hi/environment/server.py
+++ b/src/hi/environment/server.py
@@ -11,6 +11,10 @@ from django.core.exceptions import ImproperlyConfigured
class 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 its
diff --git a/update.sh b/update.sh
index 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 output
GREEN='\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 image
pull_latest_image() {
print_info "Pulling latest Docker image..."
@@ -145,11 +173,22 @@ show_success() {
# Main update function
main() {
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_app
show_success
}