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. 

Upgrading the BMC Helix Intelligent Integrations on-premises gateway involves the following tasks: 

• Upgrade the container images
• Upgrade the database
• Update the collector URL in the third-party product

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 /opt/bmc directory: 
   • Container images: bmc-hii-docker-images-<buildNumber>.tgz
   • Utility file: hii-bmc-<buildNumber>.zip

3. Stop the docker-compose service.
   

   docker-compose down

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

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

6. Load the container images that you have downloaded.
   

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

7. Obtain the database version:
   

   cat docker-compose.yaml | grep image | grep arango
8. Unzip hii-bmc-<buildNumber>.zip and overwrite the existing files in the /opt/bmc/hii directory.
9. Depending on the BMC Helix Intelligent Integrations version and the database version, upgrade the database:
   • (BMC Helix Intelligent Integrations version 24.2.02) Upgrade the database if the version is earlier than 3.11.8.
   • (BMC Helix Intelligent Integrations versions 24.2.01 and earlier) Upgrade the database if the version is earlier than 3.10.6.

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

        #      - --database.auto-upgrade

     2. Uncomment the line as follows:

        - --database.auto-upgrade

     3. Start the docker-compose service.
        

        docker-compose up -d

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

        - --database.auto-upgrade

     5. Comment the line as follows:

        #      - --database.auto-upgrade

     6. Stop the docker-compose service.
        

        docker-compose down

10. Change permissions on the /opt/bmc/hii/logs directory and the /opt/bmc/hii/scripts/iig_noauth.sh file:

    chmod 777 /opt/bmc/hii/logs
    chmod +x /opt/bmc/hii/scripts/iig_noauth.sh

11. Navigate to the  /opt/bmc/hii/scripts directory and run the following command:

    ./iig_noauth.sh -noauth
12. Depending on whether SSL was configured before upgrade, perform the following steps:
    • If SSL was not configured before upgrade, configure it. For instructions, see To configure SSL for BMC Helix Intelligent Integrations.
    • If SSL was configured before upgrade, perform the following steps:
      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

13. Access the BMC Helix Intelligent Integrations UI by using the following URL:
    https://<hostName>: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. 

To configure SSL for BMC Helix Intelligent Integrations

1. Perform one of the following actions to obtain the certificate and private keys:

   • Generate a self-signed certificate by using the following command:
     

     openssl req -x509 -sha256 -days 397 -nodes -newkey rsa:2048 -subj "/CN=<commonName>/C=<countryName>/L=<locality>" -keyout <hostName>.key -out <hostName>.crt

     In the command, replace <hostName> with the fully qualified domain name of the server where you are installing the on-premises gateway.

   • Obtain a CA-signed certificate and private keys from the Certificate Authority.
2. Create the certs directory in the /opt/bmc/hii/conf directory if it does not exist.
3. Copy the certificate and private key you obtained to the /opt/bmc/hii/conf/certs directory, and make sure that the names of the certificate and private key files are in the following format:
   <hostName>.crt and <hostName>.key
   <hostName> is the fully-qualified domain name of the server where you are installing the on-premises gateway.
4. Open the hii/conf/nginx.conf file with a text editor. 

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

   ssl_certificate /etc/nginx/certs/<iihostname>.crt;  #certificate path
   ssl_certificate_key /etc/nginx/certs/<iihostname>.key;  #certificate key
6. Save and close the file.

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

   docker-compose down
   docker-compose up -d
   
   docker compose down
   docker compose up -d

To update the collector URL in the third-party product

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

• You have upgraded to version 24.2 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.

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