Introduction

Configuring Environment

Ensure that JAVA_HOME variable is defined and points to the the java installation directory on your machine. To verify, execute the following:

$ echo $JAVA_HOME

If you do not see any output, JAVA_HOME is not defined. We need to add the following line to your profile located at /home/joe/.bash_profile or /home/joe/.bashrc, whichever you are using. If you do not have any of these files, create a ~/.bash_profile file.

export JAVA_HOME=<Path to Java installation directory>

After you have edited ~/.bash_profile (or ~/.bashrc), execute the following to make the changes effective in current shell:

$ source /home/joe/.bash_profile (or /home/joe/.bashrc)

Before proceeding, verify that JAVA_HOME is defined by executing the following:

$ echo $JAVA_HOME

Configuring SSH

If SSH is not enabled on your system, please follow the instruction below to enable/install it or else skip to the section Configuring Password-less SSH.

sudo apt-get install openssh-server

$ ssh 127.0.0.1

The authenticity of host '127.0.0.1 (127.0.0.1)' can't be established.
RSA key fingerprint is aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.
Are you sure you want to continue connecting (yes/no)?

$ ssh 127.0.0.1
Last login: Sat Mar 23 22:52:49 2013

$ ssh-keygen -t rsa -P ""
Generating public/private rsa key pair.
Enter file in which to save the key (/home/joe/.ssh/id_rsa):
[Important: Please ensure that we use the default value, so simply press enter]

/home/joe/.ssh/id_rsa already exists.
Overwrite (y/n)?

The key fingerprint is:
4d:b0:30:14:45:cc:99:86:15:48:17:0b:39:a0:05:ca joe@joe-machine
The key's randomart image is:
+--[ RSA 2048]----+
|  ..o+B@O=       |
|.. o  ==*+       |
|.E.    oo .      |
|         o       |
|        S .      |
|                 |
|                 |
|                 |
|                 |
+-----------------+

$ cat $HOME/.ssh/id_rsa.pub >> $HOME/.ssh/authorized_keys
$ chmod 700  $HOME/.ssh/authorized_keys

$ ssh 127.0.0.1

The authenticity of host '127.0.0.1 (127.0.0.1)' can't be established.
RSA key fingerprint is aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.
Are you sure you want to continue connecting (yes/no)?

Warning: Permanently added '127.0.0.1' (RSA) to the list of known hosts.
Last login: Thu Mar 28 12:27:10 2013

ssh 127.0.0.1
Last login: Sat Mar 23 22:54:40 2013

$ exit
logout
Connection to 127.0.0.1 closed.

Configuring Managix

You will need the AsterixDB installer (a.k.a. Managix). Download the Standalone Cluster installer from here; this includes the bits for Managix as well as AsterixDB.

We will refer to the directory containing the extracted files as MANAGIX_HOME and we assume that MANAGIX_HOME/bin is on your PATH.

To be able to create an AsterixDB instance and manage its lifecycle, Managix requires you to configure a set of configuration files namely:

• conf/managix-conf.xml: A configuration XML file that contains configuration settings for Managix.
• A configuration XML file that describes the nodes in the cluster, e.g., clusters/local/local.xml.

Since we intend to run AsterixDB on a single node, Managix can auto-configure itself and populate the above configuration files. To auto-configure Managix, execute the following in the MANAGIX_HOME directory:

/home/joe/asterix-mgmt> $ managix configure

Let us do a sample run to validate the set of configuration files auto-generated by Managix.

/home/joe/asterix-mgmt> $ managix validate
  INFO: Environment [OK]
  INFO: Managix Configuration [OK]

/home/joe/asterix-mgmt> $ managix validate -c clusters/local/local.xml
  INFO: Environment [OK]
  INFO: Cluster configuration [OK]

Creating an AsterixDB instance

Now that we have configured Managix, we shall next create an AsterixDB instance. An AsterixDB instance is identified by a unique name and is created using the create command. The usage description for the create command can be obtained by executing the following:

