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 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.

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:

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:

[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

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.

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.

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.

6.2 KiB Raw Blame History