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.
Before you begin
Note: Using HCL Compass on Docker and Docker Compose is
not supported when deployed in a production environment. To use HCL Compass in a container in a production
environment, deploy HCL Compass to a
Kubernetes environment.
Before you can
use the Single Sign On (SSO) functionality in HCL Compass, you must first setup HCL Compass with Docker Compose and configure
RESTful, search, and dashboard features by performing the following steps:For more information, see Deploying HCL Compass on SoFy Sandbox.
- Compete steps 1-3 in Getting started with Docker Compose.
- Complete steps 2-3 in Using RESTful and search features in separate Docker Compose services.
- Complete steps 1-2 in Getting started with RESTful, Opensearch, Opensearch Dashboards services.
About this task
hcl-compass
service for RESTful applications with two database connection set.hcl-compass-search1
service for Search application and first database connection set.hcl-compass-search2
service for Search application and second database connection set.hcl-compass-opensearch
service for the Opensearch application in order to support HCL Compass dashboards.hcl-compass-logstash
service for the Logstash application in order to support HCL Compass dashboards.hcl-compass-dashboards
service for the Dashboards application in order to support HCL Compass dashboards.hcl-compass-nginx
service for the Nginix application in order to support HCL Compass dashboards.hcl-compass-keycloak
service for the Keycloak application in order to support HCL Compass Single Sign On.
Procedure
-
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/.
-
Create the environment file for configuring Keycloak in HCL Compass.
Create an environment file named keycloak.env in your project directory, enable Keycloak, enable SSO, and paste in the
admin_user_name
,admin_user_password
,repository_name
, andsso_user_name
for each repository.KEYCLOAK_ENABLED=TRUE KEYCLOAK_REALM_NAM=CCM KEYCLOAK_USERNAME=admin KEYCLOAK_PASSWORD=admin KEYCLOAK_DASBOARDS_CLIENT_ID=dashboards-client KEYCLOAK_DASBOARDS_CLIENT_SECRET=58846041-eb1e-46d8-bac4-b2ba541ff49 SSO_CONFIG_SET=("SSO_CONFIG_1" "SSO_CONFIG_2" ..... "SSO_CONFIG_n")
Each SSO configurationSSO_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. -
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 thehcl-compass
container. -
Build and run the HCL Compass
application with Docker Compose
- 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_opensearch-data" with default driver Creating compass_hcl-compass-opensearch_1 ... done Creating compass_hcl-compass-logstash_1 ... done Creating compass_hcl-compass-dashboards_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
- 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
- From your project directory, start your application by running docker-compuse
up.
-
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
- Enter https://localhost:8190/ in a browser to see the HCL Compass application running with Single Sign On, search, and Dashboard functionality.