Getting started with HCL Compass RESTful and Keycloak services

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. Set up Keycloak.
   • The Keycloak Docker image requires you to specify both a pricate key and a certificate for serving HTTPS over port 8443. You must provide two files:
     • tls.crt: A certificate.
     • tls.key: A private key.
     You must set a keystore password during execution of the keytool and openssl commands. Replace HOST_NAME with your Keycloak hostname or IP address.

     $ keytool -genkey -alias [HOST_NAME] -keyalg RSA -keystore keycloak.jks -validity 10950
     $ keytool -importkeystore -srckeystore keycloak.jks -destkeystore keycloak.p12 -deststoretype PKCS12
     $ openssl pkcs12 -in keycloak.p12 -nokeys -out tls.crt
     $ openssl pkcs12 -in keycloak.p12 -nocerts -nodes -out tls.key

     Createa new folder named path/to/your/keycloak/tls, copy the tls.crt and tls.key files into this folder.

     $ mkdir /path/to/your/keycloak/tls
     $ cp tls.crt /path/to/your/keycloak/tls/.
     $ cp tls.key /path/to/your/keycloak/tls/.

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. You must also provide the Keycloak URL (https://<IP_OR_HOSTNAME>:PORT). The Keycloak IP or Hostname must be the same as the HCL Compass IP or Hostname.

   SSO_ENABLED=TRUE
   SSO_CONFIG_SET=("SSO_CONFIG_1""SSO_CONFIG_2" ..... "SSO_CONFIG_n")
   KEYCLOAK_URL=<KEYCLOAK_URL>

   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. Define the Keycloak 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 <HCL_COMPASS_URL> and the new folder that you created in step 1 for the TLS certificate and private key files.

   version: '3.3'
   services:
     hcl-compass:
       links:
         - hcl-compass-keycloak:hcl-compass-keycloak
       restart: on-failure
       depends_on:
         - "hcl-compass-keycloak"
   
       env_file:
         - keycloak.env                                                   # environment variables file for keycloak configuration in hcl-compass container
   
     hcl-compass-keycloak:
       image: compass-docker-dev-local.us-artifactory1.nonprod.hclpnp.com/compass-keycloak:2.0.4
       hostname: hcl-compass-keycloak
       container_name: hcl-compass-keycloak
   
       environment:
         - KEYCLOAK_USER=admin                                            # Keycloak username
         - KEYCLOAK_PASSWORD=admin                                        # Keycloak password
         - COMPASS_URL=<HCL_COMPASS_URL>                                  # HCL Compass URL
   
       volumes:
         - /path/to/your/keycloak/tls/:/etc/x509/https                    # Mounted volume for the Keycloak tls certificate and key files
   
       ports:
         - 8080:8080
         - 8445:8443                                                      # port mapping "external:internal". Internal port is for Keycloak.
   
       networks:
         - hcl-compass

   The docker-compose-keycloak.yaml file defines one additional service for Keycloak: hcl-compass-keycloak.

   The docker-compose-keycloak.yaml file updates the hcl-compass service to create links for the hostname of the hcl-compass-keycloak service and sets additional environment variables for configuring Keycloak in hcl-comnpass container.

   The hcl-compass-keycloak container is created with a default Realm configuration called HCL-Compass which includes a default Client ID named Compass and a default User with the username admin and password admin.

   The hcl-compass-keycloak service does the following:

   • Pulls the hcl-compass-keycloak docker image from the elasticsearch repository location with the specific tag.
   • Sets the hcl-compass-keycloak container hostname.
   • Sets the environment variable for Keycloak.
   • Binds the container and the host machine to the exposed port: 8445.
   • Creates volume mountpoint folder location for hcl-compass-keycloak TLS certificate and TLS Private key.
   • To update the default Realm name and default Client ID name to your selected name, add the following environment variables to the above docker run command:

      
        environment:
          - KEYCLOAK_REALM_NAME=<Custom_Realm_name> \
          - KEYCLOAK_CLIENT_NAME=<Custom_Client_ID> \

   • To import your own realm configuration file during container deployment, set the KEYCLOAK_IMPORT environment variable to your realm configuration file name and mount the realm configuration folder to a folder in the hcl-compass-keycloak container. For example, if your realm configuration is valled keycloak-realm.json and it is located in /path/to/your/keycloak/realm-file/ folder, add the following to the above docker run command:

     
       environment:
         - KEYCLOAK_IMPORT=/keycloak/<KEYCLOAK_REALM_IMPORT_FILE_NAME>    # Keycloak mounted realm file
       
       volumes:
         - /path/to/your/keycloak_relam_file/:/keycloak                   # Mounted volume for the Keycloak realm file.

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 -f docker-compose-keycloak.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_keycloak_1      ... done
      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 docker-compose-keycloak.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 docker-compose-keycloak.yaml logs

6. Enter https://localhost:8445/ in a browser to start the Keycloak Administration Console using the username and password that were set in the docker-compose-keycloak.yaml file.
   • When you access the Keycloak Administration Console, you will see a default HCL-Compass realm is already configured, and that it has a default Compass Client ID and a default user with username admin.
   • To create more Keycloak users, follow the directions for Creating a User in the Keycloak documentation.
   • For each Keycloak user, you must also create the same user in the HCL Compass user administration for each repository by following the directions for Adding a user.
7. Enter https://localhost:8190/ in a browser to see the HCL Compass application running with Single Sign On, search, and Dashboard functionality. The default Single Sign On user is admin with a default password admin.