Upgrade recovery guide

If an upgrade fails and you can no longer sign in to the portal, follow this quick reference to restore the last known good release. All commands should be executed from the project root on the application server.

Restore the previous release snapshot

  1. Connect to the server that hosts HRassess and change to the project directory.
  2. Run the automated recovery command to roll back both the codebase and the database: 
    php scripts/system_upgrade.php --action=restore --restore-db
    • Without --backup-id the tool restores the most recent successful upgrade snapshot located in storage/upgrades/runs/.
    • Add --backup-id=<run-id> if you need to target a specific backup shown in the upgrade dashboard or the JSON files inside storage/upgrades/runs/.
  3. Wait for the script to confirm that the application files (and optionally the database) were restored successfully.
Tip: If you only need to roll back the application files and want to keep the current database, omit the --restore-db flag.

After the rollback

  1. Clear any reverse-proxy or application caches (for example, restart PHP-FPM or invalidate CDN caches if used).
  2. Sign in to the portal and verify that dashboards and submissions load as expected.
  3. Review the upgrade logs in storage/upgrades/installed.json and inside storage/upgrades/runs/ to confirm the rollback details.
  4. When ready to attempt the upgrade again, resolve the underlying issue, then rerun the normal upgrade process with php scripts/system_upgrade.php --action=upgrade.

Keeping a copy of this guide outside the system ensures administrators can quickly recover even when the UI is unavailable.