Chapter 7. Titan Server

gremlin-server

Titan uses the Gremlin Server engine as the server component to process and answer client queries.

Gremlin Server provides a way to remotely execute Gremlin scripts against one or more Titan instances hosted within it. By default, client applications can connect to it via WebSockets with a custom subprotocol (there are a number of clients developed in different languages to help support the subprotocol). Gremlin Server can also be configured to serve a simple REST-style endpoint for processing Gremlin as well. These configurations just represent the out-of-the-box options for Gremlin Server. It is certainly possible to also extend it with other means of communication by implementing the interfaces that it provides.

The Titan Download comes pre-configured to run Gremlin Server without any additional configuration. Alternatively, one can Download Gremlin Server separately and then install Titan manually.

7.1. Gremlin Server with Titan

There are two ways to download and install Gremlin Server with Titan.

  1. Titan’s zip downloads come with Gremlin Server, Titan, and BerkeleyDB preconfigured to work together.
  2. Download Gremlin Server separately and then manually install Titan.

Each of these approaches is described below.

7.1.1. Getting Started Quickly

  • Download a copy of the current titan-$VERSION.zip file from the Downloads page
  • Unzip it and enter the titan-$VERSION directory
  • Run bin/gremlin-server.sh. This step will start Gremlin Server with a BerkeleyDB instance.

7.1.2. Manual Installation

This section describes the process of downloading a stock Gremlin Server distribution and then installing Titan.

Gremlin Server can be downloaded at here.

Edit the GREMLIN_SERVER_HOME/conf/gremlin-server.yaml and include the following settings to the defaults:

...
graphs: {
  g: conf/titan-berkeleydb.properties}
plugins:
  - aurelius.titan
...

The entry for graphs defines the bindings to specific TitanGraph configurations. In the above case it binds g to a Titan configuration at conf/titan-berkeleydb.properties. This means that when referencing the TitanGraph in remote contexts, this graph can simply be referred to as g in scripts sent to the server. The plugins entry simply enables the Titan Gremlin Plugin, which enables auto-imports of Titan classes so that they can be referenced in remotely submitted scripts.

Next add a conf/titan-berkeleydb.properties file which should contain something like:

storage.backend=berkeleyje
storage.directory=../db/berkeley

Gremlin Server needs to have Titan and its related library dependencies made available to it. It has an ext directory where these libraries can be placed on Gremlin Server’s path. To get Titan on the path, issue the following command (it may take a few minutes to complete this step depending on network speed):

$ bin/gremlin-server.sh -i com.thinkaurelius.titan titan-all $VERSION

Start Gremlin Server with:

$ bin/gremlin-server.sh

7.2. Connecting to Gremlin Server

Regardless of the download and installation method chosen above, Gremlin Server will be ready to listen for WebSocket connections when it is started. The easiest way to test the connection is with Gremlin Console.

Start Gremlin Console with bin/gremlin.sh and use the Remote and Submit commands to issue Gremlin to Gremlin Server:

$  bin/gremlin.sh
         \,,,/
         (o o)
-----oOOo-(3)-oOOo-----
plugin activated: tinkerpop.server
plugin activated: tinkerpop.utilities
plugin activated: aurelius.titan
plugin activated: tinkerpop.tinkergraph
gremlin> :remote connect tinkerpop.server conf/remote.yaml
==>Connected - localhost/127.0.0.1:8182
gremlin> :> g.addVertex("name","stephen")
==>v[256]
gremlin> :> g.V().values('name')
==>stephen

The :remote command tells the console to configure a remote connection to Gremlin Server using the conf/remote.yaml file to connect. That file points to a Gremlin Server instance running on localhost. The :> is the "submit" command which submits the Gremlin on that line to the currently active remote - in this case, the remote is Gremlin Server.