Panel/docs/modules/PANEL_UPDATE.md

Panel Update Module

Workspace reference: GSP-WORKSPACE.md

Purpose

This module documents the Panel-only update flow exposed at Panel/modules/update/update.php and implemented in Panel/modules/administration/panel_update.php.

The update page now updates the Panel only. Website and agent updates are separate workflows and are not rendered by this page.

Configured Settings

The update page uses these settings:

• gsp_update_repo_url
• 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 current admin UI shows these directly:

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

The current admin UI keeps these derived or advanced:

• Panel Path is derived from Repository Root plus /Panel
• Panel Source Folder is fixed to Panel
• Git Executable is hidden and defaults to git
• Post-update Command remains 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

Update Workflow

1. Admin opens the Update page.
2. Panel loads the current settings.
3. Admin can save the repository and path settings.
4. Admin can create a backup of the Panel.
5. Admin can run the Panel-only update.
6. The updater clones the configured repository/branch into a temporary checkout.
7. The updater copies only the configured Panel source folder into the live Panel path.
8. Panel/includes/config.inc.php is preserved.
9. Optional panel post-update command runs after the copy step.
10. Version metadata and LAST_UPDATE.txt are written.

Backup Workflow

When backup-before-update is enabled:

• the Panel tree is archived
• the database backup is attempted when available
• version metadata is copied
• Apache config backup can be included for repair workflows

The backup directory is created recursively if missing.

Retention is enforced after each successful backup.

Current count labels:

• Managed Backups Stored means all managed updater snapshots discovered in the backup base
• Rollback Backups Available means only full timestamped backups that the restore flow can actually restore

Rollback Workflow

• The rollback selector lists managed backups.
• The restore action only accepts full timestamped backups from gsp_get_available_backups().
• Restoring a backup restores the Panel tree and metadata.
• Missing website archives are ignored because the active backup path is Panel-focused.
• Apache config restore is optional.

Error Handling

Failures are logged to logs/update_trace.log and shown as user-facing errors on the page.

The page should remain usable even if:

• the repository source is invalid
• git cannot run
• backup directory creation fails
• backup retention pruning fails
• the post-update command fails

Troubleshooting

If the page shows Call to undefined function gsp_checkout_update_source() or a related updater fatal:

1. Verify the deployed Panel/modules/administration/panel_update.php matches the repository version.
2. Confirm the helper exists at top level in the deployed file.
3. Confirm the page is not loading a stale cached copy.
4. Check logs/update_trace.log for the detailed error.

If backups fail to create:

• verify the backup path exists or can be created recursively
• verify the web server user can write to the path
• verify the path is absolute and does not contain unsafe relative segments

Notes

• Agents now update using their own scripts and workflows.
• Website updates are handled separately.
• The Panel update page intentionally does not render agent or website update controls.