$ managix help -cmd create
Creates an AsterixDB instance with a specified name. Post creation, the instance is in ACTIVE state,
indicating its availability for executing statements/queries.
Usage arguments/options:
-n Name of the AsterixDB instance.
-c Path to the cluster configuration file

We shall now use the create command to create an AsterixDB instance by the name “my_asterix”. In doing so, we shall use the cluster configuration file that was auto-generated by Managix.

$ managix create -n my_asterix -c clusters/local/local.xml

A sample output of the above command is shown below:

INFO: Name:my_asterix
Created:Thu Mar 07 11:14:13 PST 2013
Web-Url:http://127.0.0.1:19001
State:ACTIVE

The third line above shows the web-url http://127.0.0.1:19001 for an AsterixDB’s web interface. The AsterixDB instance is in the ‘ACTIVE’ state, indicating that you may access the web interface by navigating to the web url.

Type in the following “Hello World” query in the box:

let $message := 'Hello World!'
return $message

Press the “Run” button. If the query result shows on the output box, then Congratulations! You have successfully created an AsterixDB instance!

AsterixDB Runtime

An AsterixDB runtime comprises of a ‘‘master node’’ and a set of ‘‘worker nodes’’, each identified by a unique id. The master node runs a ‘‘Cluster Controller’’ service (a.k.a. ‘‘CC’’), while each worker node runs a ‘‘Node Controller’’ service (a.k.a. ‘‘NC’’). Please note that a node in an AsterixDB cluster is a logical concept in the sense that multiple nodes may map to a single physical machine, which is the case for a single-machine AsterixDB installation. This association or mapping between an AsterixDB node and a physical machine is captured in a cluster configuration XML file. In addition, the XML file contains properties and parameters associated with each node.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cluster xmlns="cluster">
    <name>local</name>
    <java_home>/usr/lib/jvm/jdk1.8.0</java_home>
    <log_dir>/home/joe/asterix-mgmt/clusters/local/working_dir/logs</log_dir>
    <txn_log_dir>/home/joe/asterix-mgmt/clusters/local/working_dir/logs</txn_log_dir>
    <iodevices>/home/joe/asterix-mgmt/clusters/local/working_dir</iodevices>
    <store>storage</store>
    <working_dir>
        <dir>/home/joe/asterix-mgmt/clusters/local/working_dir</dir>
        <NFS>true</NFS>
    </working_dir>
    <master_node>
        <id>master</id>
        <client_ip>127.0.0.1</client_ip>
        <cluster_ip>127.0.0.1</cluster_ip>
        <client_port>1098</client_port>
        <cluster_port>1099</cluster_port>
        <http_port>8888</http_port>
    </master_node>
    <node>
        <id>node1</id>
        <cluster_ip>127.0.0.1</cluster_ip>
    </node>
</cluster>

<master_node>
    <id>master</id>
    <client_ip>127.0.0.1</client_ip>
    <cluster_ip>127.0.0.1</cluster_ip>
    <client_port>1098</client_port>
    <cluster_port>1099</cluster_port>
    <http_port>8888</http_port>
</master_node>
<node>
    <id>node1</id>
    <cluster_ip>127.0.0.1</cluster_ip>
</node>

<working_dir>
    <dir>/Users/joe/asterix-mgmt/clusters/local/working_dir</dir>
    <NFS>true</NFS>
</working_dir>

Managix Configuration

Managix allows creation and management of multiple AsterixDB instances and uses Zookeeper as its back-end database to keep track of information related to each instance. We need to provide a set of one or more hosts that Managix can use to run a Zookeeper instance. Zookeeper runs as a daemon process on each of the specified hosts. At each host, Zookeeper stores data under the Zookeeper home directory specified as part of the configuration. The following is an example configuration $MANAGIX_HOME/conf/managix-conf.xml that has Zookeeper running on the localhost (127.0.0.1) :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration xmlns="installer">
    <zookeeper>
        <homeDir>/home/joe/asterix/.installer/zookeeper</homeDir>
        <clientPort>2900</clientPort>
        <servers>
            <server>127.0.0.1</server>
        </servers>
    </zookeeper>
