Reference


Installing the TigerGraph Platform


Version 2.1



Document Updated:

This guide describes how to install the TigerGraph platform either as a single node or as a multi-node cluster.  Please use the Table of Contents to go to the appropriate section of this guide.




Preparation



This section is for New Installations.


If you are updating from a previous version of the TigerGraph platform, first read the section below on



Upgrading an Existing Installation



.

Before you can install the TigerGraph system, you need the following:

  1. One or more servers that meets the minimum


    Hardware and Software Requirements v2.1


    with regard to operating system, memory and hard disk space, as well as enough memory and storage to store your
    graph data.
  2. sudo or root privilege.
  3. A license key provided by TigerGraph (not applicable to Developer Edition)
  4. A TigerGraph system package
    .
  5. If your package is a *tar.gz file, you may need to install some software prerequisites.

Obtaining a TigerGraph Package

If you do not yet have a TigerGraph system package, you can request one at

www.tigergraph.com/download/

.

Software Prerequisites for *.tar.gz Packages

If your package is a *tar.gz file, you also need to insure your machine has the following software prerequisites.

  1. Pre-install these basic Linux utilities on your server, if necessary:


    • tar
    • curl
    • ip
    • more
    • uuidgen
    • crontab
    • ssh/sshd
    • netstat
    • semanage
  2. I
    f you are installing
    a cluster, you also need the following:


    • ntpd
    • iptables/firewalld
  3. If you will use the password

    login method (P method) instead of ssh key login method (K method) to install the TigerGraph platform, you will also need the following:


    • sshpass


Single Node Installation

The name of your package may vary, depending on the product edition (e.g., developer or enterprise) and the version (e.g., 2.0.1). For the examples here, we will assume the name is tigergraph-x.y.z.tar.gz.  Substitute the name of your actual package file.

  1. Extract the package:


    Example: extract for <version> = x.y.z
    tar -xzf tigergraph-x.y.z.tar.gz

  2. A folder named


    tigergraph-<version>-offline (or


    tigergraph-<version>-developer)




    will be created. Change into this folder. To Install with default settings, run the install.sh script with commands:


    Example: Default single-server installation for <version> = 2.0.0
    # to install enterprise edition
    cd tigergraph-*/
    sudo ./install.sh -s

    # to install developer edition
    cd tigergraph-*/
    sudo ./install.sh

    The installer will ask you a few questions:

    • Do you agree to the License Terms and Conditions?

    • What is your license key? (not applicable to Developer Edition)

    • Do you want to use the default TigerGraph user name or select/create your own?

    • Do you want to use the default TigerGraph user password or create your own?
    • Do you want to use the default installation folder or select/create your own?

    To see what are the default settings, and to see how customize the installation, read the

    Installation Options

    section below.


    Some license keys are long – over 100 characters long. If you copy-and-paste the license key, be careful not to accidentally include an end-of-line character.





  3. The installer concludes by using ‘su’ to switch to the tigergraph user account.



    To confirm correct operation:

    1. Try the command




      gadmin status








      If the system installed correctly, the command should report that

      zk

      ,

      kafka

      ,

      dict, nginx, gsql,

      and

      Visualization

      are up and ready. Since there is no graph data loaded yet,

      gse

      ,

      gpe

      , and

      restpp

      are not initialized.




    2. Try the command



      gsql --version






  4. Basic installation is now finished!  Please see

    Post-Installation Notes

    below.



Installation Options

The following default settings will be applied if no parameters specified:

  • The installer will create a user called

    tigergraph

    , with password

    tigergraph

    .
  • The root directory for the installation (referred to as <TigerGraph.Root.Dir>) is a folder called

    tigergraph

    located in the tigergraph user’s home directory, i.e.,

    /home/tigergraph/tigergraph

    .

The installation can be customized by running command line options with the install.sh script:

# Installation options of enterprise edition
Usage:
./install.sh (-s|-c) [-u <user>] [-p <password>] [-r <tigergraph_root_dir>] [-l <license_key>]
./install.sh -c -n
./install.sh -h
Options:
-h — show the help
-u — TigerGraph user [default: tigergraph]
-p — TigerGraph password [default: tigergraph]
-r — TigerGraph.Root.Dir [default: <tigergraph_user_home>/tigergraph]
-l — TigerGraph license key
-s — Single server option: install the tigergraph platform on a single server
-c — Cluster option: install the tigergraph platform on a cluster
-n — Non-interactive option: suppress prompts, and continue installation using default config

[NOTE ]: Using option ‘-c -n’ together will non-interactively install the platform
on a cluster with all configurations from config file “cluster_config.json”.
In this case, the config file should be modified before installation, and other options will be ignored.

