Building a self-learning game with ArangoDB, io.js/NodeJS & AngularJS in half a day.

Introduction and Overview

In this tutorial we want to illustrate a possible architecture of a web application using AngularJS for the frontend in the browser, io.js as application server and ArangoDB as backend database. We are particularly focusing on ArangoDB and its Foxx microservice framework, and only briefly show the io.js and AngularJS parts. In particular, this is not intended to be an AngularJS or io.js tutorial. We even use some shortcuts that one would usually not deploy in production to keep the app simple. Nevertheless, the architecture of the application is in principle suitable as a blueprint for an actual, larger web application.

We are using io.js in the example. However the project will work using node.js as well.

All necessary steps will be described in detail and you can follow the evolution of the system by looking at each stage without typing code yourself.

Our web application will be a guessing game, in which the computer tries to guess a thing or animal you think of by asking a series of questions, for which you provide the answers. Finally, the computer will try to guess what you thought of, if it is wrong, it tries to learn from the experience, such that it can be successful the next time round. If you want to give it a try, surf to

http://guesser.9hoeffer.de:8000

The data from this "machine learning" is kept persistent in the database. We use a single collection storing the questions as well as the guesses, which are organized in a binary tree. Each question node has a left and a right child for the two different answers, and each guess is a leaf in the tree. We do not use a graph data model for this since our queries will only be single document lookups.

During the game the app will simply follow one path in the tree from the root to a leaf, depending on the answers by the user. It will then try a guess, if this is not correct, it will ask the user to provide the right answer and a new question to distinguish that answer from the guess, and finally change the tree, completing the learning process.

The whole creation of the application works in ten basic steps:

1. [Fork the git repository and checkout the initial step.][1]
2. [Install application dependencies][2]
3. [Create a minimal web server using the npm module express and serve a welcome view][3]
4. [Install ArangoDB and set up a place for Foxx app development][4]
5. [Create a minimal Foxx app for the database services][5]
6. [Organize the setup and tear down: create a collection with initial data][6]
7. [Create the question asking view][7]
8. [Create the guessing view][8]
9. [Create the learning view][9]
10. [Deploy the Foxx app in ArangoDB][10]

You will be able to follow the proceedings, because in the git repository that you clone in Step 1 there is a tag for the state after each of the 10 steps, such that you can look at all the code without typing a single line of source code. In the end you will be able to adapt the whole system easily to your own situation.

The Creation

Please note that to be able to run the application at any step you will at least have to do "bower install" in iojs/static/ and "npm install" in iojs/. They will install external dependencies which are NOT contained in the repository.

Prerequisites

Install io.js

Make sure you have io.js (or node.js) installed. We will refer to "iojs" throughout this tutorial. However if you rather want to use node just replace "iojs" with "node" in any commands.

To install io.js download the appropriate package for your operating system from

http://iojs.org/

and install it. We will assume that iojs will be in your $PATH for this tutorial.

Install bower

Bower will be used to manage the frontend dependencies.

Install it using "npm install -g bower". Depending on your system you might have to execute this using sudo (-g installs it globally on your system).

<a name="One"></a>

1. Fork the git repository and checkout the initial step.

Simply do

git clone https://github.com/ArangoDB/guesser.git
cd guesser
git checkout step1

This will create a directory guesser in your current directory and will checkout the state after Step 1, you will only see a license file and a README.md.

<a name="Two"></a>

2. Install application dependencies

To create the io.js backend application

mkdir iojs
cd iojs
npm init -y
npm install --save express arangojs promise concat-stream
mkdir static

The node package manager (npm) needs a file called package.json to work. This file is used to describe the project and its dependencies. We are using npms defaults during init to get the project running as quickly as possible. Have a look at [npm's documentation][11] for an in-depth explanation of the package format.

The install command downloaded all necessary dependencies to develop a base io.js web application which uses arangodb as a database.

We will put static content served by our io.js app in the static folder.

To manage our frontend dependencies we will be using bower.

Just as npm it has its own package format (on which we won't go into detail here).

Execute

cd static
bower init

This will create a bower.json package file in the static directory. For now don't bother about the details and simply press enter during the init wizard process. You should however check out [bowers documentation later][12].

To install AngularJS using bower execute:

bower install --save angularjs

This will create a directory "bower_components" and angularjs should be installed there.

git checkout step2

to see the state of our project after this step. Note that if you actually performed the commands in this step, then the git checkout step2 will complain that it cannot overwrite some files. Simply delete them and do the git checkout step2 again.

<a name="Three"></a>

3. Create a minimal web server using the npm module express and serve a welcome view

We are now in a position to create a minimal web server serving some static content showing a welcome view. To this end, we create the files

iojs/guesser_server.js
iojs/static/index.html
iojs/static/base.css
iojs/static/guesser_controller.js

The guesser server is an io.js application using the express package to serve some static pages for now. See the [AngularJS][13] and [express][14] manuals for explanations. Here it shall suffice to say that the file index.html contains the HTML for the single page, it includes the CSS style sheet base.css, the AngularJS library file angular.min.js and the controller file guesser_controller.js. The latter contains the JavaScript code that is executed in the web browser to take care of the actual user interface, and later to perform AJAX calls back to the io.js server.

Use

git checkout step3

to see the state of our project after this step. After this, you can simply execute

cd iojs
iojs guesser_server.js

to start a web server on port 8000 of your local machine. If you visit

[http://localhost:8000/][15]

(replace localhost by the name or IP address of your server if you try this on a remote machine), you should see the starting page with a blue background and a single input field for your name. The button will not yet respond.

To get a feeling of how easy it is to configure an express server, here is the code that organizes the delivery of a single static page:

var express = require('express');
var app = express();
app.use(express.static(__dirname + "/static"));

and here is the code that creates the actual web server:

var server = app.listen(8000, function () {
  var host = server.address().address
  var port = server.address().port
  console.log('Guesser app server listening at http://%s:%s', host, port)
});

The HTML page is a standard one with a few AngularJS directives, the AngularJS controller is as yet only a stub.

<a name="Four"></a>

4. Install ArangoDB and set up a place for Foxx app development

Download and install ArangoDB as described on the page

https://www.arangodb.com/download

To setup a place to develop a Foxx app, simply create a directory hierarchy like the following anywhere in you file system:

mkdir apps # this is now our <PATH_TO_YOUR_apps_DIR>
cd apps
mkdir -p databases/_system

and either put the guesser repository in the _system folder or create a symbolic link by

ln -s <PATH_TO_guesser_DIR> <PATH_TO_YOUR_apps_DIR>/databases/_system/guesser

Finally, edit the ArangoDB configuration file arangod.conf (which usually resides in /etc/arangodb/arangod.conf) and add a line

dev-app-path = <PATH_TO_YOUR_apps_DIR>

in the javascript section. Restart ArangoDB after this change, on Linux, for example, you do

sudo service arangodb restart

for this. Use

git checkout step4

to see the state of our project after this step, note that nothing in the project has changed for this step.

**Note: You can also start arangodb with a custom dev-app-path by invoking arangod --javascript.dev-app-path=<PATH_TO_YOUR_apps_DIR>.

<a name="Five"></a>

5. Create a minimal Foxx app for the database services

We create the files

manifest.json
guesser.js

Use

git checkout step5

to see the state of our project after this step. The file manifest.json is the starting point for any Foxx app. It contains version, author, license and repository information, and tells ArangoDB what other files are relevant. Here, we install a "controller" in the form of the file guesser.js. It is responsible to define new HTTP routes and contains the JavaScript code to be executed for them. In this step, we define a single new route /hello and install an HTTP GET method for it that simply serves a co