GridDB Deployment Guide for AWS Marketplace

GridDB Community Edition is available as AMI on the AWS Marketplace. This manual describes the basic deployment procedure of GridDB on AWS Marketplace.

For details on GridDB Community Edition, please refer to our GitHub page.

Please visit the GridDB Community Edition Marketplace and follow the onscreen instructions to create GridDB instance in your VPC. We recommend that you create 3 or more instances when configuring a GridDB cluster.

GridDB node requires the following inbound ports to be open:

Protocol	Port range	Description
TCP	22	For operation over SSH.
TCP	10001,10010,10020,10040	GridDB default ports, to communicate with clients and other nodes.

For details on GridDB ports, please refer to "2.3 Configure environment-dependent parameters." of the Quick Start Guide.

You can connect to the EC2 instances via SSH as the centos default OS user once the instances have been deployed and the security group has been configured.

$ ssh -i your_keypair.pem centos@172.17.xx.xx

When you deploy the EC2 instance, the following group and user are created by default in the OS. This OS user is the default operator of GridDB.

Group	User	Home directory
gridstore	gsadm	/var/lib/gridstore

The following environment variables are automatically defined when you login as gsadm.

Environment variables	Value	Meaning
GS_HOME	/var/lib/gridstore	gsadm/GridDB home directory
GS_LOG	/var/lib/gridstore/log	Event log file output directory

[Note]

• These environment variables are used in the operating commands described in the later section.
• As gsadm password is not set by default, please login as the root user and set the password.
  • Some of the functions of the operation tools may be necessary.

To log in as gsadm from centos user, please use the following command.

$ sudo su - gsadm

The following directories and files, as well as the necessary modules and commands are created in the GridDB instance.

/var/lib/gridstore/        # GridDB home directory
     backup/               # Backup directory(unused)
     conf/                 # Directory storing definition files
         gs_cluster.json   # Cluster definition file
         gs_node.json      # Node definition file
         password          # User definition file
     data/                 # Directory storing database files
     log/                  # Directory storing event log files

