Quick Install Guide

The object of this guide is to enable the administrator to install or update the Clarive Software to the lastest version in a simple way using the steps described below.

Prerrequisites

The prerrequisites for the Clarive installation are specified in the Technical Specifications.

Software Download

MongoDB

Clarive runs on top of the MongoDB database. It could be downloaded from the website:

https://www.mongodb.org/downloads

Choose the stable version 3.0.

New Installation

Environment variables

The directory on which you want to unzip the software of Clarive is defined in the environment variable $CLARIVE_BASE. You must to define four more environment variables.

export CLARIVE_BASE=/opt/clarive
export CLARIVE_HOME=$CLARIVE_BASE/clarive
export LD_LIBRARY_PATH=$CLARIVE_BASE/local/lib
export CLARIVE_ENV=your_config
export PATH="$CLARIVE_HOME/bin:$CLARIVE_BASE/local/bin:$CLARIVE_BASE/local/sbin:$PATH"

Marked variables have to be adapted to the environment of the installation. The software unzips the downloaded zipfile in $CLARIVE_BASE.

Inside the variable environment $PATH, it is needed add the route where the MongoDB is:

export MONGO_DB=/opt/mongo
export PATH="$MONGO_DB/bin:$PATH"

New Directories

It's necessary to create the following directories if they weren't added when the unzip of Clarive was done.

$CLARIVE_BASE/config
$CLARIVE_BASE/jobs
$CLARIVE_BASE/logs
$CLARIVE_BASE/tmp/nginx/client

License

The configuration is by default stored in the clarive.yml file located in the directory $CLARIVE_HOME/config. In addition, in this file, the current license is included.

You need to create a configuration file for your environment in $CLARIVE_BASE/config called $CLARIVE_ENV.yml. Include the license in that file.

Use the company license if it was already purchased.

Configuration

The configuration file which has been created for your environment requires a minimum data that allows the correct operation of the tool.

By default, the values that are in the file are the ones that are taken:

$CLARIVE_HOME/config/clarive.yml.

In the environment configuration file values that are necessary will be overwritten.

NGINX Configuration

Nginx is included inside Clarive. However, it is necessary to create a configuration file

$CLARIVE_BASE/config/nginx.conf

Below, an example of nginx configuration:

pid  ../logs/nginx.pid;
events {
    worker_connections  1024;
}

http {
    server {
        listen       80;
        server_name  localhost;

        access_log  ../logs/nginx.access.log  combined;
        error_log   ../logs/nginx.error.log;

        location / {
            proxy_pass http://localhost:3000;

            proxy_redirect     off;
            proxy_set_header   Host             $host;
            proxy_set_header   X-Real-IP        $remote_addr;
            proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Host  $host;
        }
    }
}

MongoDB Configuration

Within the configuration file, it is necessary to specify the mongo database. To do this, in the environment configuration file specify:

mongo:
    dbname: your_database_name

Besides specifying the DataBase that Clarive will use, a configuration file from MongoDBis needed. A possible location could be:

$CLARIVE_BASE/config/mongod.conf

An example of a basic configuration of MongoDB specified in the field could be:

fork=true
dbpath=/opt/mongo/data/
logpath=/opt/clarive/logs/mongod.log
pidfilepath=/opt/clarive/logs/mongod.pid
logappend=true
journal=true
port=27017
bind_ip=127.0.0.1
setParameter=failIndexKeyTooLong=false

Start and Access

Start Nginx

To start nginx as root:

cla exec nginx -c $CLARIVE_BASE/config/nginx.conf

Start MongoDB

To start MongoDB:

mongod -f $CLARIVE_BASE/config/mongod.conf

Start Clarive

Clarive makes a difference between the web part and the dispatcher part and both must started separately:

cla web-start -c your_config --daemon
cla disp-start -c your_config --daemon

cla web-stop -c your_config
cla disp-stop -c your_config

Stop Clarive

As to start, it is necessary to stop both: the web and the dispatcher

cla web-stop -c your_config
cla disp-stop -c your_config

cla web-stop -c your_config
cla disp-stop -c your_config

Access Clarive via Web

The URL to access to the instance of Clarive is:

http://localhost:3000
user: local/root
password: admin

Configuring your OS (Linux)

To make sure you don't encounter memory errors when the system is running at full throttle, we recommend changing your Linux kernel parameters, specially if the OS has not been tuned by a sysadmin.

Warning

All of the changes proposed here require a Linux user with superuser priviledges. If you are not sure of what you're doing, please contact a sysadmin with experience with kernel parameters.

Memory Parameters

The following parameters help asure that Clarive process forks won't run into memory constraints.

vm.overcommit_memory = 1

In most linuxes this parameter can be set with the following command by a superuser:

echo 1 > /proc/sys/vm/overcommit_memory

We also recommend setting the memory ratio to 100 in case the overcommit is eventually set to 2, but this is optional and does not apply with when vm.overcommit_memory = 1.

vm.overcommit_ratio = 100

The superuser can set this ratio with the following command in most linuxes:

echo 100 > /proc/sys/vm/overcommit_ratio

User space Parameters

The ulimit command controls the user space configuration. These configurations are useful for allowing jobs to run more processes and open more files concurrently.

The following configuration can be accessed by doing a ulimit -a. Please refer to the ulimit command help for instructions on how to make changes.

-f (file size): unlimited
-t (cpu time): unlimited
-v (virtual memory): unlimited
-n (open files): 64000
-m (memory size): unlimited
-u (processes/threads): 64000

The most important values is the open files ulimit -n 64000, otherwise the pubsub server will not be able to handle all connected users at once.

TCP Parameters

The following parameters make reassigning TCP ports faster on Linux systems. These are recommended specially if you're getting a port already in use error when starting the Clarive web server.

echo 1 > /proc/sys/net/ipv4/tcp_tw_reuse
echo 1 > /proc/sys/net/ipv4/tcp_tw_recycle

Picking a OS User

Clarive cannot run as a privileged user.

A privileged user is considered a user named root or having UID equal to 0. This will be checked previous to running any cla command.

Clarive is an automation tool that can be extensively customized by its administrators. Even though automation such as rulebooks run under containers, Clarive also allows administrators to setup pipelines or automation code that could inadvertently damage the host system, so giving any of the Clarive server processes unrestricted access to a server, VM or even a container a very bad idea.

We recommend creating a specific user, such as one named clarive and installing all of Clarive assets under such user.

Also, the Job daemon or Dispatcher, which can be started as a separate OS user, ie. clarive-jobs. To start the job daemon and automation processes server separatedly, start cla disp-start under this user, making sure it can read/write all Clarive core folders:

• CLARIVE_BASE/local
• CLARIVE_BASE/logs
• CLARIVE_BASE/jobs
• CLARIVE_BASE/config
• CLARIVE_BASE/tmp
• CLARIVE_BASE/clarive