CogTL architecture

CogTL is based on Docker containers. Two different kinds of deployments exist:

Three-tier deployment, preferably with an orchestrator (although it is also possible to deploy CogTL only with simple interconnected containers).
Standalone

Three-tier deployment

A three-tier deployment is the preferred mode of deployment in an enterprise. The objective is to deploy three different kinds of containers, that can be pulled from Docker Hub:

The web front-end(s):

CogTL Admin UI (cogtl-web), contains the CogTL administration web application
PeopleRisk (cogtl-people), the frontend for non-IT users (e.g. risk managers or team leaders), to monitor risks associated with the people in their scope, and define risk profiles

The calculation server (aka "where the magic happens"):

CogTL Core Server (cogtl-server), the main calculation engine

The storage tier:

CogTL Mongo DB (cogtl-mongo), a simple MongoDB server

Notes about the three-tier deployment:

In an enterprise, you may want to use an external existing MongoDB server. See the Integration guide to discover how to proceed.
If you want to access CogTL Admin UI and/or PeopleRisk through https, you will see an invalid certificate as by default, those applications are exposed with a self-signed certificate. Please refer to the Integration guide to install a trusted certificate.

Kubernetes

If deploying CogTL with an Kubernetes orchestrator, you may have to configure liveness (health) and readiness probes for the most sensitive components, to ensure that the orchestrator can check and optionally restart your containers in case of failure.

CogTL server (cogtl-server)

The health probe is available at: http://[container]/cogtl/api/1.0/system/liveness
The readiness probe is available at: http://[container]/cogtl/api/1.0/system/readiness

PeopleRisk (cogtl-people)

The health probe is available at: http://[container]/api/1.0/health
The readiness is available at: http://[container]/api/1.0/ready

"Vanilla" Docker three-tier deployment

You can deploy CogTL as three simple interconnected Docker containers.

Therefore, you just have to start the three containers and interconnect them using container linking.

docker run -d --name cogtl-mongo cognitechs/cogtl-mongo
docker run -d --name cogtl-server --link cogtl-mongo:mongo cognitechs/cogtl-server
docker run -d --name cogtl-web --link cogtl-server:wildfly -p 80:8080 -p 443:8443 cognitechs/cogtl-web

...and for PeopleRisk:

docker run -d --name cogtl-people --link cogtl-server:wildfly -p 80:8080 -p 443:8443 --volume <path_to_your_model.json>/app/assets/config cognitechs/cogtl-people

Please refer to PeopleRisk setup page to discover the structure of the model.json file.

Customizing cogtl-mongo

Note that in this configuration, you may lose all your data whenever you update cogtl-mongo. To avoid this unfortunate effect, you should externalize the storage of the DB:

Either with a Storage volume
Or by mapping a volume from the host machine to the container.

Usage of a Storage volume is the more "compatible" approach, but depending on the maturity of your Docker environment, it may not be the safest (e.g. if you sometimes re-install or re-initialize your Docker machine). To use a Storage volume, first create the volume, then map it to the _cogtl-mongo container:

docker volume create mystorage
docker run -d -v mystorage:/data/db --name cogtl-mongo cognitechs/cogtl-mongo

Mapping a volume from the host machine to the container may be preferred depending on your infrastructure, backup policy, security strategy, etc. It however requires that the host file system is compatible with MongoDB storage requirements. Typically, at the time of writing this documentation, this is not possible under Windows Server.

docker run -d -v /path/to/the/local/storage:/data/db --name cogtl-mongo cognitechs/cogtl-mongo

Customizing cogtl-server

As described in the integration guide, you may certainly want to use an external properties file in order to customize authentication providers, trust store for custom certification authorities, etc. Therefore, you can run the CogTL server container using the following command line:

docker run -d --name cogtl-server --link cogtl-mongo:mongo --volume <local_path_to_props_file>:/opt/jboss/cogtl/props --env cogtl.properties.file=/opt/jboss/cogtl/props/cogtl.properties cognitechs/cogtl-server

If deploying on Kubernetes, you may need liveness and readiness probes. Therefore, you can query the internal port 8180 of this container, with the following URLs:

