admin_rb
132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
# 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.
|