Problem

You want to upgrade your PortalGuard server to the latest version, and you are interested in the process.

Solution

Important Note: Upgrading a PortalGuard On-Premises deployment can be completed without a Technical Support engineer. It is highly recommended that you perform the upgrade in a test/dev environment first to prevent any production issues. 

• Upgrading your PortalGuard server requires modifying new UI files to match your previous changes.  If you are not comfortable with this requirement, please submit a Technical Support ticket with a recent PGDiags output attached to have your UI reviewed:

  • KB: https://bio-key.atlassian.net/servicedesk/customer/portal/1/article/284786797

Disclaimer: It is highly recommended that you take a snapshot or backup of the server prior to upgrading.  If your environment utilizes the SQL backend, the 'pstar' database should be backed up as well.

Please be sure to read through all steps below and submit any questions as a Technical Support ticket.

1. Download the latest On-Premises installation kit for PortalGuard. (choose the newest version in the list)

   • PortalGuard Installation Kit

2. Extract the contents of the installation kit zip file to your PortalGuard server.

3. Important: Take a backup/snapshot of the PortalGuard server for redundancy.

4. Open the extracted installation kit and navigate to the following location:

   • '\PortalGuard_v6.X.X.X\Back-end Upgrade'

     • NOTE: The version referenced above may vary based on when you download the install kit, but the path should remain the same.

5. Run the 'PG_Updater.exe' application as Administrator.

   • You can also view the details of what happens during the back-end upgrade by viewing the 'PG Back-end Upgrade Readme.pdf' file in this same location.

   • This portion of the upgrade only takes a few moments and requires no downtime of the PortalGuard sever.

6. You must go through each configuration within the PortalGuard Configuration Editor and Identity Provider Configuration Editor and edit/save each one to ensure the new defaults take effect.

   • When you have saved each config again, run the 'Apply/Sync' function from both editors.

7. IMPORTANT NOTE: If you have received a customized version of the UI to put in place, follow the steps outlined in the following KB. Skip steps #9 - #14 below in this case.

   1. KB: https://bio-key.atlassian.net/servicedesk/customer/portal/1/article/284229769

8. IMPORTANT NOTE: Even if you have not made any branding customizations to the UI, follow steps #9 - #14 below to get the new UI files in place. No modifications need to be made.

9. Navigate to the 'Program Files\PistolStar\PortalGuard' folder on your PortalGuard Sever.

10. Locate the '_Upgrade_InetPub_6.X.X.X' folder.

    • Again, the version may vary, but the path structure will remain the same.

    • This folder contains the new base (unmodified) UI that includes all required modifications for the new version of PortalGuard. 

    • The PortalGuard Back-end Upgrade Utility DOES NOT touch your existing user interface at all. 

11. Make a backup of the '_Upgrade_InetPub_6.X.X.X' folder.

12. Modify the new UI Files to resemble your previous UI.

    • IMPORTANT NOTE: The 6.X.X.X versions of PortalGuard include a significant UI overhaul.  A simple merge will not be enough to bring your customizations over if the initial version of your instance was older than v6.5.0.0.  

      • If you are not comfortable modifying your UI, please submit a Technical Support ticket to request assistance with that merge.

    • The most commonly modified files that should be reviewed for migration are (assuming default file path for the installation):

      • C:\inetpub\PortalGuard\web.config

      • C:\inetpub\PortalGuard\webkey.config

      • C:\inetpub\PortalGuard\PG_Dashboard\web.config

      • C:\inetpub\PortalGuard\PG_HelpDesk\web.config

      • C:\inetpub\PortalGuard\_layouts\PG\login.aspx

      • C:\inetpub\PortalGuard\_layouts\images\PG\css\style_custom.css

      • C:\inetpub\PortalGuard\_layouts\images\PG\js\pg_custom.js

    • Ensure all necessary images have also been copied over. The most common image repositories are:

      • C:\inetpub\PortalGuard\_layouts\images\PG\images

      • C:\inetpub\PortalGuard\sso\img

13. Once the UI Files are modified as needed, they can be put in place:

    • Copy the current UI as a quick backup.

      • You can walk back the UI changes and still use PortalGuard, even with a newer version of the back-end - though certain new features will not function with the older UI in place. 

    • Delete the contents of the current 'inetpub\PortalGuard' folder.

      • You may need to 'Try Again' several times during this action.  If some of the files continue to be locked, run 'iisreset' from an elevated CMD and try again. 

        • IF the issue persists, you will need to stop the ‘PortalGuard’ website within the IIS Configuration Manager.

    • Copy the new, modified UI Files into the 'inetpub\PortalGuard' folder that you just emptied. 

    • Open an elevated CMD and run the 'iisreset' command. 

      • If the website was stopped manually, you may need to ‘Start’ it manually as well.

14. Check the web.config files under the PortalGuard, PG_Dashboard, and PG_HelpDesk folders for any modifications made for your PG instance.  One example would be uncommenting the rewrite rules in the PortalGuard root folder.

15. If you utilize the SQL Back-End: Navigate to the Installation Kit and enter the '\PortalGuard_v6.X.X.X\ADDINS\SQL Scripts\' folder.

16. Copy the 'pstar_complete.sql' file to your SQL Backend Server (or wherever you are able to run SSMS to access the 'pstar' database!

17. Backup the 'pstar' database. 

18. Execute the upgrade script to ensure your PortalGuard database has the latest functionality added with this version. 

19. Consider any services like SMTP and/or Hosted Providers and update them with the IP address of the PG Server if it has changed.

20. Navigate to the PortalGuard Website and Test!