Getting started with Docker Compose

Docker Compose is a tool that is used for running dockerized applications in a development environment.

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.
Docker Compose relies on Docker Engine. In order to use HCL Compass with Docker Compose, you must first have the Docker Engine and Docker Compose installed either locally or remotely, depending on your setup. For more information on installing Docker Compose and Docker Engine, see Install Docker Compose.
After you have installed Docker Compose and Docker Engine, you must access the HCL Compass container image from the HCL Entitled Registry. To access the Entitled Registry:
  1. Contact your HCL sales representative for the login details required to access the HCL Entitled Registry.
  2. 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
  3. The image to use in your docker-compose.yaml file is:
    hclcr.io/compass/hcl-compass:2.1.0

About this task

You can create RESTful servcies for HCL Compass running on Docker Compose by performing the following steps:

Procedure

  1. Define the HCL Compass RESTful service dependencies.
    Create a directory for the project:
    $ mkdir compass
    $ cd compass
  2. Create environment files for the HCL Compass license and database connection environment variables.
    1. Create an environment file named license.env in your project directory and paste the license URL and license ID into the file:
      HCL_CCM_LICENSE_SERVER_URL=<license_url>
      HCL_CCM_LICENSE_SERVER_ID=<license_id> 
    2. Create an environment file named db.env in your project directory and set DB_CONNECTION_SET to list your connections database set. 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.
      DB_CONNECTION_SET=<("connection-1" "connection-2" ..... "connection-n")>
      You can set as many connections as you need in the DB_CONNECTION_SET. 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> -searchPort <solr_port_number>
      The following databases are supported, and usage examples are as follows:
      Oracle
      -v Oracle -s oracle_host -d orcle -u admin -p admin_pwd -dbset DefectTracking1
      SQL Server
      -v SQL_Server -s sql_host -d sqldb1 -u admin -p pwd -dbset DefectTracking2
      DB2
      -v DB2 -s db2_host-d msiteb -u db2 -p pwd -dbset DefectTracking3

      The --searchPort solr_port_number is needed to enable the search feature in the HCL Compass RESTful service.

      The following example illustrates a db.env file when two database connections exist. In this case, one is for DefectTracking-SAMPL and the other is for EssentialSAFe-SAMPL applications:
      DB_CONNECTION_SET=("-v Oracle -d xe -s oracle_host -u DefMaster -p c0mpass -dbset DefectTracking" "-v Oracle -d xe -s oracle_host -u SafeMaster -p c0mpass -dbset EssentialSAFe")
    3. Optionally, if you plan to install SSL certifications, you must create an environment file named ssl.env in your project directory and set the SSL password and SSL key alias.
      SSL_PASSWORD=<key-store-password>
      SSL_KEY_ALIAS=<keyAlias number>
  3. Define the service in a Docker compose file.
    1. Create a YAML file named docker-compose.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:
          image: hclcr.io/compass/hcl-compass:2.1.0
          hostname: hcl-compass
          env_file:
            - license.env        # environment variables file for the FlexNet license.
            - db.env             # environment variables file for the Database.
          ports:
            - 8190:8190          # port mapping "external:internal". Internal port is for RESTful Server APIs.
          networks:
            - hcl-compass
          volumes:
            - hcl-compass-logs:/opt/hcl/compass/compass-rest-server-distribution/logs
            - hcl-compass-config:/opt/hcl/compass/compass-rest-server-distribution/data
      
      networks:
        hcl-compass:
          driver: bridge
      
      volumes:
        hcl-compass-logs:
        hcl-compass-config:
      The docker-compose.yaml file defines a service called hcl-compass. The hcl-compass service does the following:
      • Pulls the hcl-compass docker image from the repository location with the specific tag
      • Sets the HCL Compass container hostname
      • Sets environment variables that are defined in the license.env and db.env files.
      • Binds the container and the host machine to the exposed port: 8190
      • Creates volume mountpoint folder location for HCL Compass RESTful logs and data folders
    2. Optionally, if you plan to install SSL certificates, you must
      • Create a new folder named path/to/your/keystore that contains the keystore.p12 file for installing an SSL Certificates on HCL Compass Docker container:
        $ mkdir /path/to/your/keystore
      • Add the ssl.env file and mount the path/to/your/keystore folder in the docker-compose.yaml file:
        services:
          hcl-compass:
            env_file:
              - ssl.env
        
            volumes:
              - /path/to/your/keystore/:/opt/hcl/compass/compass-rest-server-distribution/data/ssl:ro
  4. 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 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_1 ... done

      Docker Compose pulls and builds the HCL Compass RESTful service and starts the hcl-compass service.

    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 ps
    3. Optionally, you can view the container logs by using the following command:
      $ docker-compose -f docker-compose.yaml logs
    4. Enter http://localhost:8190/ in a browser to see the HCL Compass application running.

What to do next

After you have installed and configured HCL Compass and Docker Compose, you can work with HCL Compass RESTful and search features in the same Docker Compose service, or in separate Docker Compose services.