Quick start

Getting Forest Bus up and running

Intro

This quick start guide walks through the steps to get Forest Bus running on localhost.  For more detail on running Forest Bus across multiple physical servers and configuration options please see the administration guide.

Running a single server

A Forest Bus server requries an empty directory in which to write both configuration and topic data.  In these examples these are stored in ~/forest-data/ - the directory can be stored anywhere with write access.

To start-up a single server, download and install the server, and start it up:

> forest-bus-server -id testcluster -cbor :5000 -name :3000 -http :8000 -path ~/forest-data/bus0

This starts the server with the following configuration:

• An ID of "testcluster".  This is used to group together servers under a single identity.
• The interface name and port number to listen on for cbor connections.  This is used to support Java and Python clients.
• The http interface and port number.  This allows Forest Bus Monitor to connect and provide information on the internal status of Forest Bus.
• The path to an empty directory that Forest Bus will use for configuration and data storage.

Now that there is an instance of forest-bus-server running, it needs to be configured as a one node cluster:

> forest-admin -id testcluster peers :3000
Configuration set successfully on node :3000

In addition to sending configuration data to the forest-bus-server, the forest-admin command will also create a file called "testcluster.nodelist" containing the list of servers in this cluster ID.  This allows subsequent commands to be sent to the whole cluster, without writing out each node.

The final step in getting a single server setup is to create a topic:

> forest-admin -id testcluster topic test
Configuration set successfully on node :3000

The forest bus server is now ready to use.  To test everything is working correctly, we can send a message to the queue using the forest-send command:

> echo "Test Message: Hello World" | forest-send -forestbus testcluster#test@localhost:3000
Messages sent - completing
Read 1 messages, sent 1 messages succesfully and 0 errors.

The forest-send command reads lines from stdin and sends them to the specified topic.  This can be useful for more than just testing - it can be used to send CSV files or web server log files to a topic for parsing and handling.

To verify that the message has been stored we can retrieve it with the forest-get command:

> forest-get -forestbus testcluster#test@localhost:3000
Test Message: Hello World
Recieved 1 messages from index 1
Maximum available message index: 1

The forest-get command writes each message retrieved to stdout on a new line.  The information messages are written to stderr, allowing the output of forest-get to be redirected to a file or piped into additional commands.

Both forest-send and forest-get use the -forestbus connection string format of [cluster-id]#topic@host:port[,host:port]

Setting up a cluster

Forest Bus works well as a standalone server, but it can also be configured as a distributed cluster.  When working in this way a leader among the cluster is automatically chosen for each topic (allowing topic leadership to be spread among the nodes), with the other nodes being followers that replicate messages and serve them up to clients.

This guide covers setting up a three node cluster all running on the localhost.  The same principals apply when running each node on it's own physical machine.

To start with run two more instances of forest-bus-server:

> forest-bus-server -id testcluster -cbor :5001 -name :3001 -http :8001 -path ~/forest-data/bus1
> forest-bus-server -id testcluster -cbor :5002 -name :3002 -http :8002 -path ~/forest-data/bus2

To establish the cluster use the forest-admin command to give the list of peers to all servers:

> forest-admin -id testcluster peers :3000,:3001,:3002
Configuration set successfully on node :3000
Configuration set successfully on node :3001
Configuration set successfully on node :3002

After this step there will be regular errors printed out on the console from the server forest-bus-server instance.  This is because it is trying to hold an election (determine the leader) for the test topic, which the new servers do not yet know about.  To fix this us the forest-admin command again:

> forest-admin -id testcluster -node :3001,:3002 topic test
Configuration set successfully on node :3001
Configuration set successfully on node :3002

The first server will quickly become the leader and replicate all the messages in the topic to the other two servers.  This can be checked by running the forest-get command against each server in turn:

> forest-get -forestbus testcluster#test@localhost:3001
Test Message: Hello World
Recieved 1 messages from index 1
Maximum available message index: 1