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
• (Optional) 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-<version>-<buildNo>.tgz
7. Unzip hii-bmc-<buildNumber>.zip and overwrite the existing files in the /opt/bmc/hii directory.
   

8. Perform the following steps to upgrade the database if the database version is earlier than 3.10.6:
   

   Tip

   Use the following command to obtain the database version: docker image ls | grep arango #

   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
9. If SSL was configured before upgrade, go to step 10. If SSL was not configured before upgrade, configure it and skip to step 11. For instructions, see To configure SSL for BMC Helix Intelligent Integrations. 

10. Start the docker-compose service by using one of the following set of commands:
    

    docker-compose up -d
    docker compose up -d

11. 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 <certificate> with the fully qualified domain name of the server where you are installing the on-premises gateway.

   ssl_certificate /etc/nginx/certs/<certificate>.crt;  #certificate path
   ssl_certificate_key /etc/nginx/certs/<certificate>.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.1 or later 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.