Installing HCL Compass by using the keycloak.json file

This quick start guide demonstrates how to use Docker Compose to setup and run an HCL Compass with RESTful and Keycloak services that are used for the HCL Compass Single Sign On.

1. Create a new folder named path/to/your/keycloak-json and copy the keycloak.json file in this folder.

   $ mkdir /path/to/your/keycloak-json
   $ cp keycloak.json /path/to/your/keycloak-json/.

2. Create the environment file for configuring Keycloak in HCL Compass.
   Create an environment file named keycloak.env in your project directory and paste in the admin_user_name, admin_user_password, repository_name, and sso_user_name for each repository.

   SSO_ENABLED=TRUE
   SSO_CONFIG_SET=("SSO_CONFIG_1""SSO_CONFIG_2" ..... "SSO_CONFIG_n")
   

   Each SSO configuration SSO_CONFIX_x must be set with the following format:

   -username [Username] -password [User password] -dbset [dbset_name] -ssousername [sso_user_name]

   The following example illustrates the proper configuration for a two SSO configuration. In this case, one is for DefectTracking-SAMPL and the other is for EssentialSAFe-SAMPL repository applications:

   SSO_CONFIG_SET=("-username admin -password "" -dbset DefectTracking  -ssousername SYSTEM_SSO1""-username admin -password "" -dbset EssentialSAFe -ssousername SYSTEM_SSO2")

   Note: The value for [sso_user_name] should be an internal name provided by the administrator. This name should be unique and should not be used for any other function in HCL Compass.
3. Update the hcl-compass service in a Docker compose file.
   Create a YAML file named docker-compose-keycloak.yaml in your project directory as shown below. Paste in the new folder that you created in step 1 for the TLS certificate and private key files.

   version: '3.3'
   services:
     hcl-compass:
       env_file:
         - keycloak.env                          # environment variables file for keycloak configuration in hcl-compass container
   
       volumes:
         - /path/to/your/keycloak-json/:/opt/hcl/compass/compass-rest-server-distribution/data/keycloak   # Mounted volume for the Keycloak.json file

   The docker-compose-keycloak.yaml file updates the hcl-compass service to set additional environment variables for configuring Keycloak in the hcl-compass container.

4. Build and run the HCL Compass application with Docker Compose
   1. From your project directory, start your application by running docker-compuse up.

      $ docker-compose -f docker-compose.yaml -f docker-compose-search-model2.yaml -f docker-compose-ek.yaml up  -d
      
      Creating network "compass_hcl-compass" with driver "bridge"
      Creating volume "compass_hcl-compass-logs" with default driver
      Creating volume "compass_hcl-compass-config" with default driver
      Creating volume "compass_elasticsearch-data" with default driver
      Creating compass_hcl-compass-elasticsearch_1 ... done
      Creating compass_hcl-compass-kibana_1        ... done
      Creating compass_hcl-compass-search1_1       ... done
      Creating compass_hcl-compass-search2_1       ... done
      Creating compass_hcl-compass-nginx_1         ... done
      Creating compass_hcl-compass_1               ... done

   2. After the command has been launched, you can check to see that the service and the container are started by using the following command:

      $ docker-compose -f docker-compose.yaml -f docker-compose-search-model2.yaml -f docker-compose-ek.yaml  ps

5. Optionally, you can view the container logs by using the following command:

   $ docker-compose -f docker-compose.yaml -f docker-compose-search-model2.yaml -f docker-compose-ek.yaml logs

6. Enter https://localhost:8190/ in a browser to see the HCL Compass application running with Single Sign On, search, and Dashboard functionality.