Overview

In this section, the Automated Deployment method for Syndeia Cloud on Linux OS is presented. In the Automated Deployment method, Syndeia admins will run scripts that download and configure Syndeia Cloud and its infrastructure components - Cassandra, JanusGraph, Kafka, and Zookeeper.

There is also an option to first download Syndeia Cloud and its infrastructure components, and then run the automated scripts to install. This is useful when deploying Syndeia in an air-gapped environment. See the Offline Installation Mode (Optional) section below to learn more.

Syndeia admins must perform the Automated Deployment (presented here) or one of the alternatives listed in Deployment Methods. For efficient support, please do not deviate from the guides or alter the scripts. If your organization wants assistance crafting their own deployment practices, contact us at Intercax.com/help for a Services engagement.

Prerequisites Summary

1. Software and Hardware Requirements - Please read Software and Hardware Requirements before getting started.

   • Hardware must meet specified requirements.

     • The syndeia-cloud-3.7.1_cassandra_zookeeper_kafka_setup.zip file now includes a script to automatically check this under bin named syndeia-cloud_pre-reqs_checker.bash.

     • This will be automatically run during the Cassandra pre-setup

   • Software must meet specified version requirements.

2. Supported OS & shell:

   1. Preferred and Recommended - RHEL/Alma Linux v8.X with Console and/or SSH access enabled (see Software and Hardware Requirements for more specific details)

      • ( INFORMATIONAL: SC Web Ports 9000 (HTTP) | 9443 (HTTPS) will be opened automatically by adding a firewall service definition /etc/firewalld/services/syndeia.xml)

      • bash shell is used

3. Software: Compatibility Layer Components

   1. Linux:

      1. JRE/JDK (automatically installed during Cassandra installation)

4. Software: Infrastructure Components (automatically downloaded OR can use offline mode, see below)

   1. Apache Cassandra

   2. Janusgraph

   3. Apache Zookeeper

   4. Apache Kafka

5. Software: Syndeia Cloud (SC) Components

   1. Syndeia Cloud (SC) media file .ZIPs downloaded : Download .ZIPs from password-protected links provided in the Intercax Helpdesk request where you originally received your Syndeia Cloud license. Filenames for each are as follows.

      1. syndeia-cloud-3.7.1_cassandra_zookeeper_kafka_setup.zip

      2. syndeia-cloud-3.7.1_janusgraph_setup.zip

      3. syndeia-cloud-3.7.1.zip

6. Software: Intercax License Server

   1. RLM-based Intercax License Server 15.1 must be up and running if using a floating license. See this document for installation instructions if one has not been set up: Linux - Intercax License Server Installation and Setup

   2. A valid license file must be present in the home directory of the user/admin that will be running the installation scripts.

      1. If the Intercax License Server is serving floating licenses, then you must create a License Pointer File as described here: License Pointer File Creation.

      2. If you are using node-locked license, then you must have downloaded the node-locked license available with your Syndeia downloads.

      3. The License Pointer File (for floating licenses) or the node-locked license file will be used when deploying Syndeia Cloud later in this process.

   3. Please see Syndeia Licensing for details regarding license types. If you need help acquiring a license, you can open a ticket at intercax.com/help.

Installation Logging

Offline Installation Mode (Optional)

Steps

Extract SC Media

1. Launch a Terminal with bash (ensure you are in your home directory)

2. Place all SC packages in your home directory

3. Install the unzip utility, if it isn’t installed on the OS

   sudo yum install unzip

4. Unzip all SC packages:
   find . -iname "syndeia-cloud-3.7.1*.zip" -exec unzip {} \;

Deploy Apache Cassandra

1. cd to the cassandra_zookeeper_kafka_setup package’s bin directory:

   cd ~/syndeia-cloud-3.7.1*_cassandra_zookeeper_kafka_setup/bin

2. Patch the Apache Cassandra pre-setup script:

   SCRIPT=syndeia-cloud_cassandra_pre-setup.bash; EXPECTED_MD5=29573c2f31e9cff22dcce5fa4f477195 [ "$(md5sum "$SCRIPT" | awk '{print $1}')" = "$EXPECTED_MD5" ] && PATCH_OK=1 || { echo "ERROR: unexpected $SCRIPT checksum; not patched"; PATCH_OK=0; } [ "$PATCH_OK" = 1 ] && sed -i.bak.$(date +%Y%m%d%H%M%S) -e '599d' -e '609d' "$SCRIPT" && bash -n "$SCRIPT"

3. Run the Apache Cassandra pre-setup script:

   ./syndeia-cloud_cassandra_pre-setup.bash -a

   What this will do:
   - -a will automatically maintain backwards compatible non-prompting (automated mode) behavior to automatically configure Cassandra with the default recommended settings.
   - Check the machine against the documented minimum requirements a single-node “all-in-one” topology deployment of SC 3.7.1, and if it meets the minimum requirements…
   - Download Cassandra and install/upgrade to the version in the Requirements or if already downloaded, simply install it.

