vps/runbooks/matrix-e2ee-update.md

matrix_e2ee update (hass.windy.lan)

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

• Last reviewed: 2026-08-18
• Related systems: hass.windy.lan (HAOS, machine: green)

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

STOP conditions: live state conflicts with the prerequisites below (e.g. the source repo is not on the target state, the host manifest does not match the source after rsync, or Core fails to start after restart) — stop and record evidence; never bypass a failed check. Roll back per the Rollback section when Core does not come back up.

SSH config gotcha (verified 2026-08-18): on the WSL client the systemwide /etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf can be owned by nobody (e.g. under the agent sandbox), making plain ssh fail with Bad owner or permissions on /etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf. Workaround: add -F /dev/null to every ssh/rsync command below (still uses the default key and ~/.ssh/known_hosts). If your plain ssh hassio@... works, you can drop it.

Domain is matrix_e2ee (double-e). Older notes may say matrix_e2e; paths, events, and services all use matrix_e2ee.

Prerequisites

• The source repo at /home/windy/project/ha-matrix-e2ee is on the target state: either a release tag (git tag -l 'v*') or a commit whose manifest.json version is the target. Note v0.3.0 was deployed from an untagged main HEAD (216cc99), so the tag check alone is not enough — confirm the working-tree custom_components/matrix_e2ee/manifest.json.
• The working tree matches HEAD: git status --short clean (only ignorables) and git diff HEAD -- custom_components/ empty. Record git rev-parse HEAD for the docs/Linear record — HEAD can move during a session, so re-check right before rsync (verified 2026-08-18: HEAD moved from a w1n-180 branch merge to main mid-deploy).
• 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-e2ee-backups &&
   sudo -n -i cp -a /homeassistant/custom_components/matrix_e2ee \
     /homeassistant/.matrix-e2ee-backups/matrix_e2ee.bak-$(date +%Y%m%d)-v<OLD_VERSION>'

The backup lives in /homeassistant/.matrix-e2ee-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-e2ee/custom_components/matrix_e2ee/ \
  hassio@hass.windy.lan:/homeassistant/custom_components/matrix_e2ee/

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, but rsync exits with code 23 (some files/attrs were not transferred) — that is expected, not a failure. Confirm the transfer by checking the manifest on the host before restarting.

3. Wipe __pycache__ (as root) and restart Core

Quote the nested __pycache__ glob — remote login shell is zsh and will fail with no matches found if left unquoted.

ssh -o BatchMode=yes hassio@hass.windy.lan \
  "sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2ee/__pycache__ \
     '/homeassistant/custom_components/matrix_e2ee/*/__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_e2ee/manifest.json'

Expect "version": "<NEW_VERSION>".

4b. Check Core logs for matrix_e2ee

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

Expect:

• Setup of domain matrix_e2ee took ... (older wording Setting up matrix_e2ee may appear)
• matrix_e2ee restored existing device; user=@hass:chans.xyz device=rO1R915ncu
• No ERROR level messages from custom_components.matrix_e2ee
• Blocking-call WARNINGs from _patch_nio_sas_timeout / nio store I/O are expected

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

No trailing slash on the entries URL (trailing / returns 404 on Core 2026.8.1).

ssh -o BatchMode=yes hassio@hass.windy.lan \
  "sudo -n -i python3 - <<'PY'
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_e2ee':
        print(f\"{e['domain']}: state={e['state']} source={e['source']}\")
PY"

Expect state: loaded.

5. Record the deployment

• Update the matrix_e2ee live-tree section in hosts/hass.windy.lan.md: new version, source commit (git rev-parse HEAD), backup name, and any new feature notes.
• Record the operation in the Linear vps project (scope, action, verification, follow-up); see docs/agents/issue-tracker.md.

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_e2ee &&
   sudo -n -i cp -a /homeassistant/.matrix-e2ee-backups/matrix_e2ee.bak-<DATE>-v<OLD_VERSION> \
     /homeassistant/custom_components/matrix_e2ee &&
   sudo -n -i rm -rf /homeassistant/custom_components/matrix_e2ee/__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-e2ee source — GitHub repo