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](../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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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:

```bash
# 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](../hosts/hass.windy.lan.md) — current live version and config
- [docs/home-assistant-matrix.md](../docs/home-assistant-matrix.md) — integration architecture and verification model
- [home-assistant-maintenance.md](home-assistant-maintenance.md) — general HA maintenance procedures
- [ha-matrix-e2e source](https://github.com/windyboy/ha-matrix-e2e) — GitHub repo