vps/runbooks/matrix-e2e-update.md

matrix_e2e update (hass.windy.lan)

Update the custom matrix_e2e integration on hass.windy.lan.

Facts: hosts/hass.windy.lan.md (see § matrix_e2e live tree) Source: /home/windy/project/ha-matrix-e2e (development clone on workstation) Access: ssh -o BatchMode=yes hassio@hass.windy.lan 'sudo -n -i <cmd>'

Prerequisites

• The source repo at /home/windy/project/ha-matrix-e2e is on the correct tag/commit.
• The tag exists: git tag -l 'v*' shows the target version.
• The remote host is reachable and sudo -n -i ha core info succeeds.
• The workstation HTTP proxy does not interfere — LAN hosts must be reachable without proxying (unset http_proxy / HTTP_PROXY if needed).

Update procedure

1. Backup the live tree

ssh -o BatchMode=yes hassio@hass.windy.lan \
  'sudo -n -i mkdir -p /homeassistant/.matrix-e2e-backups &&
   sudo -n -i cp -a /homeassistant/custom_components/matrix_e2e \
     /homeassistant/.matrix-e2e-backups/matrix_e2e.bak-$(date +%Y%m%d)-v<OLD_VERSION>'

The backup lives in /homeassistant/.matrix-e2e-backups/ — a directory separated from custom_components/ to avoid HA scanning it as a custom component domain.

2. Rsync the new source

rsync -a --delete -e 'ssh -o BatchMode=yes' \
  /home/windy/project/ha-matrix-e2e/custom_components/matrix_e2e/ \
  hassio@hass.windy.lan:/homeassistant/custom_components/matrix_e2e/

The --delete cannot remove Core-owned __pycache__ — that is handled in the next step. Source .py files and manifest.json are transferred correctly even with the __pycache__ errors.

3. Wipe __pycache__ (as root) and restart Core

ssh -o BatchMode=yes hassio@hass.windy.lan \
  'sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2e/__pycache__ \
     /homeassistant/custom_components/matrix_e2e/*/__pycache__ &&
   sudo -n -i ha core restart'

Stale cpython-314 bytecode in Core-owned __pycache__ keeps the old coordinator in memory until restart. Wipe before restart.

Wait for Command completed successfully. (typically 1–2 min).

4. Verify the deployment

4a. Confirm manifest version

ssh -o BatchMode=yes hassio@hass.windy.lan \
  'sudo -n -i cat /homeassistant/custom_components/matrix_e2e/manifest.json'

Expect "version": "<NEW_VERSION>".

4b. Check Core logs for matrix_e2e

ssh -o BatchMode=yes hassio@hass.windy.lan \
  'sudo -n -i ha core logs -n 2500' | grep -E 'matrix_e2e|Setting up matrix' | head -20

Expect:

• Setting up matrix_e2e
• matrix_e2e restored existing device; user=@hass:chans.xyz device=rO1R915ncu
• No ERROR level messages from custom_components.matrix_e2e
• The _patch_nio_sas_timeout WARNING is expected (known nio workaround)

The code domain is matrix_e2e (E2EE = End-to-End Encryption), so log entries and file paths use matrix_e2e. The integration's short name is matrix_e2e.

4c. Verify the entry is loaded (optional, via Supervisor API)

ssh -o BatchMode=yes hassio@hass.windy.lan \
  'sudo -n -i python3 -c "
import os, json, urllib.request
req = urllib.request.Request(
    \"http://supervisor/core/api/config/config_entries/entry/\",
    headers={\"Authorization\": \"Bearer \" + os.environ[\"SUPERVISOR_TOKEN\"]},
)
entries = json.loads(urllib.request.urlopen(req, timeout=30).read())
for e in entries:
    if e[\"domain\"] == \"matrix_e2e\":
        print(f\"{e[\"domain\"]}: state={e[\"state\"]} source={e[\"source\"]}\")
"'

Expect state: loaded.

Rollback

If Core fails to start after the update:

# Restore the backup
ssh -o BatchMode=yes hassio@hass.windy.lan \
  'sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2e &&
   sudo -n -i cp -a /homeassistant/.matrix-e2e-backups/matrix_e2e.bak-<DATE>-v<OLD_VERSION> \
     /homeassistant/custom_components/matrix_e2e &&
   sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2e/__pycache__ &&
   sudo -n -i ha core restart'

If a full HA backup exists (pre-update), restore via ha backups restore <slug>.

References

• hosts/hass.windy.lan.md — current live version and config
• docs/home-assistant-matrix.md — integration architecture and verification model
• home-assistant-maintenance.md — general HA maintenance procedures
• ha-matrix-e2e source — GitHub repo