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

6
docs/development/CODEX_GUIDE.md
View file

@ -136,9 +136,9 @@ This file is the first stop for future Codex sessions working in this repository
1. Read `docs/modules/UPDATE.md`.
2. Check `Panel/modules/update/update.php`.
3. Check `Panel/modules/administration/panel_update.php`.
4. Check `Panel/includes/lib_remote.php` for the `component_update` wrapper.
5. Check both `Agent_Linux/ogp_agent.pl` and `Agent-Windows/OGP64/OGP/ogp_agent.pl` for the `component_update` RPC.
6. Remember that local Panel/Website updates and remote agent updates both clone a configured Git branch into staging and copy only configured component folders.
4. Check `Panel/includes/lib_remote.php` only if a shared helper is actually needed.
5. Remember that the active Panel update page updates the Panel only.
6. Website and agent updates are separate workflows and should not be reintroduced into the Panel update page.
7. Never let updater logic delete server homes, game install folders, user data, agent `Cfg/`, logs, uploads, backups, or runtime PID files.
## Things Already Investigated

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.

115
docs/modules/UPDATE.md
View file

@ -8,22 +8,26 @@ Primary operational reference:
## Role
`Panel/modules/update` exposes the admin Panel update page. The page delegates most update behavior to:
`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 update page is intentionally simple:
The active update page is intentionally narrow:
- shows the installed Panel version
- shows the current git branch and commit when available
- exposes editable repository settings
- can create a backup
- can update from the configured repository and branch
- can roll back to an existing backup
- exposes editable 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:
@ -32,14 +36,11 @@ The admin page stores these settings in the Panel settings table:
- `gsp_update_branch`
- `gsp_update_repo_root`
- `gsp_update_panel_path`
- `gsp_update_website_path`
- `gsp_update_panel_source_path`
- `gsp_update_linux_agent_source_path`
- `gsp_update_windows_agent_source_path`
- `gsp_update_website_source_path`
- `gsp_update_git_path`
- `gsp_update_backup_path`
- optional admin-only post-update commands per component
- `gsp_update_backup_retention`
- `gsp_update_panel_post_update_command`
- `gsp_update_backup_before`
Defaults:
@ -48,63 +49,40 @@ Defaults:
- Branch: `Panel-unstable`
- Repository Root: `/var/www/html/GSP`
- Panel Path: `/var/www/html/GSP/Panel`
- Website Path: `/var/www/html/GSP/Website`
- Panel Source Folder: `Panel`
- Linux Agent Source Folder: `Agent_Linux`
- Windows Agent Source Folder: `Agent-Windows`
- Website Source Folder: `Website`
- Backup Before Update: enabled
Important implementation note:
## Backup and Rollback
- `gsp_update_settings()` and `gsp_validate_update_settings()` are defined at top level in `Panel/modules/administration/panel_update.php`.
- These helpers must not be nested inside another function. A previous bad edit placed `gsp_update_settings()` inside `gsp_get_git_commit()`, which caused a fatal error when the update page called the helper before `gsp_get_git_commit()` had ever executed.
- If the update page throws `Call to undefined function gsp_update_settings()`, first verify the deployed `Panel/modules/administration/panel_update.php` matches the repository version and that this helper exists near the top of the file before `gsp_panel_update_section()` is called.
- `gsp_do_configured_git_update()` must also remain top-level. A bad edit placed it inside `gsp_do_update()`, so `/home.php?m=update` called an undefined function until a legacy GitHub update path happened to execute first.
- `gsp_checkout_update_source()` must remain top-level. If it is nested inside `gsp_apply_update_from_zip()` or another helper, configured Git updates can fatal with `Call to undefined function gsp_checkout_update_source()`.
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.
## 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 Panel source folder into the configured 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 Panel path.
3. Run preflight against the configured paths.
4. Create a backup when enabled.
5. Clone the configured repository source and branch into a temporary checkout.
6. Sync files into the configured root/Panel paths.
7. Preserve `Panel/includes/config.inc.php`.
8. Run module updates/post-update hooks.
9. Write version metadata and `LAST_UPDATE.txt`.
## Component Updates
The update page can update selected components from one repository:
- Panel files
- Website files
- Linux agents
- Windows/Cygwin agents
Local Panel/Website updates clone the configured repository into a temporary checkout and copy only the configured component source folder into the configured destination path. Protected folders and files are not overwritten:
- `includes/config.inc.php`
- `Cfg/`
- `ServerFiles/`
- `Schedule/`
- `logs/`
- `screenlogs/`
- `cache/`
- `tmp/`
- `uploads/`
- `backups/`
- `steamcmd/`
- `startups/`
- PID files
Remote agent updates use the encrypted Panel-Agent XML-RPC channel and the `component_update` RPC. The agent writes a detached updater script, clones the repo to staging, backs up the current agent code, copies only the configured agent source folder, validates `ogp_agent.pl`, then restarts through `systemd` when available or the existing `screen` fallback.
Remote update status is queued/asynchronous. The first response confirms that the update was accepted and gives the agent-side log path.
Remote updates require PHP XML-RPC on the Panel host. If the extension is missing, the update page still loads and reports a clean `missing_xmlrpc` error when a remote agent update is requested.
2. Validate repository URL, branch, repo root, Panel path, 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 configured Panel source folder into the configured 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
@ -113,27 +91,22 @@ Useful validation commands:
```bash
php -l Panel/modules/administration/panel_update.php
php -l Panel/modules/update/update.php
php -l Panel/includes/lib_remote.php
php Panel/modules/update/tests/update_config_smoke.php
perl -c ogp_agent.pl # run from each installed agent directory with dependencies present
```
## Diagnostics
Apache and SSL checks are diagnostics only. Missing SSL certificates do not block Panel updates.
The old repeated SSL vhost disable buttons are not part of the primary update page. Apache path repair remains available under Advanced Diagnostics, and SSL issues are shown as concise diagnostic warnings.
## Remaining Issues
- The updater still contains legacy GitHub release helper code that is no longer rendered by the simplified primary UI.
- Real production testing should confirm file ownership and web-server permissions on `/var/www/html/GSP`.
## 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`.
- `Panel/modules/update/update.php` only loads `Panel/modules/administration/panel_update.php` and calls `gsp_panel_update_section()`.
- The configured update action uses `git clone --depth 1 --branch <configured branch> <configured repository source> <temporary checkout>`.
- 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`.