# Deployment and recovery - AIM WebGUI 2.1.0rc9

Target: separately installed AIM Core **3.3.0rc8**, service/wire/event API **1.0**.
WebGUI HTTP **v2**, SQLite **schema 5**. From WebGUI 2.1.0rc3 there is no database
schema change or new permission/service requirement. This candidate qualifies the
new public patch catalog/report shape; it does not upgrade Core itself.

## Fresh installation

Use [ADDON-INSTALLATION.md](../ADDON-INSTALLATION.md) after the independently supplied
Core `scripts/docs/INSTALLATION.md`. `install` is for a new add-on; `update` is for an
existing managed installation. The Core and WebGUI deployers have different flags.

## Coordinate Core and WebGUI versions

The previous WebGUI 2.1.0rc4 targets Core3.3.0rc3 exactly; it does not accept Core rc8.
Finish active jobs, prevent new submissions and quiesce terminal writers. Cancellation
is not rollback. Keep matching Core and add-on backups, including the workflow DB.

```bash
sudo systemctl stop aim-web-worker.service aim-web.service aim-web-executor.service
```

Deploy Core3.3.0rc8 independently with its verified source archive and its own

**Controller prerequisite:** Core rc8 requires `ansible.windows >=3.8.0,<4.0.0` for Windows playbooks. Confirm it in the canonical collection path under the executor identity; WebGUI does not install collections.
preview/apply/quiesced procedure. Do not overwrite Core settings, environments,
inventory/Vault/keys or global SSH trust. Review patch-wave changes in Core's release
notes and complete separately approved terminal acceptance. A UI release does not
certify the new native Windows Update flow.

Then extract this add-on into a fresh directory, not over the active source:

```bash
cd /var/tmp
sha256sum -c AIM-WebGUI-2.1.0rc9.zip.sha256
unzip AIM-WebGUI-2.1.0rc9.zip
cd aim-web-2.1.0rc9
sudo python3 deploy/deploy.py update
```

Ordinary2.x updates do not need --migrate-core. Same-version reinstall is rejected.
The installer validates the actual manifest/required files, prepares dependencies and
assets, checks public Core access, backs up and activates the release, writes known
managed units and waits boundedly for socket readiness. Unknown unit drop-ins require
operator review. Core remains unchanged by this updater.

## State, review and retention

Accounts, grants, plans, journals, reports and audit remain in schema5. Its five
released SQL migrations are unchanged. An older schema4 install follows the existing
schema5 migration (pending/queued work blocked, running work interrupted, old reviews
removed). A schema5-to5 update does not rewrite job states: old prepared work is still
subject to the existing source/revision revalidation and cannot silently execute a new
Core revision. Quiesce first and use a fresh review after Core source/schema changes.

Saved plans remain presets; selecting one requires a fresh review. Historical reports
use their stored schema and are not revalidated with the new enlarged patch schema.
There is no backfill, terminal-history collection or automatic retry/continuation.

The full webgui.toml remains release-managed and overwritten with the approved site
profile (execution enabled, existing14-playbook allowlist, no independent approval,
credential transport attestation). Keep the independently configured Core opt-in.
Retention defaults remain:

```toml
[journal]
max_events = 20000
max_bytes = 8388608
[reports]
max_bytes = 16777216
retain_configuration = false
```

Custom local TOML edits must be incorporated into the reviewed release profile to
survive later replacements. Job deletion removes its linked evidence; protected
backups and physical-storage erasure have separate operator policies.

## Verify in the real service context

```bash
aim-web --version
aim-web config-check
sudo systemctl status aim-web-executor.service aim-web.service aim-web-worker.service --no-pager
sudo -u aim-web aim-web core-check
sudo journalctl -u aim-web-executor.service -n 60 --no-pager
```

Expected: AIM WebGUI2.1.0rc9 / Core3.3.0rc8. ExecStartPre remains the authoritative
staging probe inside the executor's actual sandbox. A plain sudo -u shell lacks its
unit-scoped aim-web group and is not an equivalent preflight. Do not loosen config or
staging permissions to make the interactive wrapper pass.

The generated unit contract is unchanged: normal executor primary group plus aim-web
supplementary group; web state0700; config root:aim-web0640; executor state and both
staging paths0700; runtime directory executor0711; socket executor:aim-web0660;
NoNewPrivileges, empty capabilities, ProtectSystem=strict, ProtectHome=read-only with
only exact staging write exceptions. No new ports/services/writable paths are needed.

Start with a safe read-only reporting job and reload its recorded evidence. New native
patching/reboot behavior needs Core's disposable-target acceptance, not a production
installation used as a browser smoke test. See [PATCH-WAVES.md](PATCH-WAVES.md).

## Recovery and rollback

Record the printed /var/backups/aim-web checkpoint. After an interrupted deployment,
investigate pending.json and use the same release deployer's recover command; do not
manually retarget current symlinks.

```bash
sudo python3 deploy/deploy.py recover
sudo python3 deploy/deploy.py rollback --backup CHECKPOINT
```

The commands above are alternative recovery actions, not a sequence to run blindly.
An rc5->rc4 add-on rollback stays on schema5, but the older adapter still requires its
matched Core version. The deployer tests restored compatibility; an incompatible
restoration remains stopped/disabled until the operator separately restores the
matching Core and deliberately enables the units.

Crossing schema5->4 requires --restore-auth-db and an explicit historical database
restore. That can reinstate older password hashes and discard later users/jobs/plans/
journals/reports; restored sessions are revoked. Back up current data first. Neither
product rollback reverses remote installations/reboots or unrelated operator changes.

## Offline assets

This is not a full offline dependency bundle. Python and production browser pins are
unchanged (Bootstrap5.3.8 and HTMX2.0.10 with SHA384 checks). Existing matching assets
can be reused. --wheelhouse and --assets-dir accept independently prepared exact
artifacts. No development/test dependency is installed into either product environment.