# Installation options of developer edition
Usage:
./install.sh [-u <user>] [-p <password>] [-r <tigergraph_root_dir>]
./install.sh -h
Options:
-h — show the help
-u — TigerGraph user [default: tigergraph]
-p — TigerGraph password [default: tigergraph]
-r — TigerGraph.Root.Dir [default: <tigergraph_user_home>/tigergraph]
-n — Non-interactive option: suppress prompts, and continue installation using default config



Cluster Installation and Configuration (Enterprise Edition Only)


TigerGraph cluster configuration enables the graph database to be partitioned and distributed across multiple server nodes in a local network (not available in the Developer Edition). The cluster can either be a physical cluster or a network virtual cluster from a cloud service such as Amazon EC2 or Microsoft Azure.


  1. The installation of TigerGraph 2.x has been validated on Amazon EC2 and Microsoft Azure and on a physical on-premises cluster. For Amazon EC2, please make sure all tcp ports are open among all cluster nodes, otherwise service may not start.
  2. In TigerGraph 2.x, the installation machine can be within or outside the cluster. If outside the cluster, the installation machine should be a Linux machine.
  3. Currently, every machine in the cluster must have a sudo user with the same username and password or SSH key
    .
  4. To install a high-availability cluster (with at least 3 nodes), please set HA.option to be “true” for non-interactive installation or answer “yes” to HA question for interactive installation.


During cluster configuration, the user provides the following information:

  • The IP address for each server node, e.g.,
    172.30.3.2
  • The login credentials for the nodes.


Cluster Installation Overview

Cluster installation begins by the user downloading the TigerGraph software package to any Linux machine in the cluster or with access to the cluster nodes

(see

notes above).

When the user runs the installation script with the cluster option, it will either prompt the user for cluster configuration information described above, or if the user requests non-interactive installation, it will read the configuration information from a file


cluster_config.json


located in the same folder with the platform package.  The installer then proceeds to install the product on each of the cluster nodes and to configure the cluster.

The two installation methods, interactive and non-interactive, are described below.


Interactive Mode Installation

In interactive mode, the installer will first ask the same basic questions it asks for single-node installation. It will then ask how many machines are in your cluster. Then it will prompt for the IP addresses of the machines, assigning each machine an alias m1, m2, m3, etc. Next it will ask for sudo user name and credentials information. Last, it will ask the user if they accept some changes to the system. (See non-interactive mode installation below for details about user credentials.)  A screenshot of interactive installation is shown below.




Non-Interactive Mode Installation

For non-interactive mode installation, the user must put all the settings into the file


cluster_config.json


before running the installer. This file is in the folder with your install.sh file and other TigerGraph package files.

the two key parameters to set are the following:


  1. nodes.ip




    Each machine in the cluster is defined as a key:value pair, where the key is a machine alias m1, m2, m3, etc. Use as many key:value pairs as you need, placing the public IP addresses next to each key.  The installer will auto detect the local IP addresses and use them to configure the system. If the installer detects more than one
    local IP
    address, it will ask the user to select one for configuration.





  2. nodes.login




    Two login methods are supported:


    • SSH with password
    • SSH with key file



    For SSH with password, you must input the sudo/root user and its password. For SSH with key file, you may specify the AWS ec2 key file or other key file. If nothing provided, the installer will use default ssh key file such as

    ~/.ssh/id_rsa

    .


  3. HA.option



    If enable.HA is set to “true”, then the system will be configured for a replication factor of 2. For example, if your cluster has 6 machines, 3 will be used for one copy of the data, and 3 will be used for a replica copy of the data.  More advanced configuration is possible after initial setup.  See

    Configuring a High Availability Cluster v2.1

Below is a sample


cluster_config.json


file.


cluster_config.json example
{
“tigergraph.user.name”: “tigergraph”,
“tigergraph.user.password”: “tigergraph”,
“tigergraph.root.dir”: “/home/tigergraph/tigergraph”,
“license.key”: “91583b19abf850cee381168e0e0cd41fcaceba2d734cd3a9e6f5fd393eda71171519710003”,
“nodes.ip”: {
“m1”: “172.30.3.2”,
“m2”: “172.30.3.3”,
“m3”: “172.30.3.4”,
“m4”: “172.30.3.5”
},
“nodes.login”: {
“supported.methods (this is a comment)”: “P. SSH with password; K. SSH with key file (e.g. ec2_key.pem)”,
“notes (this is a comment)”: “All nodes must use the same sudo user, same password, or same key file”,
“chosen.method”: “K”,
“P”: {
“sudo.user.name”: “sudoUserName”,
“sudo.user.password”: “sudoUserPassword”
},
“K”: {
“sudo.user.name”: “centos”,
“ssh.key.file”: “/home/centos/.ssh/gsql_east.pem”
}
},
“HA.option”: {
“Notes of HA.option (this is a comment)”: “option to install high-availability cluster (with at least 3 nodes), default value false”,
“enable.HA”: “false”
}
}