Verification:

1. Verify Cassandra is up and functioning by running nodetool status:
   If you are on Linux:

   nodetool status

   You should get output similar to the following:

   Datacenter: dc1 ======================= Status=Up/Down |/ State=Normal/Leaving/Joining/Moving -- Address Load Tokens Owns (effective) Host ID Rack UN 192.168.1.3 644.57 KiB 256 100.0% 141c21db-4f79-476b-b818-ee6d2da16d7d rack1

Deploy Apache Zookeeper (ZK)

1. Run the Apache Zookeeper (ZK) pre-setup script:

   ./syndeia-cloud_zookeeper_pre-setup.bash

   This will download Apache Zookeeper and install/upgrade to the version in the Requirements or if already downloaded, simply install it

Verification

1. Verify Zookeeper is up and functioning by running zkCli.sh:

   sudo -u zookeeper /opt/zookeeper-current/bin/zkCli.sh -server localhost:2181

   You should get output similar to the following:

   Connecting to localhost:2181 Welcome to ZooKeeper! JLine support is enabled WATCHER:: WatchedEvent state:SyncConnected type:None path:null [zk: localhost:2181(CONNECTED) 0]

   Note, to quit, type quit

Deploy Apache Kafka

1. Run the Apache Kafka pre-setup script.

   ./syndeia-cloud_kafka_pre-setup.bash

   This will download Apache Kafka and install/upgrade to the version in the Requirements or if already downloaded, simply install it

Verification

1. Verify Kafka is up and functioning by creating a test topic, producer with test events and a consumer that replays them:

   /opt/kafka-current/bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

   Acting as the topic producer, enter the following command, wait, and then enter the two topic lines:

   /opt/kafka-current/bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092
   Test event1 Test event2

   To exit, hit CTRL-C
   
   

2. Now, acting as a topic consumer, run the following command and wait a few moments:

   /opt/kafka-current/bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

   You should see:

   Test event1 Test event2

   To exit, hit CTRL-C

Deploy JanusGraph (JG)

1. cd to the janusgraph_setup package’s bin directory:

   cd ~/syndeia-cloud-3.7.1*_janusgraph_setup/bin

2. Run the JanusGraph (JG) pre-setup script:

   ./syndeia-cloud_janusgraph_pre-setup.bash

   This will download JanusGraph and install/upgrade to the version in the Requirements or if already downloaded, simply install it

3. Run the (main) JanusGraph (JG) setup script, ie:

   ./syndeia-cloud_janusgraph_setup.bash

Verification:

1. Verify JG is up and functioning by running the Gremlin client, ie:

   /opt/janusgraph-current/bin/gremlin.sh

   Then execute the following commands after it starts up:

   :remote connect tinkerpop.server conf/remote.yaml session :remote console graph = ConfiguredGraphFactory.open('syndeia_cloud_graph'); // should return: ==>standardjanusgraph[cql:[cassandra.mydomain.com]] g = graph.traversal(); g.V(); g.E(); // The last 2 commands above should not return any results since the graph (syndeia_cloud_graph) is empty - no vertices or edges.

   To exit, type :quit

Deploy Syndeia Cloud (SC)

1. cd to the syndeia-cloud package’s bin directory:

   cd ~/syndeia-cloud-3.7.1/bin

2. Run the Syndeia Cloud (SC) pre-setup script:

   ./syndeia-cloud_install_pre-setup.bash

3. Ensure that there is a valid license pointer file or node-locked license file in the user's home directory.

4. Run the Syndeia Cloud (SC) setup script, ie:

5. Confirm that the output of the script looks like the output in the expandable content above (syndeia-cloud_install.bash sample output). It should end with the following line:

If the output looks like the message in the expandable section below, this indicates that you have an issue with your license. Please refer to requirement 6 in the requirements section at the beginning of this document.

Verification

On the server and/or your local machine, launch a web browser & check the following to validate that the application is correctly running:  

1. http://<syndeia_server_FQDN>:9000 should give you:  

   Open

   

   Fig. 1: Syndeia Cloud login prompt

    

   To log in as the default administrator and create users, see the user management section of the post-deployment document: Post-Deployment Configuration.

2. Once logged in, please verify you see:

   1. a bar graph gets rendered on the Dashboard home page and

   2. the installed version shows correctly under Help > About in the sidebar.

      Open

      
      Open

      

      Fig. 2: Syndeia Cloud Help > About

       

       

       

Review the following sections to learn about monitoring the services and locating service logs.

How to Manage Services & Check Logs

Services

