Running HCL Detect

Starting and stopping HCL Detect

Starting HCL Detect requires two steps.

First, we must ensure that the environment of the current shell is properly configured. This is accomplished by invoking the script that performs this task:

$ ./<installation-location>/drive/bin/environment_setter

Note:

Modifying the PATH environment variable in the user's .bashrc file

The environment_setter script loads the user's .bashrc file (if it exists) and, subsequently, validates that the execution environment is not modified inadvertently with respect to the needs of HCL Detect.

Specifically, the environment_setter validates that the executables for the Java Virtual Machine (java) and the Python interpreter (python) are consistent with the ones needed by HCL Detect.

In case an inconsistency is flagged due to a modification of the user's PATH environment variable in .bashrc, an error message will be emitted and two corrective alternatives are possible.

If it happens to be an irrelevant/unintended misconfiguration, you can simply eliminate it from your .bashrc file.

If the original behavior needs to be preserved, this can be accomplished by conditionally making the following modification to the PATH environment variable:

if [[ -z ${HCL_PRODUCT:-} ]]; then
    export PATH=<path_to_custom_python>:<path_to_custom_jdk>:$PATH
fi

HCL_PRODUCT is an environment variable defined by HCL Detect in the new instance of the Bash shell the environment_setter starts.

By checking for this environment variable and conditionally updating the PATH variable only when it is not defined, the conflicting settings will not affect HCL Detect's runtime environment. Yet, when a regular shell is instantiated, those PATH settings will still remain active.

Next, we start all of the HCL Detect services:

$ <installation-location>/drive/bin/services_manager start

At this point, it is possible to open a browser on any computer with access to the server where HCL Detect is installed and access its web user interface by pointing the browser to the appropriate URL: https://HCL.acme.com/drive.

If everything has worked correctly, you will be presented with the initial setup workflow, whereby an administration password will be configured as well as other initialization steps.

If you cannot access the HCL Detect UI, the Testing and troubleshooting the web proxy installation section provides a few troubleshooting instructions that will help you ensure that your configuration is correct.

Finally, we can stop the HCL Detect services:

$ <installation-location>/drive/bin/services_manager stop

Advanced options when starting and stopping Detect

HCL Detect can be started using the services_manager script located at $HCL_HOME/bin.

This script can be used to configure various parameters associated with the execution of the HCL Detect platform. A list of available parameters can be obtained as follows:

$ cd $HCL_HOME
$ ./bin/services_manager --help

 usage: services_manager [-h] [-a] [-c path] [-i id] [-k] [-o [app [app ...]]]
                     [-r] [-p] [-s] [-t] [-u uri]
                     operation

 The 'services_manager' application is part of HCL Detect 1.2.0 (build id:
 HCLadmin@ubdev.HCL.com - commit id:
 465f0374ffc53c20139e54ed9575ef81505c8ca3)

 positional arguments:
   operation             specifies the operation to be performed, one of:
                         'start_applications', 'start', 'stop', 'check',
                         'stop_applications'

 optional arguments:
   -h, --help            show this help message and exit
   -a, --disable-fastpast
                         indicates that FastPast should not be checked (when
                         checking the status of Detect services), started (when
                         starting the Detect services), or stopped (when
                         stopping the Detect services) (default: False)
   -c path, --drive-config-file path
                         specifies the path of the HCL Detect
                         configuration file (default: None)
   -i id, --instance-id id
                         specifies the instance identifier to use (default:
                         None)
   -k, --disable-kafka
                         indicates that Kafka should not be checked (when
                         checking the status of the services), started (when
                         starting the services), or stopped (when stopping the
                         services) (default: False)
   -o [app [app ...]], --applications-to-run [app [app ...]]
                         specifies the list of Detect applications to use (by
                         default, all of them are used)
   -r, --disable-pinpoint
                         indicates that PinPoint should not be checked (when
                         checking the status of the services), started (when
                         starting the services), or stopped (when stopping the
                         services) (default: False)
   -p, --disable-campaign-actuator
                         indicates that Campaign Acturator should not be checked
                         (when checking the status of the services), started
                         (when starting the services), or stopped (when
                         stopping the services) (default: True)
   -s, --disable-segment-updater
                         indicates that Segment Updater should not be checked
                         (when checking the status of the services), started
                         (when starting the services), or stopped (when
                         stopping the services) (default: False)
   -t, --disable-tomcat  indicates that Tomcat should not be checked (when
                         checking the status of the services), started (when
                         starting the services), or stopped (when stopping the
                         services) (default: False)
   -u uri, --instance-uri uri
                         specifies the instance URI to use (default: None,
                         indicating that a self-managed Name Service will be
                         started and used)