Cluster Installation Commands

After you have planned out your cluster configuration, you are ready to run the installer.

  1. Extract the package.


    Example: extract for <version> = 2.0.0
    tar -xzf tigergraph-x.y.z.tar.gz

  2. A folder named


    tigergraph-<version>-offline


    will be created. Change into this folder.  To run cluster installation in interactive mode, use the -c option:


    Example: Installation with interactive cluster configuration for <version> = 2.0.0
    cd tigergraph-*/

    ## Method 1. Interactive mode
    ./install.sh -c

    To run cluster installation in non-interactive mode, using the settings in the


    cluster_config.json


    file, use the -c and -n (or merged -cn) options:


    Example: Installation with non-interactive cluster configuration <version> = 2.0.0
    cd tigergraph-*/

    ## Method 2. non-interactive
     # step 1: modify the config file “cluster_config.json”
    # step 2:
     ./install.sh -cn

  3. The installer concludes by prompting the user to login to node m1 of the cluster and use ‘su’ to switch to the tigergraph user account.



    To confirm correct operation:

    1. Try the command



      gadmin status



      from any machine in the cluster.

      If the system installed correctly, the command should report that



      zk

      ,



      kafka

      ,

      dict, nginx, gsql,



      and

      Visualization

      are up and ready. Since there is no graph data loaded yet,



      gse

      ,



      gpe

      , and



      restpp



      are not initialized.


    2. Try the command





      gsql --version





      The


      gsql


      command must be run on node m1 of the cluster because the gsql server is installed on m1 only.









  4. Basic installation is now finished!  Please see

    Post-Installation Notes

    below.




Post-Installation Notes


Change Your Password

If you installed with the default password, we recommend that you change it now.


Additional Customization

To perform additional customization, run


gadmin --configure


(

must be on node m1

if it is cluster


), followed by


gadmin config-apply


. The ‘

gadmin config-apply

‘ command must be run on node m1 if it is cluster, since only node m1 contians

pkg_pool

resources. If you configured one or more items of gpe.servers, gse.servers, restpp.servers, kafka.servers, zk.servers, dictserver.servers, gpe.replicas, or gse.replicas, you must reinstall the package by running command


gadmin pkg-install reset


on node m1.

see the appropriate sections of the





TigerGraph System Administrators Guide v2.1



.


Learning To Use TigerGraph

If you are a first-time user:



Upgrading an Existing Installation

Develop Edition upgrade is not supporteder


The Developer Edition is not designed for upgrade from one version to another



It is not possible to upgrade a Developer Edition installation to Enterprise Edition.

This document covers
how to upgrade
to v2.1. To see how to upgrade to other versions, (e.g., from 1.1 to 1.2), see the documentation for the appropriate target version.

Updating from v2.0 to v2.1

v2.0 can be upgraded to v2.1 Enterprise Edition. The data store format and GSQL language scripts in v2.0 are forward compatible to v2.1.

Upgrading from v1.x to v2.x

The data store format between 1.x and 2.x for single servers is forward compatible but not backward compatible. For a single server platform, users can upgrade from 1.x to 2.x without reloading data or recreating the graph schema. Some details of the GSQL language have changed, so some loading jobs and queries will need to be revised and reinstalled.

For a cluster configuration, direct upgrade from 1.x to 2.x is not supported at this time.  Users interested in migrating from 1.x to 2.x need to export their data and metadata, install v2.x, and then reload data and metadata, with some small modifications.  Please contact

support@tigergraph.com

for assistance.

Please consult the Release Notes for all the versions between your current version and your target version (e.g., v2.1) to see a summary of specification changes.  Contain

support@tigergraph.com

for assistance.

Workflow for Direct Upgrade

  1. Verify that your data store is compatible and is eligible for direct update / upgrade.
  2. Review the specification changes and how they may affect your applications (loading jobs and queries).
  3. Stop issuing new commands to your TigerGraph system and allow any operations to complete.
  4. (Recommended) Backup your data, as a precaution.

  5. Follow the procedure at the beginning of this document for installing a new system.  The installer will automatically shut down your system and start it again.




    Be sure to specify the same username as your current installation. Otherwise, if you use a different user name, it will be treated as a new installation, with an empty graph.

  6. Pay attention to output messages during the installation process which may alert you to additional tasks or checks you should perform.

  7. Run the command



    gsql

    to start the GSQL shell. The first time after an update, gsql performs two important operations:


    1. Copies your catalog from your old installation to the new installation

      .

    2. Compares the files in the backup /dev_<datetime>/gdk/gsql/src folder to the new /dev/gdk/gsql/src folder. Pay attention to any files residing in the old folder but not in the new folder.  Review them and copy them to the new folder if appropriate.  See the example below.


  8. Revise and reinstall loading jobs and queries as needed.