</configuration>

It is possible to have a single host for Zookeeper. A larger number of hosts would use Zookeeper’s replication and fault-tolerance feature such that a failure of a host running Zookeeper would not result in loss of information about existing AsterixDB instances.

Step (1): Configure SSH

The steps of setting up SSH are similar to those in the single-machine setup case. We assume we have a common user account called “joe” on each machine in the cluster.

On the master machine, do the following:

machineA> ssh 127.0.0.1

If you get an output similar to one shown below, type “yes” and press enter.

The authenticity of host '127.0.0.1 (127.0.0.1)' can't be established.
RSA key fingerprint is aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.
Are you sure you want to continue connecting (yes/no)?

If you are not prompted for a password, that is if you get an output similar to one shown below, it signifies that you already have password-less SSH configured.

$ ssh 127.0.0.1
Last login: Sat Mar 23 22:52:49 2013

[Important: Password-less SSH requires the use of a (public,private) key-pair. The key-pair is located as a pair of files under $HOME/.ssh directory. It is required that the (public,private) key-pair files have default names (id_rsa.pub, id_rsa) respectively. If you are using different names, please rename the files to use the default names]

If you are prompted for a password, execute the following

machineA> ssh-keygen -t rsa -P ""
machineA> cat $HOME/.ssh/id_rsa.pub >> $HOME/.ssh/authorized_keys
machineA> chmod 700  $HOME/.ssh/authorized_keys

If $HOME is not on the NFS, copy the id_rsa.pub to the directory ~/.ssh (login with the same account) on each machine, and then do the following on each machine. (Notice that this step is not needed if the folder “.ssh” is on the NFS and can be accessed by all the nodes.)

cd ~/.ssh
cat id_rsa.pub >> authorized_keys
chmod 700  $HOME/.ssh/authorized_keys

Then run the following step again and type “yes” if prompted:

machineA> ssh 127.0.0.1

Step (2): Define the AsterixDB cluster

We first log into the master machine as the user “joe”. On this machine, download the Standalone Cluster installer from here (save as above), then do the following steps similar to the single-machine case described above:

machineA> cd ~
machineA> mkdir asterix-mgmt
machineA> cd asterix-mgmt
machineA> unzip  <path to the Managix zip bundle>

Note that it is recommended that MANAGIX_HOME is not located on a network file system (NFS). Managix creates artifacts/logs that are not required to be shared. Any overhead associated with creating artifacts/logs on the NFS should be avoided.

We also need an AsterixDB configuration XML file for the cluster. We give the name to the cluster, say, “rainbow”. We create a folder for the configuration of this cluster:

machineA> mkdir asterix-mgmt/rainbow_cluster

For this cluster we create a configuration file $MANAGIX_HOME/rainbow_cluster/rainbow.xml. The following is a sample file with explanation of the properties:

