GSP/Panel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update updater

Browse source
This commit is contained in:
Frank Harris 2026-06-08 18:00:08 -05:00
parent 3829a4a83d
commit 17a31b7f5f
4 changed files with 179 additions and 1530 deletions
Download patch file Download diff file Expand all files Collapse all files

241
docs/modules/PANEL_UPDATE.md
View file

@ -2,201 +2,98 @@
Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)
## Scope
## Purpose
This document covers the admin Panel updater implemented through:
This module documents the Panel-only update flow exposed at `Panel/modules/update/update.php` and implemented in `Panel/modules/administration/panel_update.php`.
- `Panel/modules/update/update.php`
- `Panel/modules/administration/panel_update.php`
- `Panel/includes/lib_remote.php` for remote agent component updates
The update page now updates the Panel only. Website and agent updates are separate workflows and are not rendered by this page.
## Current Workflow
## Configured Settings
```text
Admin opens home.php?m=update
-> update.php loads panel_update.php
-> gsp_panel_update_section() renders UI
The update page uses these settings:
Configured Git update:
-> load saved settings
-> validate repo/branch/paths/retention
-> preflight path and write checks
-> create backup when enabled
-> git clone configured branch to temp checkout
-> resolve source layout
-> self-update updater files first if needed
-> apply patches
-> sync Panel and Website files
-> preserve config.inc.php and protected paths
-> write LAST_UPDATE.txt and version metadata
-> clear cache / fix permissions
-> prune backups by retention
```
- `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
Backup helpers:
When backup-before-update is enabled:
- `gsp_get_backup_base()`
- `gsp_get_backup_retention()`
- `gsp_create_full_backup()`
- `gsp_safe_component_backup()`
- `gsp_get_available_backups()`
- `gsp_get_managed_backup_entries()`
- `gsp_prune_old_backups()`
- 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
Behavior:
The backup directory is created recursively if missing.
- full updater backups use the configured `gsp_update_backup_path`
- component-only backups also use the configured backup path
- missing parent directories are created recursively
- failures are logged to `logs/update_trace.log` with path diagnostics
- retention is enforced after full backups and component backups
Retention is enforced after each successful backup.
Managed backup directory names:
## Rollback Workflow
- full backups: `YYYY-MM-DD_HH-MM-SS`
- component backups: `component_<name>_YYYY-MM-DD_HH-MM-SS`
Rollback uses only full backups. Component backups are retained and pruned, but are not shown in the rollback selector.
## Retention Workflow
Retention setting:
- `gsp_update_backup_retention`
- default: `5`
Behavior:
1. Create backup.
2. Scan all updater-managed backup directories under the configured backup path.
3. Sort newest to oldest.
4. Delete entries beyond retention.
5. Log deleted backup directories to `logs/update_trace.log`.
This applies to both:
- full updater backups
- component backups created by local component updates
## Required Folders And Permissions
Minimum writable locations:
- configured repository root
- configured Panel path
- configured backup path
- `logs/` under repository root for `update_trace.log`
Required tools when used:
- `git`
- `tar`
- `mysqldump` for database backup
- `mysql` for restore
- 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
The update page should not white-screen for routine helper/runtime failures.
Failures are logged to `logs/update_trace.log` and shown as user-facing errors on the page.
Current protections:
The page should remain usable even if:
- `update.php` checks that `gsp_panel_update_section()` exists before calling it
- `update.php` catches `Throwable` and logs unexpected failures
- `gsp_panel_update_section()` catches action-time `Throwable` and keeps rendering the UI
- backup directory creation logs detailed path diagnostics
- missing helper regressions are surfaced as user-visible failures instead of fatal white screens where possible
Log file:
- `GSP_ROOT/logs/update_trace.log`
## Helper Scope Warnings
These helpers must remain top-level:
- `gsp_update_settings()`
- `gsp_validate_update_settings()`
- `gsp_checkout_update_source()`
- `gsp_do_configured_git_update()`
- `gsp_disable_ssl_vhost()`
If any of these are accidentally nested inside another function, the update page can pass `php -l` but still fail at runtime with `Call to undefined function ...`.
## Scheduler Audit
Current finding:
- the existing `cron` scheduler is game-server oriented
- it schedules `gamemanager` and `server_content` actions through `ogp_api.php`
- it does **not** currently expose a first-class scheduled self-update path for:
- Panel updates
- Website updates
- remote Linux agent code updates
- remote Windows agent code updates
Result:
- backup/retention integration for scheduled self-updates is currently not applicable because those scheduled self-update jobs do not exist in the current codebase
- game-server Steam/content scheduler jobs are separate and do not use this updater module
## Remote Agent Update Flow
Remote component updates use:
- `lib_remote.php::component_update()`
- agent-side `component_update` RPC
The Panel:
1. validates configured repo and source folder
2. selects Linux or Windows agent source folder
3. builds an encoded payload
4. sends the payload over XML-RPC
5. shows queued/failed results per remote host
- the repository source is invalid
- git cannot run
- backup directory creation fails
- backup retention pruning fails
- the post-update command fails
## Troubleshooting
### Undefined function crash
If the page shows `Call to undefined function gsp_checkout_update_source()` or a related updater fatal:
Check:
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.
- `php -l Panel/modules/administration/panel_update.php`
- `php -r 'require "Panel/modules/administration/panel_update.php"; var_dump(function_exists("gsp_checkout_update_source"));'`
If backups fail to create:
If `php -l` passes but `function_exists(...)` is false, a helper was nested inside another function.
- 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
### Backup directory creation fails
## Notes
Check:
- configured `gsp_update_backup_path`
- parent directory existence
- web server write access
- `logs/update_trace.log` for the exact `mkdir` failure
### Retention appears wrong
Remember:
- rollback list shows only full backups
- managed backup count includes full backups and component backups
- pruning applies to all updater-managed backup directories
### Update page loads but remote agent updates fail
Check:
- PHP XML-RPC extension on the Panel host
- agent reachability and encryption key
- agent-side `component_update` support
## 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
php -r 'require "Panel/modules/administration/panel_update.php"; foreach (["gsp_checkout_update_source","gsp_do_configured_git_update","gsp_disable_ssl_vhost"] as $f) echo $f,":",function_exists($f)?"yes":"no",PHP_EOL;'
```
- 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.