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.
About this task
This quick start guide demonstrates how to use Docker Compose to
setup and run an HCL Compass with
RESTful and Keycloak to use the HCL Compass Single Sign On service on separate
services.In this example, we will create the following:
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
-
Set up Keycloak.
- The Keycloak Docker image requires you to specify both a private 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/.
-
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.
KEYCLOAK_ENABLED=TRUE
KEYCLOAK_URL=KEYCLOAK_URL>
SSO_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_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.
-
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: hclcr.io/ccm/ccm-keycloak:2.2.2
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-compass container.
The
hcl-compass-keycloak
container is created with a default Realm configuration called
CCM
which includes a default Client ID named
ccm-client 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.
- Creates a default Realm configuration called
CCM
with a default
Client ID called ccm-client, and a default User with username
admin with password admin.
- 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.
-
Build and run the HCL Compass
application with Docker Compose
- From your project directory, start your application by running
docker-compose
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_opensearch-data" with default driver
Creating compass_hcl-compass_keycloak_1 ... done
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 docker-compose-keycloak.yaml ps
-
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
-
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
CCM
realm is already configured, and that it has a default ccm-client
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.
-
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.