# Panel Update Module

Workspace reference: [`GSP-WORKSPACE.md`](../../../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`

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

## Rollback Workflow

- The rollback selector lists managed 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.