Learn how to install, configure, and launch the HCL Compass Docker Containers with RESTful APIs and
HCL Compass search.
Before you begin
In order to use
HCL Compass with Docker, you must first have the
Docker Engine installed either locally or remotely, depending on your setup. For more information
on installing Docker, see
Install Docker Engine.
Note:
- Each Search configuration requires approximately 5 GB of memory. Ensure that your system
has enough memory before configuring Seach with HCL Compass.
- The Docker compose example in this document includes a two database schema connection and
two search configurations. You will need at least 12 GB of memory to deploy this
configuration.
After you have installed Docker Engine, you must access the
HCL Compass container image from the HCL Entitled
Registry. To access the Entitled Registry:
- Contact your HCL sales representative for the login details required to access the HCL
Entitled Registry.
- After you have the login details, execute the following command to login into the HCL
Entitled
Registry:
docker login -u <your_username> -p <your_entitled_key> hclcr.io
- Use the docker pull command to pull the image from the HCL Entitled
Registry:
docker pull hclcr.io/sofy/services/hcl-compass/hcl-compass:2.0.3.01
Procedure
-
Use the docker run command to start the HCL Compass container from the HCL Compass image.
$ docker run -d --name [container-name] -h [container--host-name] \
--env HCL_CCM_LICENSE_SERVER_URL=[license_url] \
--env HCL_CCM_LICENSE_SERVER_ID=[license_id] \
-p [external_port_number]:8190 \
hclcr.io/sofy/services/hcl-compass/hcl-compass:2.0.3.01
This example includes the minimum settings required to run the HCL Compass container. The HCL FlexNet license
server URL and license server ID fields are required during the installation and should be
provided when the HCL Compass Server
container is created.
The default setting of the internal HCL Compass container port is 8190. You can
select any available external port number and use it to launch the HCL Compass browser by entering
http://localhost:[external_port_number]
.
-
Add environment variables as necessary to support your HCL Compass container configuration.
The following example illustrates the
docker run command with all
supported environment variables for the
HCL Compass
container.
$ docker run -d --name [container-name] -h [container-name] \
--env HCL_CCM_LICENSE_SERVER_URL=[license_url] \
--env HCL_CCM_LICENSE_SERVER_ID=[license_id] \
--env DB_CONNECTION_SET=[(\"connection-1\" \"connection-2\" ..... \"connection-n\")] \
--env SEARCH_ENABLED=TRUE \
--env SEARCH_CONFIG_SET=[(\"SEARCH_CONFIG_1\" \"SEARCH_CONFIG_2\" ..... \"SEARCH_CONFIG_n\")] \
--env SSL_KEY_ALIAS=[keyAlias number] \
--mount source=<Volume name>,destination=<Folder location in the container> \
-v /path/to/your/search_data_entity/:/opt/hcl/compass/compass-rest-server-distribution/config/search \
-v /path/to/your/keystore/:/opt/hcl/compass/compass-rest-server-distribution/config/ssl \
-p [external_port_number]:8190 \
-p [search_host_port]:[search_container_port] \
-p [search_host_port_1]-[search_host_port_n]:[search_container_port_1]-[search_container_port_n] \
hclcr.io/sofy/services/hcl-compass/hcl-compass:2.0.3.01
If you plan to create the Rest-Server-APIs instance container with a database set
connection, the
DB_CONNECTION_SET environment variable must be added to the
docker run
command.
--env DB_CONNECTION_SET=[(\"connection-1\" \"connection-2\" ..... \"connection-n\")]
Each connection must be set with the following
format:
-v [db_vendor] -d [db_name] -s [db_server] -u [user] -p [password] -dbset [dbset_name] -ip [db_server_ip]
The following example illustrates the proper configuration for a two database connection. In
this case, one is for
DefectTracking-SAMPL and the other is for
EssentialSAFe-SAMPL
applications:
--env DB_CONNECTION_SET="(\"-v Oracle -d xe -s oracle_host -u DefMaster -p c0mpass -dbset DefectTracking -ip 10.134.149.18\" \
\"-v Oracle -d xe -s oracle_host -u SafeMaster -p c0mpass -dbset EssentialSAFe -ip 10.134.149.18\")"
-
Configure the search features in the container by setting the Search feature environment
variables, binding the Search data entity file, and map the searchPorts numbers defined in the
database connection environment variables.
- Create a new folder
/path/to/your/search_data_entity:
$ mkdir /path/to/your/search_data_entity
- Copy your search data entity file to the
/path/to/your/search_data_entity
folder:
$ cp [Search_data_entity_file] /path/to/your/search_data_entity/
- Set the search feature environment
variables:
--env SEARCH_CONFIG_SET=[(\"SEARCH_CONFIG_1\" \"SEARCH_CONFIG_2\" ..... \"SEARCH_CONFIG_n\")]
Each
Search configuration must be set with the following
format:
-username [Username] -password [User password] -dbset [dbset_name]
-userdb [User database] -searchPort [search_port_number]
The
following example illustrates the proper configuration for a two Search
configuration. In this case, one is for
DefectTracking-SAMPL and
the other is for
EssentialSAFe-SAMPL
applications:
--env SEARCH_CONFIG_SET="(\" -username admin -password \"\" -dbset DefectTracking -userdb SAMPL -searchPort 8983\" \"-username admin -password \"\" -dbset EssentialSAFe -userdb SAMPL -searchPort 8984\")"
- Mount the search data entity file folder path to container folder
/opt/hcl/compass/compass-rest-server-distribution/config/search
-v /path/to/your/search_data_entity/:/opt/hcl/compass/compass-rest-server-distribution/config/search
- Set the search ports mapping. The number search port mapping in the range must match the
number of database
connections.
-p [search_host_port]:[search_container_port] # One search port mapping
-p [search_host_port_1]-[search_host_port_n]:[search_container_port_1]-[search_container_port_n] # Range of Search ports mapping
-
If you need to update the default full text search properties values, you must add the
SEARCH_PROPERTIES_VALUE_SET environment variable and set your new
properties values during deployment of the containers.
--env SEARCH_PROPERTIES_VALUE_SET="(\"-IndexWorkspace <true/false> -MaxHeapSize <val> -RetryAttempts <val> -RetryAttemptsPause <val> -IncrIndexMaxHeapSize <val> -FullIndexMaxHeapSize <val> -ProcRetryAttempts <val> -ProcRetryAttemptsPause <val>\")"
For example, to change the amount of memory that Solr uses, you can limit it to
512mb:
--env SEARCH_PROPERTIES_VALUE_SET="(\"-MaxHeapSize 512\")"
To limit memory for the indexer as well (both full and
incremental):
--env SEARCH_PROPERTIES_VALUE_SET="(\"-MaxHeapSize 512 -IncrIndexMaxHeapSize 512 -FullIndexMaxHeaPSize 512\")"
-
Install the SSL certificate:
- Create a new folder named
path/to/your/keystore:
$ mkdir /path/to/your/keystore
- Copy the keystore.p12 file to the
path/to/your/keystore
folder.
$ cp keystore.p12 /path/to/your/keystore/
- Set the SSL password and SSL key-alias environment
variables:
--env SSL_PASSWORD=[key-store-password]
--env SSL_KEY_ALIAS=[keyAlias number]
- Mount the folder that you created in step A to the container folder
/opt/hcl/compass/compass-rest-server-distribution/config/ssl:
-v /path/to/your/keystore/:/opt/hcl/compass/compass-rest-server-distribution/config/ssl
-
Attach the volume:
--mount source=<Volume name>,destination=<Folder location in the container>
What to do next
After you have installed and configured HCL Compass and Docker, you can learn how to
create new database connections or update database connections on running Docker containers,
upgrade services, and create and attach volumes to the HCL Compass container.