Services are all managed using systemd’s systemctl command with a verb, ie: status, start, stop, restart, followed the service name, ie: cassandra, janusgraph, zookeeper, kafka, sc-SC-short-service-name(s) (or sc-* to reference all SC services). For more information run systemctl --help and/or man systemctl .

Example usage for Cassandra, Zookeeper, Kafka, JanusGraph, and Syndeia Cloud follows:

Apache Cassandra

• To check the summary status:

  sudo systemctl status cassandra

• To start the service:

  sudo systemctl start cassandra

• To stop the service:

  sudo systemctl stop cassandra

• To restart the service:

  sudo systemctl restart cassandra

Apache Zookeeper

• To check the summary status:

  sudo systemctl status zookeeper

• To start the service:

  sudo systemctl start zookeeper

• To stop the service:

  sudo systemctl stop zookeeper

• To restart the service:

  sudo systemctl restart zookeeper

Apache Kafka

• To check the summary status:

  sudo systemctl status kafka

• To start the service:

  sudo systemctl start kafka

• To stop the service:

  sudo systemctl stop kafka

• To restart the service:

  sudo systemctl restart kafka

JanusGraph

• To check the summary status:

  sudo systemctl status janusgraph

• To start the service:

  sudo systemctl start janusgraph

• To stop the service:

  sudo systemctl stop janusgraph

• To restart the service:

  sudo systemctl restart janusgraph

Syndeia Cloud

Syndeia Cloud 3.7.1 is defined by two sets of services:

1. SC 3.7.1 Core Services: sc-store, sc-auth, sc-graph, sc-web-gateway

2. SC 3.7.1 Integration Services ( = New!) : sc-aras, sc-artifactory, sc-ado , sc-codebeamer , sc-bitbucket, sc-collaborator, sc-confluence,sc-dt,sc-doors, sc-dscr, sc-dse3, sc-github, sc-genesys, sc-gitlab, sc-jama, sc-jira,sc-pipeline , sc-polarion , sc-restful, sc-swpdm , sc-sysmlv2, sc-tc, sc-testrail, sc-twcloud, sc-volta, sc-wc

• To check the summary status for a specific service, ex: web-gateway:

  sudo systemctl status sc-web-gateway

• To start a specific service, ex: web-gateway:

  sudo systemctl start sc-web-gateway

• To stop a service, ex: web-gateway:

  sudo systemctl stop sc-web-gateway

• To restart a service, ex: web-gateway:

  sudo systemctl restart sc-web-gateway

Logs & Monitoring

Logs on Linux can be viewed using the journalctl command, ex: sudo journalctl -xeu service-name, ie: cassandra, janusgraph, zookeeper, kafka, sc-SC-short-service-name(s)

Raw log files are located in the following locations:

Apache Cassandra

Apache Zookeeper

Zookeeper creates a log file of the form zookeeper-accountName -server-serverFQDN .log

This is cumbersome, so for simplicity we have created a symlink to it as zookeeper.log

Apache Kafka

Apache Kafka generates several files with the extension .log in its logs folder

Most of these files constitute Kafka’s DB, the only one that is of concern for diagnostics/troubleshooting is the one named server.log

JanusGraph

Syndeia Cloud

For single-node deployments, one can use the common logs directory with symlinks to every service’s logs folder (this is useful is say one wishes to quickly archive all logs to submit for troubleshooting)

For an individual service’s logs, log files will be under:

… where ${service_name} = any one from the below two sets of services:

1. SC 3.7.1 Core Services: store, auth, graph, web-gateway

2. SC 3.7.1 Integration Services ( = New!) :sc-aras, sc-artifactory, sc-ado , sc-codebeamer , sc-bitbucket, sc-collaborator, sc-confluence, sc-dt ,sc-doors, sc-dscr , sc-dse3 ,sc-github, sc-genesys , sc-gitlab, sc-jama, sc-jira,sc-pipeline , sc-polarion , sc-restful, sc-swpdm , sc-sysmlv2, sc-tc, sc-testrail, sc-twcloud, sc-volta, sc-wc

   Note, teamcenter has an additional logs subfolder under logs/SOA for the logs generated by the Siemens SOA client libs.

Troubleshooting

The pre-setup scripts have been tested on the documented platforms so most scripts should execute reliably (ideally flawlessly).

However having said that, it’s always possible that:

• you may have missed a step (or steps)

• you have a non-standard environment

• there’s a genuine bug

If you do experience any issues, please perform the following before opening that Helpdesk ticket:

1. Review the output: if you notice an error, stop! VS simply moving forward (this is one of the reasons trace mode was (currently) left enabled VS hiding the output).

2. Uninstall & try again: Try following the instructions below to reset to a clean state and start over (in case a step (or steps) were missed) :

Uninstall