Using HCL Compass RESTful and search features in separate Docker Compose services
This quick start guide shows you how to use Docker Compose to setup and run an HCL Compass with RESTful and search features in sepearate Docker Compose services.
Before you begin
For more information, see Deploying HCL Compass on SoFy Sandbox.
- Define the RESTful services.
- Define environment files.
- Define the services in a docker-compose.yaml file.These steps are detailed as steps 1-3 in Getting Started with Docker Compose.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.
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.-
Note: If your configuration requires only one port and one database connection set, skip the steps listed for a second port and database connection set.Note: If your configuration requires more than one port and more than one database connection set, you must have more than one connection defined in the
DB_CONNECTION_SET
in thedb.env
file.
Procedure
-
Create an environment file for the Search feature environment variables.
- Create an environment file named search1.env in your project
directory and paste your username, user password, user database name, and first
database connection set into the
file:
SEARCH_ENABLED=TRUE SEARCH_CONFIG_SET=(-username [Username] -password [User password] -dbset [dbset_name] -userdb [User database] -searchPort 8983} DB_CONNECTION_SET=("-v <db_vendor> -d <db_name> -s <db_server> -u <user> -p <password> -dbset <dbset_name>")
The DB_CONNECTION_SET values must be the same as the values that are set for the first database connection that is set in the db.env file. Note the following:If you need to update the default full text search properties values, you must add the SEARCH_PROPERTIES_VALUE_SET environment variable in the search1.env file and set your new properties values.- In the Compass
Maintenance Tool, ensure that the database host name can be resolved from Docker
and that it matches what you put int the
-s
parameter for theDB_CONNECTION_SET
. - In Compass Designer,
make sure that the address of the user database can also be resolved from
Docker.Note: Valid parameters for the seach.env file include:
SEARCH_ENABLED
: You can set the search configuration to enabled by setting toTRUE
. Setting this value toFALSE
disables the search configuration.USER_NAME
: The user name that is used to login to the user database. The user must have the role of admin.USER_PASSWORD
: The password for the login to the user database.USER_DB
: The user database name.
SEARCH_PROPERTIES_VALUE_SET=("-IndexWorkspace <true/false> -MaxHeapSize <val> -RetryAttempts <val> -RetryAttemptsPause <val> -IncrIndexMaxHe apSize <val> -FullIndexMaxHeapSize <val> -ProcRetryAttempts <val> -ProcRetryAttemptsPause <val>")
- In the Compass
Maintenance Tool, ensure that the database host name can be resolved from Docker
and that it matches what you put int the
- Create an environment file named search2.env in your project
directory and paste your username, user password, user database name, and second
database connection set into the
file:
SEARCH_ENABLED=TRUE SEARCH_CONFIG_SET=(-username [Username] -password [User password] -dbset [dbset_name] -userdb [User database] -searchPort 8984) DB_CONNECTION_SET=("-v <db_vendor> -d <db_name> -s <db_server> -u <user> -p <password> -dbset <dbset_name>")
The DB_CONNECTION_SET values must be the same as the values that are set for the second database connection that is set in the db.env file.Note: If your configuration requires only one port and one database connection set, skip step 1b.If you need to update the default full text search properties values, you must add the SEARCH_PROPERTIES_VALUE_SET environment variable in the search2.env file and set your new properties values for search2.SEARCH_PROPERTIES_VALUE_SET=("-IndexWorkspace <true/false> -MaxHeapSize <val> -RetryAttempts <val> -RetryAttemptsPause <val> -IncrIndexMaxHe apSize <val> -FullIndexMaxHeapSize <val> -ProcRetryAttempts <val> -ProcRetryAttemptsPause <val>")
- Create an environment file named search1.env in your project
directory and paste your username, user password, user database name, and first
database connection set into the
file:
-
Define the service in a Docker compose file.
- Create a YAML file named docker-compose-search-model2.yaml in
your project directory as shown below. Update the image repository and tag it with the
HCL Compass image repository
and tag as needed:
version: '3' services: hcl-compass: links: - hcl-compass-search1:hcl-compass-search1 - hcl-compass-search2:hcl-compass-search2 hcl-compass-search1: image: hclcr.io/compass/hcl-compass:2.2.0 hostname: hcl-compass-search1 env_file: - license.env # environment variables file for the FlexNet license. - search1.env # environment variables file for the search1. ports: - 8983:8983 # search port volumes: - /home/compass/data/:/opt/hcl/compass/compass-rest-server-distribution/data/search networks: - hcl-compass hcl-compass-search2: image: hclcr.io/compass/hcl-compass:2.2.0 hostname: hcl-compass-search2 env_file: - license.env # environment variables file for the FlexNet license. - search2.env # environment variables file for the search2. ports: - 8984:8984 # search port volumes: - /home/compass/data/:/opt/hcl/compass/compass-rest-server-distribution/data/search networks: - hcl-compass
If your configuration requires only one port and one database connection set, your YAML file should look like this:version: '3' services: hcl-compass: links: - hcl-compass-search1:hcl-compass-search1 hcl-compass-search1: image: hclcr.io/compass/hcl-compass:2.2.0 hostname: hcl-compass-search1 env_file: - license.env # environment variables file for the FlexNet license. - search1.env # environment variables file for the search1. ports: - 8983:8983 # search port volumes: - /home/compass/data/:/opt/hcl/compass/compass-rest-server-distribution/data/search networks: - hcl-compass
The docker-compose-model2.yaml file defines two additional services for search,
hcl-compass-search1
andhcl-compass-search2
. You can add as many additional search services as you need based on your database connection set numbers.The
docker-compose-model2.yaml
file updates thehcl-compass
service to create links for hostname of search service, such ashcl-compass-search1
andhcl-compass-search2
.The
hcl-compass-search1
service:- Pulls the hcl-compass docker image from the repository location with specific tag
- Sets the
hcl-compass-search1
container hostname. - Sets environment variables defined in the license.env and search1.env file.
- Binds the container and the host machine to the exposed port 8983 that you defined in the searchPort variable in the search1.env file.
- Creates volume mountpoint folder location for search files.
hcl-compass-search2
service:- Pulls the hcl-compass docker image from the repository location with specific tag
- Sets the
hcl-compass-search2
container hostname. - Sets environment variables defined in the license.env and search2.env file.
- Binds the container and the host machine to the exposed port 8984 that you defined in the searchPort variable in the search2.env file.
- Creates volume mountpoint folder location for search files.
- Create a YAML file named docker-compose-search-model2.yaml in
your project directory as shown below. Update the image repository and tag it with the
HCL Compass image repository
and tag as needed:
-
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 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 compass_hcl-compass-search1_1 ... done Creating compass_hcl-compass-search2_1 ... done Creating compass_hcl-compass_1 ... done
Docker Compose pulls an HCL Compass image, builds an image for HCL Compass RESTful service, and starts the
hcl-compass
,hcl-compass-search1
, andhcl-compass-search2
services. - 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 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 logs
- Enter
http://localhost:8190/
in a browser to see the HCL Compass application running.
- From your project directory, start your application by running
docker-compuse
up