GettingStarted

Getting Started

This guide will walk you through the steps to setup a simple instance of Newts running on a single node.

If you are using Newts as part of a solution embedded into another project i.e. OpenNMS you should consult the associated documentation as some of these steps may not be required.

Contents

• Requirements
• Setting up Cassandra
  • Download and extract Cassandra
  • Update configuration for Cassandra data and log directories
  • Start Cassandra in the foreground
• Setting up Newts
  • Download and extract Newts
  • Configure and initialize Newts
  • Start Newts in the foreground
• Testing
  • Write
  • Read
  • Web UI
• Next Steps

Requirements

• Java 7 (OpenJDK, Oracle, etc)
• curl
• tar
• sed

Setting up Cassandra

This section assumes that you're setting up a single, local instance of Cassandra for purposes of evaluating Newts. These steps are not suitable for a production Cassandra cluster, (see the Cassandra Getting Started Guide for help with that). If you already have a running cluster, you can skip this section.

Open a new terminal and:

Download and extract Cassandra

Substitute ${version} below with the version of Cassandra to download. The latest 2.1.x version of Cassandra is recommended (version 2.1.10 at the time of this writing).

# Terminal 1
version=2.1.12
curl http://www.apache.org/dist/cassandra/${version}/apache-cassandra-{${version}}-bin.tar.gz -o "apache-cassandra-#1-bin.tar.gz"
tar zxvf apache-cassandra-${version}-bin.tar.gz
cd apache-cassandra-${version}/

Update configuration for Cassandra data and log directories

Again, this assumes a scratch install of Cassandra in order to test out Newts, so issue the following commands to modify the config so that data is stored in the /tmp/ directory. Do not do this for a system you intend to run in production.

# Terminal 1
sed -i -e "s/var\/lib/tmp/g" conf/cassandra.yaml

Start Cassandra in the foreground

# Terminal 1
bin/cassandra -f

Setting up Newts

Open a new terminal and:

Download and extract Newts

The latest stable release can be downloaded from Github.

# Terminal 2
curl -L https://github.com/OpenNMS/newts/releases/download/1.3.3/newts-1.3.3-bin.tar.gz -o newts-1.3.3-bin.tar.gz
tar xvf newts-1.3.3-bin.tar.gz
cd newts-1.3.3

Configure and initialize Newts

The default Newts config (etc/config.yaml) will connect to localhost at the default port and keyspace, but if you're using your own install of Cassandra then you'll need to edit it accordingly.

To perform a one-time initialization of Newts, and create the Cassandra schema

# Terminal 2
bin/init etc/config.yaml

Note: During initialization, SLF4J may complain about logger implementations, you can safely ignore this.

Start Newts in the foreground

# Terminal 2
bin/newts -c etc/config.yaml

Note: During Newts server startup, you may see warnings about missing compression libraries from the Cassandra driver, you can safely ignore these.

Testing

Open a new terminal and:

Write

Next, we'll download some sample data in the JSON representation that Newts expects, and import them using curl as a quick test that everything is working.

# Terminal 3
curl https://raw.githubusercontent.com/OpenNMS/newts/master/rest/samples.txt -o samples.txt
curl -D - -X POST -H "Content-Type: application/json" -d @samples.txt http://0.0.0.0:8080/samples

Read

Finally, we should be able to read back some of the samples inserted above.

# Terminal 3
curl -D - -X GET 'http://0.0.0.0:8080/samples/localhost:chassis:temps?start=1998-07-09T12:05:00-0500&end=1998-07-09T13:15:00-0500'; echo

Web UI

New in 1.1, is a simple web interface. While too simplistic for most serious applications, the web UI is a handy means of verifying that everything works. Point your browser at http://localhost:8080/ui/, click Debug to insert some random sample data, and then Search to locate and graph it.

Next Steps

Why not try the Global Summary of Day (weather data) demo?