<cluster xmlns="cluster">

  <!-- Name of the cluster -->
  <name>rainbow</name>

  <!-- username, which should be valid for all the three machines -->
  <username>joe</username>

  <!-- The working directory of Managix. It is recommended for the working
       directory to be on a network file system (NFS) that can accessed by
       all machines.
       Managix creates the directory if it it doesn't exist. -->
  <working_dir>
    <dir>/home/joe/managix-workingDir</dir>
    <NFS>true</NFS>
  </working_dir>

  <!-- Directory for Asterix to store worker logs information for each machine.
       Needs to be on the local file system of each machine.
       Managix creates the directory if it doesn't exist.
       This property can be overriden for a node by redefining at the node level. -->
  <log_dir>/mnt/joe/logs</log_dir>

  <!-- Directory for Asterix to store transaction log information for each machine.
       Needs to be on the local file system of each machine.
       Managix creates the directory if it doesn't exist.
       This property can be overriden for a node by redefining at the node level. -->
  <txn_log_dir>/mnt/joe/txn_logs</txn_log_dir>

  <!-- Mount point of an iodevice. Use a comma separated list for a machine that
       has multiple iodevices (disks).
       This property can be overriden for a node by redefining at the node level. -->
  <iodevices>/mnt/joe</iodevices>

  <!-- Path on each iodevice where Asterix will store its data -->
  <store>storage</store>

  <!-- Java home for each machine -->
  <java_home>/usr/lib/jvm/jdk1.8.0</java_home>

  <!-- IP addresses of the master machine A -->
  <master_node>
    <id>master</id>
    <client_ip>128.195.52.177</client_ip>
    <cluster_ip>192.168.100.0</cluster_ip>
    <client_port>1098</client_port>
    <cluster_port>1099</cluster_port>
    <http_port>8888</http_port>
  </master_node>

  <!-- IP address(es) of machine B -->
  <node>
    <id>nodeB</id>
    <cluster_ip>192.168.100.1</cluster_ip>
  </node>

   <!-- IP address(es) of machine C -->
  <node>
    <id>nodeC</id>
    <cluster_ip>192.168.100.2</cluster_ip>
  </node>
</cluster>

As stated before, each of the above properties can be defined at the cluster level, in which case it applies to all the nodes in the system. Each property can also be defined at a node level.

Once we have formed the cluster XML file, we can validate the configuration by doing the following:

managix validate -c rainbow_cluster/rainbow.xml

This will verify the contents of the file, and also attempt to ssh to each node in the cluster to ensure that password-less SSH is configured correctly. You may see output like

The authenticity of host '192.168.100.1 (192.168.100.1)' can't be established.
RSA key fingerprint is 89:80:31:1f:be:51:16:d7:2b:f5:e0:b3:2c:bd:83:94.
Are you sure you want to continue connecting (yes/no)?

and this output may be repeated for each node in the cluster. Answer “yes” each time.

If the final output contains the following lines (possibly separated by the RSA prompts mentione above):

INFO: Environment [OK]
INFO: Cluster configuration [OK]

it means that the XML configuration file is correct!

Step (3): Configuring Managix

Managix uses a configuration XML file at $MANAGIX_HOME/conf/managix-conf.xml to configure its own properties, such as its Zookeeper service. We can use the configure command to auto-generate this configuration file:

machineA> managix configure

We use the validate command to validate the Managix configuration. To do so, execute the following.

machineA> managix validate
INFO: Environment [OK]
INFO: Managix Configuration [OK]

Note that the configure command also generates a cluster configuration XML file at $MANAGIX_HOME/clusters/local/local.xml. This file is not needed in the case of a cluster of machines.

Step (4): Creating an AsterixDB instance

Now that we have configured Managix, we shall next create an AsterixDB instance, which is identified by a unique name and is created using the create command. The usage description for the create command can be obtained by executing the following:

machineA> managix help -cmd create

Creates an AsterixDB instance with a specified name. Post creation, the instance is in ACTIVE state,
indicating its availability for executing statements/queries.
Usage arguments/options:
-n Name of the AsterixDB instance.
-c Path to the cluster configuration file

We shall now use the create command to create an AsterixDB instance called “rainbow_asterix”. In doing so, we shall use the cluster configuration file that was auto-generated by Managix.

machineA> managix create -n rainbow_asterix -c clusters/rainbow.xml

If the response message does not have warning, then Congratulations! You have successfully installed AsterixDB on this cluster of machines!

Please refer to the section Managing the Lifecycle of an AsterixDB Instance for a detailed description on the set of available commands/operations that let you manage the lifecycle of an AsterixDB instance. Note that the output of the commands varies with the cluster definition and may not apply to the cluster specification you built above.