# Update Module

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

```bash
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`.