Upgrading the on-premises gateway by using Docker containers

This topic describes how to upgrade the BMC Helix Intelligent Integrations on-premises gateway by using Docker containers. 

Before you begin

• Review the system requirements and download the container images and utility files.
• Back up the connector configurations, see Backing-up-and-restoring-connector-configurations.

To upgrade the on-premises gateway by using Docker containers

1. Go to the server where you want to upgrade the on-premises gateway.
2. Copy the following files that you have downloaded to the /<IIGateway_INSTALL_DIR> directory: 
   • Container images: bmc-hii-docker-images-<buildNumber>.tgz
   • Utility file: hii-bmc-<buildNumber>.zip
3. Update the container images:

   1. Stop the docker-compose service.
      

      docker-compose down

   2. Delete and purge the existing container images from the local repository. 
      

      docker image prune -a
   3. When prompted to purge all containers, enter Y.

   4. Load the container images.
      

      docker load --input /<IIGateway_INSTALL_DIR>/bmc-hii-docker-images-<buildNo>.tgz

4. Obtain the database version:
   

   cat docker-compose.yaml | grep image | grep arango
5. Navigate to the /opt/bmc/hii/defaults directory and delete the following files if they exist:
   • docker-compose.yaml_Rsso
   • podman-compose.yaml_Rsso
   • nginx.conf_Rsso
6. Unzip hii-bmc-<buildNumber>.zip and overwrite the existing files in the /<IIGateway_INSTALL_DIR>/hii directory.
   
7. Upgrade the database:

   1. Open the /<IIGateway_INSTALL_DIR>/hii/docker-compose.yaml file with a text editor and search for the following line:

      #      - --database.auto-upgrade

   2. Uncomment the line.

      - --database.auto-upgrade

   3. Start the docker-compose service.
      

      docker-compose up -d

   4. Open the /<IIGateway_INSTALL_DIR>/hii/docker-compose.yaml file with a text editor and search for the following line:

      - --database.auto-upgrade

   5. Comment the line.

      #      - --database.auto-upgrade

   6. Stop the docker-compose service.
      

      docker-compose down

8. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/logs directory:

   chmod 777 /<IIGateway_INSTALL_DIR>/hii/logs 

   
   

9. (Applicable if you are upgrading to version 24.3.00) Perform the following steps to disable the authentication:

   1. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/scripts/iig_noauth.sh file:

      chmod +x /<IIGateway_INSTALL_DIR>/hii/scripts/iig_noauth.sh

   2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and run the following command:

      ./iig_noauth.sh -noauth
10. (Applicable if you are upgrading to version 24.3.01) Depending on whether you want to enable or disable the authentication, perform one of the following tasks: 
    • To enable the authentication:
      1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and open the cred.json file with a text editor.
      2. Update the values of the following parameters: 

         • access_key and access_secret_key: Access key and secret key required to access the BMC Helix applications.
           For instructions about how to generate the access key and secret key, see Setting up access keys for programmatic access..
           The keys are generated in the following format: key:<access key>::<secret key>,tenant id: <tenant ID>. Enter <access key> and <secret key> as the values of the access_key and access_secret_key parameters.

           Important

           The access key and secret key must have the Administrators group and the Administrator role assigned.

         • tenant_id: Tenant ID
           Copy the tenant ID from the access key (key:<access key>::<secret key>,tenant id: <tenant ID>).
         • tenant_url: Tenant URL
         • host_name: Name of the server where the on-premises gateway is installed.

      3. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh file:

         chmod +x /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh

      4. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and run the following command:

         ./iig_auth.sh -auth

         After the script file is successfully executed, cred.json and external.conf files are backed up in the /<usehome>/iig_auth folder.

    • To disable the authentication:

      1. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh file:

         chmod +x /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh

      2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and run the following command:

         ./iig_auth.sh -noauth
11. Update the SSL configuration:
    1. Open the hii/conf/nginx.conf file with a text editor.

    2. In the following SSL configuration, replace <iihostname> with the fully qualified domain name of the server where you are upgrading the on-premises gateway.

       ssl_certificate /etc/nginx/certs/<iihostname>.crt;  #certificate path
       ssl_certificate_key /etc/nginx/certs/<iihostname>.key;  #certificate key

    3. Restart the docker-compose service by using one of the following set of commands:
       

       docker-compose down --remove-orphans
       docker-compose up -d
       
       docker compose down --remove-orphans
       docker compose up -d

12. Access the BMC Helix Intelligent Integrations UI by using the following URL:
    https://<hostName>:443/swpui
    <hostName> is the fully-qualified domain name of the server where the on-premises gateway is deployed.
    For example, https://swp-2021-1840-disceks1.abc.com:443/swpui.

    Important

    BMC Helix Portal does not display any tile for the BMC Helix Intelligent Integrations on-premises gateway. Access the UI by using the URL specified in this step. 

After you upgrade

Update the collector URL in the third-party product if the following conditions are satisfied:

• You have upgraded to version 24.3 or later from a version earlier than 24.1 and SSL was not configured before upgrade.
• You are collecting data from a third-party product via the webhook mechanism.

Perform the following tasks to update the collector URL:

1. Access the BMC Helix Intelligent Integrations UI by using the following URL:
   https://<hostName>:443/swpui
2. On the SOURCES panel, click Configure Mediator for the source connection that you created and then expand the <thirdPartyProduct Datatype> panel.
3. On the COLLECTOR CONFIGURATION tab, click copy to copy the existing, auto-generated collector URL and save the URL in a temporary file.
   For example, https://hostA:443/hii/api/mediator/v3/push/9mn-6c97-4c2e-8pc5-12c0asdf.
4. Configure the third-party product again to forward data to BMC Helix Intelligent Integrations.

For the sample instructions to update the collector URL in the third-party product, see To configure a connection with Entuity for collecting incidents data.