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

Issue all the commands using the root user account.

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.

   systemctl stop wildfly.service

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

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 /usr/local/ubisecure
   mv customerid customerid-old

4. Back up Ubisecure Directory (OpenLDAP). See instructions from Backup And Restore - Ubisecure Directory.
5. Unpack the new distribution package. See instructions from Distribution Package Unpacking On Linux. Your unpack directory e.g. ~/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 Linux.

   1. before uninstalling the previous version

      export WILDFLY_HOME=/usr/local/wildfly-<old-version-number>.Final 

   2. before installing the new version

      export WILDFLY_HOME=/usr/local/wildfly-<new-version-number>.Final 

7. Extract the deployment template cid-deployment-template-x.x.x-linux.tar.gz. Your installation directory e.g. /usr/local/ubisecure/customerid must be empty before doing this step.

   cd /usr/local/ubisecure
   tar xzvf ~/customerid/cid-deployment-template-x.x.x-linux.tar.gz 

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 /usr/local/ubisecure/customerid-old/application/linux.config.

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

      cd /usr/local/ubisecure/customerid/application
      cp config/linux.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 linux.config files. Refer to page Setup template on Linux - CustomerID for more information about the current configuration options.

      NOTE: If you have made configuration changes to any of the linux.config parameters directly in eidm2.properties file after previously running the setup.sh ensure that these changes are included in the new linux.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 linux.config file.

9. Run the setup script.

   cd /usr/local/ubisecure/customerid/application
   ./setup.sh

10. When upgrading from 5.6 or older, or you have reinstalled Wildfly, configure WildFly. See instructions from WildFly Configuration On Linux. When Wildfly has been started, check each step:
    
    1. Copy the existing SSL certificate to $WILDFLY_HOME/standalone/configuration/keystore.pfx
    2. Set WildFly UndertowRealm and verify HTTPS connection as instructed
    3. Set up customerid.home as instructed
    4. Set up logging as instructed
    5. Set up a mail session as instructed

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

    systemctl start ubilogin-server

12. 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 linux.config: database.driver.path and database.driver.file settings.

       cd /usr/local/ubisecure/customerid/tools
       ./create-datasource.sh

13. When upgrading from 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
14. Upgrade PostgreSQL JDBC driver on SSO side (for supported versions, see System Recommendations)

    1. Transfer the postgresql-x.x.x.jar library to the Ubisecure SSO server and copy it to the following folder: /usr/local/ubisecure/ubilogin-sso/tomcat/lib. See also PostgreSQL JDBC driver installation to SSO on Linux

    2. Restart SSO

       systemctl restart ubilogin-server

15. 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.

    cp -a -u /usr/local/ubisecure/customerid-old/application/custom /usr/local/ubisecure/customerid/application/
    chown -R wildfly:wildfly /usr/local/ubisecure/customerid
    chmod -R o-xrw /usr/local/ubisecure/customerid

    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.
    

16. 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 /usr/local/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 /usr/local/ubisecure/ubilogin-sso/ubilogin/ldap/openldap
       ./import.sh ~/customerid-ldifs/customerid.ldif
       ./import.sh ~/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 /usr/local/ubisecure/ubilogin-sso/ubilogin/ldap/openldap
       ./import.sh ../../../../customerid/application/ldap/customerid.ldif
       ./import.sh ../../../../customerid/application/ldap/customerid-secrets.ldif

17. 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 needs to be running for the deployment to succeed (systemctl start ubilogin-directory) . If you did not reinstall Wildfly when upgrading from 5.7 or newer, you need first start the service and undeploy the EAR files from the previous CustomerID version

     Click here to expand Instructions when Wildfly has not been reinstalled

    1. Start Wildlfy service:

    systemctl start wildfly

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

    cd /usr/local/wildfly-21.0.2.Final/bin

    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:

    [root@localhost bin]# ./jboss-cli.sh --connect --command="undeploy"
    cid-ear-5.7.0.ear         cid-worker-ear-5.7.0.ear  cidpgdriver

    4. Undeploy CustomerID EAR files:

    ./jboss-cli.sh --connect --command="undeploy cid-ear-5.7.0.ear"
    ./jboss-cli.sh --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:

    cd /usr/local/ubisecure/customerid/tools
    ./remove-datasource.sh
    

    If you get error, expand and follow instructions

     If you get error, click here to expand...

    [root@localhost root]# cd /usr/local/ubisecure/customerid/tools
    [root@localhost tools]# ./remove-datasource.sh
    Unregistering JDBC Data Source from Wildfly
    operation-requires-reload: true
    process-state:             reload-required
    Undeploying database driver to Wildfly...
    {"WFLYCTL0062: Composite operation failed and was rolled back. Steps that failed:" => {"Operation step-1" => "WFLYCTL0216: Management resource '[(\"deployment\" => \"postgresql-42.3.1.jar\")]' not found"}}
    
    [root@localhost tools]# cd /usr/local/wildfly-21.0.2.Final/bin
    [root@localhost bin]# ./jboss-cli.sh --connect --command="reload"
    [root@localhost bin]# ./jboss-cli.sh --connect --command="undeploy cidpgdriver"
    [root@localhost bin]# cd /usr/local/ubisecure/customerid/tools

    Add new data source before deploying new CustomerID

    ./create-datasource.sh

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

    cd /usr/local/ubisecure/customerid/tools
    ./deploy-ear.sh ~/customerid/cid-ear-x.x.x.ear
    ./deploy-ear.sh ~/customerid/cid-worker-ear-x.x.x.ear

    Successful deployment will show Deploying CustomerID EAR to Wildfly... Press any key to continue . . .

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