Panel/docs/modules/UPDATE.md

Update Module

Workspace reference: GSP-WORKSPACE.md

Primary operational reference:

• docs/modules/PANEL_UPDATE.md

Role

Panel/modules/update exposes the admin Panel update page. The page delegates its logic to:

• Panel/modules/administration/panel_update.php

This page now updates the Panel only.

Current Behavior

The active update page is intentionally narrow:

• shows the installed Panel version
• shows the current git branch and commit when available
• exposes a reduced set of commonly changed repository settings for the Panel update only
• can create a Panel backup
• can update the Panel from the configured repository and branch
• can roll back to an existing Panel backup
• keeps Apache diagnostics in a collapsed Advanced Diagnostics section

It does not expose agent updates, website updates, or “update all components” behavior.

Update Settings

The admin page stores these settings in the Panel settings table:

• gsp_update_repo_url for the repository source. This may be a Git URL or a safe absolute local repository path.
• gsp_update_branch
• gsp_update_repo_root
• gsp_update_panel_path
• gsp_update_panel_source_path
• gsp_update_git_path
• gsp_update_backup_path
• gsp_update_backup_retention
• gsp_update_panel_post_update_command
• gsp_update_backup_before

The active UI now exposes these commonly changed settings directly:

• Repository URL / Path
• Branch / Channel
• Repository Root
• Backup Path
• Backup Retention
• Backup Before Update

The active UI now treats these as derived or advanced:

• Panel Path is derived as Repository Root + /Panel
• Panel Source Folder is fixed to Panel
• Git Executable is hidden and defaults to git
• Post-update Command remains available under Advanced Settings

Defaults:

• Repository URL / Path: http://forge.runlevelsystems.com/dev/GSP.git
• Branch: Panel-unstable
• Repository Root: /var/www/html/GSP
• Panel Path: /var/www/html/GSP/Panel
• Panel Source Folder: Panel
• Backup Before Update: enabled

Backup and Rollback

Backups are Panel-focused:

• the Panel tree is archived
• includes/config.inc.php is preserved by the restore logic
• version markers are preserved
• database backup is included when the environment supports it
• Apache configs can be included for diagnostic/repair workflows

Retention is enforced after each successful backup.

If retention is 5, the newest five managed backups are kept and older managed backups are pruned automatically.

Current backup counters on the admin page:

• Managed Backups Stored counts all managed updater snapshots returned by gsp_get_managed_backup_entries(), including full and component-style entries when present
• Rollback Backups Available counts only full timestamped backups returned by gsp_get_available_backups() that the restore flow can actually use

Implementation Notes

• gsp_update_settings() and gsp_validate_update_settings() remain top-level in Panel/modules/administration/panel_update.php.
• gsp_checkout_update_source() remains a top-level compatibility helper for the configured repository checkout.
• gsp_do_configured_git_update() now applies only the fixed Panel source folder into the derived Panel path.
• The page no longer depends on website or agent update settings.

Update Flow

1. Save or submit repository settings.
2. Validate repository URL, branch, repo root, and backup settings.
3. Create a backup when enabled.
4. Clone the configured repository source and branch into a temporary checkout.
5. Copy only the fixed Panel source folder into the derived Panel path.
6. Preserve Panel/includes/config.inc.php.
7. Run module updates/post-update hooks.
8. Write version metadata and LAST_UPDATE.txt.

Smoke Tests

Useful validation commands:

php -l Panel/modules/administration/panel_update.php
php -l Panel/modules/update/update.php
php Panel/modules/update/tests/update_config_smoke.php

Diagnostics

Apache and SSL checks are diagnostics only. Missing SSL certificates do not block Panel updates.

Repair Notes

• The update page fatal Call to undefined function gsp_update_settings() means the deployed Panel/modules/administration/panel_update.php is missing the top-level helper or is not the current repository copy.
• The update page fatal Call to undefined function gsp_do_configured_git_update() means the configured Git update helper is missing or nested inside another helper in the deployed panel_update.php.
• The update page fatal Call to undefined function gsp_checkout_update_source() means the configured Git checkout helper is missing or nested inside another helper in the deployed panel_update.php.
• The current fix removes the multi-component update UI from the active page and keeps the Panel update path self-contained.
• Clone failures are logged to logs/update_trace.log with the configured repository source and branch.

Remaining Issues

• Legacy update helpers remain in the file for compatibility and historical reference, but the active page does not render them.
• Real production testing should confirm file ownership and web-server permissions on /var/www/html/GSP.