Single node upgrade on Windows from version 5.x.x - CustomerID

Issue all of the following commands using the Windows Command Prompt as an Administrator.

1. Stop Ubisecure CustomerID service and make sure no changes are made to the database during the following steps. Take care you still have Java 8 installed and the related environment variables set at this stage.

   net stop wildfly

2. Remove Java 8 installation, install Java 11 and set JAVA_HOME according to Java Check On Windows.

3. Back up Ubisecure CustomerID. See instructions from Backup and restore - CustomerID. You should do this regularly but for the upgrade process we advise you in this step to move the existing installation to a specific location customerid-old which is used in this document.

   cd "%PROGRAMFILES%\Ubisecure"
   move customerid customerid-old

4. Back up Ubisecure Directory (ADAM or AD LDS). See instructions from Backup and restore Ubisecure Directory - SSO.
5. Unpack the new distribution package. See instructions from Distribution Package Unpacking On Windows. Your unpack folder e.g. %USERPROFILE%\Desktop\customerid must be empty before doing this step.

6. When upgrading from 5.6 or older, or you have an existing WildFly installation which has different version number than the one included in the distribution package you need to uninstall the old version and install the new one. See instructions from WildFly Installation On Windows.

   1. before uninstalling the previous version

      set WILDFLY_HOME=%PROGRAMFILES%\wildfly-<old-version-number>.Final 

   2. before installing the new version

      set WILDFLY_HOME=%PROGRAMFILES%\wildfly-<new-version-number>.Final 

7. Extract the deployment template cid-deployment-template-x.x.x.zip to %PROGRAMFILES%\Ubisecure. Your installation folder e.g. %PROGRAMFILES%\Ubisecure\customerid must be empty before doing this step.
8. Import configuration settings from the previous installation.
   1. In order to resume the service after the upgrade it is necessary to copy some configuration settings from the previous installation. These settings are contained in the file %PROGRAMFILES%\Ubisecure\customerid-old\application\win32.config.

   2. In the new installation the win32.config file is located further down the similar path in the config sub-folder and must first be copied to the application folder.

      cd /D "%PROGRAMFILES%\Ubisecure\customerid\application"
      copy config\win32.config 

   3. The values must be copied carefully from the previous installation as the configuration options may have changed. You should copy only those values that have the same keys on both old and new win32.config files. Refer to page Setup template on Windows - CustomerID for more information about the current configuration options.

      NOTE: If you have made configuration changes to any of the win32.config parameters directly in eidm2.properties file after previously running the setup.cmd ensure that these changes are included in the new win32.config file. For example, if you have changed the REST credentials in eidm2.properties file, make sure the same values are now present in the win32.config file.

9. Run the setup script.

   cd /D "%PROGRAMFILES%\Ubisecure\customerid\application"
   setup.cmd

10. When upgrading from 5.6 or older, or you have reinstalled Wildfly, configure WildFly if you reinstalled it. See instructions from WildFly Configuration On Windows. When Wildfly has been started, check each step:
    
    1. Copy the existing SSL certificate to %WILDFLY_HOME%\standalone\configuration\keystore.pfx
    2. Modify WildFly service as instructed
    3. Configure WildFly file permissions as instructed
    4. Apply WildFly configuration changes as instructed
    5. Verify WildFly SSL configuration as instructed
    6. Set up customerid.home as instructed
    7. Set up logging as instructed
    8. Set up a mail session as instructed

11. Restart Ubisecure CustomerID service. If you have not reinstalled Wildfly, it is not running at this stage and it is enough to start the service.

    net stop wildfly
    net start wildfly

12. Start Ubisecure SSO service which was stopped during WildFly installation step if you performed it.

    net start UbiloginServer

13. Prepare Database for Ubisecure CustomerID.
    1. Check if you need to do any modifications in the existing PostgreSQL database for this CustomerID version from Database changes - CustomerID

    2. When upgrading from 5.6 or older, or you have reinstalled Wildfly, create the JDBC data source to WildFly. There is a script in the distribution package's tools folder for this purpose but before executing it verify that the driver file is found in the location you have specified in win32.config: database.driver.path and database.driver.file settings.

       cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
       create-datasource.cmd

14. When upgrading from version 5.6 or older, upgrade PostgreSQL server (for supported versions, see System Recommendations) following PostgreSQL official upgrade documentation at https://www.postgresql.org/docs/12/upgrading.html.
    We have created Knowledge Base "How-to" article with information how we have tested the upgrade and also include estimated migration times. See Upgrade and migrate to new version of PostgreSQL