$ ls /usr/griddb-X.X.X/*
/usr/griddb-X.X.X/RPM-README.md

/usr/griddb-X.X.X/3rd_party:
3rd_party.md            apr              json-simple      picojson  slf4j
activemq-cpp-library    BSD_License.txt  MessagePack      purewell  yield
Apache_License-2.0.txt  ebb              MIT_License.txt  sha2

/usr/griddb-X.X.X/bin:
gridstore-X.X.X.jar       gs_joincluster   gs_startnode    log.py
gridstore-conf-X.X.X.jar  gs_leavecluster  gs_stat         util.py
gs_adduser                gs_passwd        gs_stopcluster
gs_deluser                gsserver         gs_stopnode

/usr/griddb-X.X.X/conf:
gs_cluster.json  gs_node.json  password

/usr/griddb-X.X.X/doc:
manual  sample

When you access and run a GridDB node, the following files are created in the directories to store database files and event log files.

[Database file]

/var/lib/gridstore/        # GridDB home directory
     data/                 # Directory storing database files
         gs_log_n_m.log    # File recording transaction logs (n, m: positive number)
         gs_cp_n_p.dat     # Checkpoint file recording data regularly (n, p: positive number)

[Event log file]

/var/lib/gridstore/              # GridDB home directory
     log/                        # Directory storing event logs
         gridstore-%Y%m%d-n.log  # Event log file

You can change the directories used to store files by editing the relevant parameters in the node definition file.

Please refer to the document below for more information.

• RPM Install Guide

Other documents below are available on our GitHub page.

• Release notes
• GridDB Technical Design Document
• Quick Start Guide
• API Reference

An administrator user is needed for authentication purposes in nodes and clusters. Administrator user information is stored in the User definition file. The default file is shown below.

• /var/lib/gridstore/conf/password

The following user is created by default.

User	Password
admin	No settings

Administrator user information including the default admin user can be changed using the following user administration command in the operating commands.

Command	Function
gs_adduser	Add an administrator user
gs_deluser	Delete an administrator user
gs_passwd	Change the password of an administrator user

Change the default admin password using the gs_passwd command shown below. The password is encrypted during registration.

[Note]

• The default admin password is not set by default. Please make sure to change the password as the server will not start if the administrator user password is not set.

  $ gs_passwd admin
  Password:(Input password)
  Retype password:(Input password again)
  

When adding a new administrator user (not including the default user), the user name has to start with gs#. One or more ASCII alphanumeric characters and the underscore sign "_" can be used after gs#.

An example on adding a new administrator user is shown below.

$ gs_adduser gs#newuser
Password:(Input password)
Retype password:(Input password again)

[Note]

• Changes to the administrator user information take effect after the node is restarted.
• User information is used for client authentication, so the common user information must be registered in all nodes. Please ensure that these information are available in all nodes by copying the user definition file.

/usr/griddb-3.0.0/        # Installation directory
     conf/                # Directory storing definition files
         gs_cluster.json  # Template for cluster definition file
         gs_node.json     # Template for node definition file

/var/lib/gridstore/       # GridDB home directory
     conf/                # Directory storing definition files
         gs_cluster.json  # (Edited) Cluster definition file
         gs_node.json     # (Edited) Node definition file

{
                             :
                             :
  "cluster":{
    "clusterName":"yourClusterName",
    "replicationNum":2,
    "heartbeatInterval":"5s",
    "loadbalanceCheckInterval":"180s",
    "notificationMember": [
     {
        "cluster": {"address":"172.17.xx.xx", "port":10010},
        "sync": {"address":"172.17.xx.xx", "port":10020},
        "system": {"address":"172.17.xx.xx", "port":10040},
        "transaction": {"address":"172.17.xx.xx", "port":10001}
     },
     {
        "cluster": {"address":"172.17.yy.yy", "port":10010},
        "sync": {"address":"172.17.yy.yy", "port":10020},
        "system": {"address":"172.17.yy.yy", "port":10040},
        "transaction": {"address":"172.17.yy.yy", "port":10001}
     },
     {
        "cluster": {"address":"172.17.zz.zz", "port":10010},
        "sync": {"address":"172.17.zz.zz", "port":10020},
        "system": {"address":"172.17.zz.zz", "port":10040},
        "transaction": {"address":"172.17.zz.zz", "port":10001}
      }
    ]
  },
                             :
                             :
}

If you use a Java-based client, please copy the client libraries in the GridDB instance to client instance.

The installed GridDB client libraries are shown below.

/usr/griddb-3.0.0/bin:
gridstore-3.0.0.jar     gridstore-conf-3.0.0.jar

Add the client library paths to CLASSPATH.

$ export CLASSPATH=${CLASSPATH}:/usr/share/java/gridstore-3.0.0.jar:/usr/share/java/gridstore-conf-3.0.0.jar

To connect GridDB instance to the client program on client instance, please specify the connection point and user/password in the client program or Client Properties File.

When using the client for a single node cluster, please specify the "host" and "port" instead of "notificationAddress" and "notificationPort". On the other hand, when using the client for a multiple node cluster, please specify the "notificationMember" instead of "notificationAddress" and "notificationPort".

For details on the NoSQL specifications, please refer to "Class GridStoreFactory" of the GridDB API Reference and "Connection method of client" of the GridDB CE 3.0.0 RELEASE NOTES.

The installed GridDB sample program is shown below.

/usr/griddb-3.0.0/docs/sample/program:
Sample1.java

This sample program is written for multicast connection method. In order to use a unicast or fixed list connection method, we recommend that you use Client Properties File and comment out connection settings in the program.

The following lines are needed to comment out of Sample1.java:

props.setProperty("notificationAddress", args[0]);
props.setProperty("notificationPort", args[1]);
props.setProperty("clusterName", args[2]);
props.setProperty("user", args[3]);
props.setProperty("password", args[4]);

By including both directories which contain the properties file "gs_client.properties" and the configuration library "gridstore-conf-3.0.0.jar" in the classpath, properties of the file are automatically applied to GridStoreFactory. Connection properties can be changed without editing application codes by using the properties file.

Example of gs_client.properties for unicast connection method

store.host=172.17.xx.xx
store.port=10001
store.clusterName=yourClusterName
store.user=admin
store.password=yourpassword

Example of gs_client.properties for fixed list connection method

store.notificationMember=172.17.xx.xx:10001,172.17.yy.yy:10001,172.17.zz.zz:10001
store.clusterName=yourClusterName
store.user=admin
store.password=yourpassword

Add the directory path including the client properties file to CLASSPATH.

$ ls /var/lib/gridstore/client
gs_client.properties
$ export CLASSPATH=${CLASSPATH}:/var/lib/gridstore/client

Compile the program and execute it with the following command.

$ javac -d . Sample1.java
$ java gsSample/Sample1

To update GridDB to the latest release, please download the latest RPM package from our GitHub page and perform a manual reinstallation by following this procedure.

1. Stop the cluster.
2. Stop each node.
3. Uninstall the installed RPM package on each instance.
4. Install the latest RPM package on each instance.