From b2cb9f7e9787098ccd761721406ec47e9feadd2f Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Tue, 7 Jul 2026 14:17:19 +0200 Subject: [PATCH] Sync install-uninstall module docs --- Repo-docs-MODULE-ARCHITECTURE.md | 19 ++++++++++++++++--- Repo-docs-RELEASE-DEPENDENCIES.md | 25 ++++++++++++++++++------- 2 files changed, 34 insertions(+), 10 deletions(-) diff --git a/Repo-docs-MODULE-ARCHITECTURE.md b/Repo-docs-MODULE-ARCHITECTURE.md index 4f746e0..903272c 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.md +++ b/Repo-docs-MODULE-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. > Origin: `repository`. @@ -421,6 +421,14 @@ The package install-plan API records operator intent only: module refs to the install plan without typing them manually. The endpoint also reports catalog validity, channel, signature, trust state, and the configured path. +- `POST /api/v1/admin/system/modules/install-plan/catalog/{module_id}` saves + a planned install row from a validated catalog entry. Catalog signature and + approved-channel policy are enforced before the row is saved. +- `POST /api/v1/admin/system/modules/{module_id}/uninstall-plan` saves a + planned non-destructive uninstall row for an installed module after it has + been disabled. The Python distribution name is resolved from the installed + `govoplan.modules` entry point; the WebUI package name comes from the module + manifest. - `PUT /api/v1/admin/system/modules/install-plan` saves planned install or uninstall rows. Install rows must use tagged package or git references, not local `file:`/workspace paths. Python install rows must also include the @@ -434,7 +442,10 @@ The package install-plan API records operator intent only: - `govoplan-module-installer --apply --build-webui` executes the saved plan after preflight passes, snapshots `pip freeze` and WebUI package files, writes a run record under the runtime installer directory, and marks planned rows as - applied after success. + applied after success. Successful installs are added to saved startup state by + default; successful uninstalls are removed from saved startup state by default. + Use `--no-activate-installed-modules` or + `--keep-uninstalled-modules-in-desired` only for staged rollout workflows. - `govoplan-module-installer --supervise --migrate --health-url http://127.0.0.1:8000/health --restart-command ''` is the preferred disruptive-change path. It applies the plan, optionally runs migrations in a fresh Python process after a fresh-process manifest @@ -462,7 +473,9 @@ The package install-plan API records operator intent only: release-channel path from an operator shell. - `govoplan-module-installer --rollback ` restores the saved package snapshots, restores the captured SQLite or external database snapshot when - present, and reruns package installation from the previous freeze file. + present, restores the previous desired module state when the database was not + restored wholesale, and reruns package installation from the previous freeze + file. - `--database-backup-command ''` and `--database-restore-command ''` provide non-SQLite backup/restore hooks for migrated installer runs. The backup hook runs before migrations; diff --git a/Repo-docs-RELEASE-DEPENDENCIES.md b/Repo-docs-RELEASE-DEPENDENCIES.md index 4aa0534..4089c06 100644 --- a/Repo-docs-RELEASE-DEPENDENCIES.md +++ b/Repo-docs-RELEASE-DEPENDENCIES.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`. > Origin: `repository`. @@ -99,9 +99,12 @@ govoplan-module-installer \ ``` Admin > System > Modules can then queue the saved install plan as a supervised -request. The daemon claims one queued request at a time and writes request/run -records below `runtime/module-installer`. For process-manager one-shot usage or -tests, use `--daemon-once`. The daemon also writes +request. Install rows can be planned directly from the approved package catalog; +uninstall rows are generated from installed, disabled modules so the Python +distribution and WebUI package names do not need to be typed by hand. The +daemon claims one queued request at a time and writes request/run records below +`runtime/module-installer`. For process-manager one-shot usage or tests, use +`--daemon-once`. The daemon also writes `runtime/module-installer/daemon.status.json`; check it with: ```bash @@ -139,6 +142,14 @@ saved install plan state so the operator can correct it. The supervisor must run outside the FastAPI server process; the admin UI saves and validates plans but does not mutate packages from an HTTP request. +After a successful install plan, the installer adds installed modules to saved +startup state by default so the restarted server can discover and enable them. +After a successful uninstall plan, the installer removes uninstalled modules +from saved startup state by default. Use +`--no-activate-installed-modules` or +`--keep-uninstalled-modules-in-desired` only for staged rollout workflows that +will update module state separately. + Package rollback is automatic. SQLite database rollback is automatic for installer runs that used `--migrate` and captured a database snapshot. Non-SQLite rollback is automatic when the run used @@ -178,9 +189,9 @@ govoplan-module-installer --retry-request --format json Package catalogs are file-backed. Set `GOVOPLAN_MODULE_PACKAGE_CATALOG` to a JSON file matching `docs/module-package-catalog.example.json`; the admin UI will -show those entries and can add them to the install plan. This keeps the release -approval decision outside the running server while avoiding hand-typed package -refs. Validate the catalog before handing it to operators: +show those entries and can save them into the install plan. This keeps the +release approval decision outside the running server while avoiding hand-typed +package refs. Validate the catalog before handing it to operators: ```bash govoplan-module-installer --validate-package-catalog docs/module-package-catalog.example.json --format json