99 lines
3.2 KiB
Markdown
99 lines
3.2 KiB
Markdown
# 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.
|