Getting started with Docker

Learn how to install, configure, and launch the HCL Compass Docker Containers with RESTful APIs and HCL Compass search.

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.

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 Search 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,

Use the docker pull command to pull the image from the hclcr.io Registry:
```
docker pull hclcr.io/compass/hcl-compass:2.2.0
```

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/compass/hcl-compass:2.2.0
```
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/data/search \
 -v /path/to/your/keystore/:/opt/hcl/compass/compass-rest-server-distribution/data/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/compass/hcl-compass:2.2.0

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, mounting the Search data entity files and the Search data type-ahead files, and mapping the searchPorts numbers defined in the database connection environment variables.
1. Create a new folder /path/to/your/search_data_entity:
```
$ mkdir /path/to/your/search_data_entity
```
2. Copy your search data entity files and search data type-ahead files to the /path/to/your/search_data folder:
```
$ cp [Search_data_entity_file] /path/to/your/search_data/
```
3. 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\")" 
```
4. Mount the search_data folder path to container folder /opt/hcl/compass/compass-rest-server-distribution/data/search
```
-v /path/to/your/search_data_entity/:/opt/hcl/compass/compass-rest-server-distribution/data/search
```
5. 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
```
6. Ensure that the number of Search ports in the range match the number of database connection sets.

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:
1. Create a new folder named path/to/your/keystore:
```
$ mkdir /path/to/your/keystore
```
2. Copy the keystore.p12 file to the path/to/your/keystore folder.
```
$ cp keystore.p12 /path/to/your/keystore/
```
3. Set the SSL password and SSL key-alias environment variables:
```
--env SSL_PASSWORD=[key-store-password]
--env SSL_KEY_ALIAS=[keyAlias number]
```
4. Mount the folder that you created in step A to the container folder /opt/hcl/compass/compass-rest-server-distribution/data/ssl:
```
-v /path/to/your/keystore/:/opt/hcl/compass/compass-rest-server-distribution/data/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.