/cogtl/api/1.0/system/liveness: returns a status 200 if and only if the server is started and last heartbeat didn’t last more than one minute, or if it is starting since less than 3 minutes.
/cogtl/api/1.0/system/readiness: returns a status 200 if and only if the server starting phase has completed.

Important notice: The cogtl-web and cogtl-people containers must have access to the ports 8180 and 8543 of the cogtl-server container. They also internally use the DNS name "cogtl-server", so if deploying on Kubernetes, you must link those containers together with this name.

Customizing cogtl-web

As described in the integration guide, you may certainly want to use a specific TLS certificate for https connection. Therefore, you should also start the server with a mapped external volume containing your files fullchain.pem and privkey.pem:

docker run -d --name cogtl-web --link cogtl-server:wildfly --volume <local_path_to_certs_file>:/opt/cogtl --env COGTL_TLS_DIRECTORY=/opt/cogtl -p 80:8080 -p 443:8443 cognitechs/cogtl-web

If you are in a Kubernetes environment, where containers linking is not a regular practice, you may have to define the hostname of the cogtl-server container, so that cogtl-web can connect to the right server.

To do so, please use the following environment variables:

COGTL_SERVER_HOST: Host name of CogTL server (by default cogtl-server)
COGTL_SERVER_HTTP_PORT: HTTP port of CogTL server (by default 8180)
COGTL_SERVER_HTTPS_PORT: HTTPS port of CogTL server (by default 8543)

For example:

docker run -d --name cogtl-web --volume <local_path_to_certs_file>:/opt/cogtl --env COGTL_SERVER_HOST=cogtl.acme.com --env COGTL_SERVER_HTTP_PORT=80 --env COGTL_SERVER_HTTPS_PORT=443 -p 80:8080 -p 443:8443 cognitechs/cogtl-web

Customizing cogtl-people

Exactly like CogTL Admin UI, as described in the integration guide, you may want to use a specific TLS certificate for https connection to PeopleRisk. Therefore, you should also start the server with a mapped external volume containing your files fullchain.pem and privkey.pem:

docker run -d --name cogtl-people--link cogtl-server:wildfly --volume <local_path_to_certs_file>:/opt/cogtl --env COGTL_TLS_DIRECTORY=/opt/cogtl --volume <path_to_your_model.json>/app/assets/config -p 80:8080 -p 443:8443 cognitechs/cogtl-people

Just like for Admin UI, if you are in a Kubernetes environment, you may have to define the hostname of the cogtl-server container, so that PeopleRisk can connect to the right server.

To do so, please use the following environment variables:

COGTL_SERVER_HOST: Host name of CogTL server (by default cogtl-server)
COGTL_SERVER_HTTP_PORT: HTTP port of CogTL server (by default 8180)
COGTL_SERVER_HTTPS_PORT: HTTPS port of CogTL server (by default 8543)

For example:

docker run -d --name cogtl-people --volume <path_to_your_model.json>/app/assets/config --env COGTL_SERVER_HOST=cogtl.acme.com --env COGTL_SERVER_HTTP_PORT=80 --env COGTL_SERVER_HTTPS_PORT=443 -p 80:8080 cognitechs/cogtl-people

Standalone deployment

The standalone version of CogTL is a packaged version of the three main components of CogTL (Admin UI, Core Server and MongoDB), in an unique container. You should use this version for tests, quick analysis, etc, but it is not recommended for use in production, as multiple configuration features may not be possible, and performance may be limited.

To start a standalone CogTL container with a persistent storage (otherwise you may lose all configuration and data on update/restarts), please follow the following steps:

Create a storage volume : docker volume create mystorage
Start CogTL standalone image: docker run --name cogtl -p 80:8080 -p 443:8443 -v mystorage:/data/db cognitechs/cogtl:latest

You can now access CogTL on the docker machine in http/https.

A few notes:

By default, no user is configured except superadmin, whose password is superadmin.
If you want to access CogTL through https, you will see an invalid certificate as by default, CogTL is exposed with a self-signed certificate. Please refer to the Integration guide to install a trusted certificate.