15. Upgrade PostgreSQL JDBC driver on SSO side (for supported versions, see System Recommendations)
    

    1. Copy the postgresql-x.x.x.jar library included in the root folder of the CustomerID installation archive to the Ubisecure SSO server and copy it to the following folder: %PROGRAMFILES%\Ubisecure\ubilogin-sso\tomcat\lib. See also PostgreSQL JDBC driver installation to SSO on Windows

    2. Restart SSO

       net restart ubiloginserver
       

16. Restore the local customization from the previous installation and update it to be compliant with the installed version. Do not override any of the files which have been already created by the setup script especially eidm2_generated.properties. This step needs to be done even if there are no customizations made for the installation.

    xcopy /E "%PROGRAMFILES%\Ubisecure\customerid-old\application\custom" "%PROGRAMFILES%\Ubisecure\customerid\application\custom"

    NOTE: Before continuing open document Configuration changes in versions - CustomerID  which lists all changes you need to do between different versions. Using that document as a guide delete all removed keys, add new ones if needed and replace all changed keys from the custom files in your new installation.
    

17. When upgrading from CustomerID version 5.6.x or older, update CustomerID LDAP entries to facilitate REST API OAuth2 authentication, see also Configuring OAuth2 authentication for REST API
    1. Copy the LDIF files found from %PROGRAMFILES%\Ubisecure\customerid\application\ldap on the Ubisecure CustomerID server to Ubisecure SSO server. You can place them on the desktop in a folder called customerid-ldifs.

    2. On the SSO server side use the script to import the definitions

       cd /D "%PROGRAMFILES%\Ubisecure\ubilogin-sso\ubilogin\ldap\adam"
       import.cmd "%USERPROFILE%\Desktop\customerid-ldifs\customerid.ldif"
       import.cmd "%USERPROFILE%\Desktop\customerid-ldifs\customerid-secrets.ldif"

       
       Tip: If both CustomerID and SSO installation reside on the same server you can simply do the following instead:

       cd /D "%PROGRAMFILES%\Ubisecure\ubilogin-sso\ubilogin\ldap\adam"
       import.cmd "..\..\..\..\customerid\application\ldap\customerid.ldif"
       import.cmd "..\..\..\..\customerid\application\ldap\customerid-secrets.ldif"

18. Deploy Ubisecure CustomerID enterprise archives (EARs) to the WildFly J2EE container - use the location where you have extracted the installation package and the proper version number in the file name. Note that also Ubisecure Directory service (UbiloginDirectory) needs to be running for the deployment to succeed. If you did not reinstall Wildfly when upgrading from 5.7 or newer, you need first check the service is running, and then undeploy the EAR files from the previous CustomerID version

     Click here to expand Instructions when Wildfly has not been reinstalled

    1. Start Wildlfy service if it  is not running:

    net start wildfly

    2. Change current directory to $WILDFLY_HOME\bin in order to use JBoss CLI for undeployment:

    Command Prompt

    cd /D "%PROGRAMFILES%\wildfly-21.0.2.Final\bin"
    set NOPAUSE=Y

    Powershell

    cd "$Env:PROGRAMFILES\wildfly-21.0.2.Final\bin"
    $Env:NOPAUSE="Y"

    3. Check the names of the deployed EAR files (cid-ear-x.x.x.ear and cid-worker-ear-x.x.x.ear), in the following example they are from CustomerID version 5.7.0:

    C:\Program Files\wildfly-21.0.2.Final\bin>.\jboss-cli.bat --connect --command="undeploy"
    cid-ear-5.7.0.ear         cid-worker-ear-5.7.0.ear  cidpgdriver

    4. Undeploy CustomerID EAR files:

    C:\Program Files\wildfly-21.0.2.Final\bin>.\jboss-cli.bat --connect --command="undeploy cid-ear-5.7.0.ear"
    C:\Program Files\wildfly-21.0.2.Final\bin>.\jboss-cli.bat --connect --command="undeploy cid-worker-ear-5.7.0.ear"

    5. When upgrading from version 5.8 or older, upgrade PostgreSQL JDBC driver in WildFly:

    Command Prompt

    cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools"
    ./remove-datasource.cmd
    ./create-datasource.cmd

    When Wildfly is running and there are no EAR files from the previous CustomerID installation deployed, continue with the deployment:

    cd /D "%PROGRAMFILES%\Ubisecure\customerid\tools\"
    deploy-ear.cmd %USERPROFILE%\Desktop\customerid\cid-ear-x.x.x.ear
    deploy-ear.cmd %USERPROFILE%\Desktop\customerid\cid-worker-ear-x.x.x.ear

    Successful deployment will show Deploying CustomerID EAR to Wildfly..., and optionally, depending on the NOPAUSE setting Press any key to continue . . .

19. Upgrade SSO Adapter. See instructions from CustomerID SSO Adapter extension upgrade