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 Getting started with HCL Compass Helm Chart.
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.3
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.3
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] \
--add-host <Database-Hostname>:<Database-IPAddress> \
--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.3
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]
-
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.
- Create a new folder
/path/to/your/search_data_entity:
$ mkdir /path/to/your/search_data_entity
- 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/
- 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]
- 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
- 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
- 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:
- 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/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.