The user responsible for managing HCL Detect (typically HCLadmin) can start HCL Detect using the following command:

$ ./bin/services_manager start
Starting Name Service
--- running as process id 27981
--- instance URI is 'redis://10.0.2.15:34549/HCLadmin'
Starting Kafka
--- running Kafka as process id 27991
--- running Zookeeper as process id 27983
Starting FastPast
--- running as process id 27994
--- waiting for FastPast to initialize (done)
Starting PinPoint
--- running as process id 27995
--- waiting for PinPoint to initialize (done)
Starting Tomcat
--- running as process id 28051
--- waiting for HCL Drive to initialize.................. (done)
Starting application 'Segment Updater'
--- running as process id 28181
Starting feed applications: 'Topup Demo', 'Mobile Usage'
Starting application 'Topup Demo'
--- running as process id 28193
Starting application 'Mobile Usage'
--- running as process id 28209

After its execution, the HCL Detect web-based user interface is accessible by opening the http://<hostname>:8080/Detect URL in a browser.

HCL Detect can be stopped by invoking the following command:

$ ./bin/services_manager stop
Stopping feed applications: 'Topup Demo', 'Mobile Usage'
Stopping application 'Topup Demo'
--- waiting for application 'Topup Demo' to terminate.
--- stopped process id 28193
Stopping application 'Mobile Usage'
--- waiting for application 'Mobile Usage' to terminate.
--- stopped process id 28209
Stopping application 'Segment Updater'
--- waiting for application 'Segment Updater' to terminate.
--- stopped process id 28181
Stopping Tomcat
--- waiting for Tomcat to terminate.
--- stopped process id 28051
Stopping PinPoint
--- waiting for PinPoint to shutdown its servers.
--- waiting for PinPoint to terminate.
--- stopped process id 27995
Stopping FastPast
--- waiting for FastPast to shutdown its servers.
--- waiting for FastPast to terminate.
--- stopped process id 27994
Stopping Kafka
--- waiting for Kafka to terminate.
--- stopped process id 27991
--- waiting for Zookeeper to terminate.
--- stopped process id 27983
Stopping the Name Service
--- stopped process id 27981

Once the stop sequence is complete, the web-based user interface is not available anymore.

The sample services_manager invocation we used earlier starts up all applications available as part of your installation. The HCL Detect administrator user can, of course, make use of the other parameters associated with the script. For instance, in order to start the services only with a single application named Topup Demo (assuming it is available as part of your installation), the following command can be used:

$ ./bin/services_manager start -o 'Topup Demo'
Starting Name Service
--- running as process id 28730
--- instance URI is 'redis://10.0.2.15:57173/HCLadmin'
Starting Kafka
--- running Kafka as process id 28741
--- running Zookeeper as process id 28735
Starting FastPast
--- running as process id 28743
--- waiting for FastPast to initialize (done)
Starting PinPoint
--- running as process id 28744
--- waiting for PinPoint to initialize (done)
Starting Tomcat
--- running as process id 28798
--- waiting for HCL Drive to initialize.................. (done)
Starting application 'Segment Updater'
--- running as process id 28896
Starting feed applications: 'Topup Demo'
Starting application 'Topup Demo'
--- running as process id 28903

While the detailed status of the HCL Detect services can be examined via the web-based user interface, the services_manager script can also be used to get a brief status of all services. An example invocation is as follows:

$ ./bin/services_manager check
Kafka is UP
Zookeeper is UP
FastPast is UP
PinPoint is UP
Tomcat is UP
application 'Segment Updater' is UP
application 'Topup Demo' is UP
application 'Mobile Usage' is DOWN

While the services are up, the services_manager script can be used start and stop individual applications. For instance, the following command can be used to start the ‘Mobile Usage' application:

$ ./bin/services_manager start_applications -o 'Mobile Usage'
Starting feed applications: 'Mobile Usage'
Starting application 'Mobile Usage'
--- running as process id 29058

A running application can be stopped in a similar way. For instance, the following command can be used to stop the ‘Mobile Usage' application:

$ ./bin/services_manager stop_applications -o 'Mobile Usage'
Stopping feed applications: 'Mobile Usage'
Stopping application 'Mobile Usage'
--- waiting for application 'Mobile Usage' to terminate.
--- stopped process id 29058