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

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. For more information, see Deploying HCL Compass on SoFy Sandbox.

Before you can use HCL Compass RESTful services with search features in seperate Docker Compose services, you must first:

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

In this guide, we are creating three services:

hcl-compass service for RESTful application with a two database connection set.
hcl-compass-search1 for the Search application for the first database connection set.
hcl-compass-search2 for the Search application for the 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 the db.env file.

Procedure

Create an environment file for the Search feature environment variables.
1. 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:
  - 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 the DB_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 to TRUE. Setting this value to FALSE 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.
  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.
```
 SEARCH_PROPERTIES_VALUE_SET=("-IndexWorkspace <true/false> -MaxHeapSize <val> -RetryAttempts <val> -RetryAttemptsPause <val> -IncrIndexMaxHe apSize <val> -FullIndexMaxHeapSize <val> -ProcRetryAttempts <val> -ProcRetryAttemptsPause <val>")
```
2. 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>")
Define the service in a Docker compose file.
1. 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.1.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/hcluser/compass/data/:/opt/hcl/compass/compass-rest-server-distribution/data/search
    networks:
      - hcl-compass

  hcl-compass-search2:
    image: hclcr.io/compass/hcl-compass:2.1.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/hcluser/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.1.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/hcluser/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 and hcl-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 the hcl-compass service to create links for hostname of search service, such as hcl-compass-search1 and hcl-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.
  The 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.
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 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, and hcl-compass-search2services.
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 ps
```
3. 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
```
4. Enter http://localhost:8190/ in a browser to see the HCL Compass application running.

What to do next

After logging into the HCL Compass browser, the search box appears in the top right corner of the browser. You can now use search in HCL Compass on Docker Compose.