Deploy a gebo agent

This document provides step-by-step instructions on how to deploy a gebo agent. It is comprehensive so that you may copy, paste, and execute the commands and deploy the configurations provided, from beginning to end.

Getting Started

This document is intended to stand alone so that you do not need to read previous tutorial posts. As such, some of the following steps may have already been executed. They do not need to be executed again.

Setup the database

These steps may already have been executed.

Install MongoDB on your system, if you haven’t already:

Start MongoDB by executing this at the command line:

1
sudo service mongodb start

These instructions are also outlined in your new gebo’s README.md.

Setup grunt

1
2
sudo npm install grunt-cli -g
sudo npm install grunt-init -g

The first command enables you to run the grunt installed locally, automatically. The second allows you to call grunt-init on this template.

Get the gebo template

This is going in your ~/.grunt-init/ directory

1
git clone https://github.com/RaphaelDeLaGhetto/grunt-init-gebo.git ~/.grunt-init/gebo

Create a new project:

1
2
3
mkdir myfirstagent
cd myfirstagent
grunt-init gebo

Upon execution gebo-init will prompt you for some input, with some fields prefilled:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Please answer the following:
[?] Project name (myfirstagent)
[?] Description (The best project ever.)
[?] Version (0.0.0)
[?] Project git repository (git://github.com/RaphaelDeLaGhetto/myfirstagent.git)
[?] Project homepage (https://github.com/RaphaelDeLaGhetto/myfirstagent)
[?] Project issues tracker (https://github.com/RaphaelDeLaGhetto/myfirstagent/issues)
[?] Licenses (MIT)
[?] Author name (RaphaelDeLaGhetto)
[?] Author email (daniel@capitolhill.ca)
[?] Author url (none)
[?] What versions of node does it run on? (>= 0.10.0)
[?] Main module/entry point (<project-name>.js)
[?] Npm test command (grunt nodeunit)
[?] Do you need to make any changes to the above before continuing? (y/N)

Once everything is configured to your liking, execute:

1
sudo npm install

Test

If everything has been initialized correctly, the tests will pass:

1
grunt nodeunit

Run the development server

1
node myfirstagent.js

and go to http://localhost:3000. You will be redirected to an HTTPS site, which will require making an exception in your browser, as you currently only have self-signed certificates.

Make a friendo

A gebo will only perform an action if an agent has permission to request that action. These permissions are analogous to Linux-style read/write/execute permissions on an action or database resource.

From the project directory…

Register agent

This is mostly for human agents who need traditional username/password access through some human-agent interface. A friendo does not need to be a registered agent, though a registered agent does need to be a friendo with permissions set to access any given gebo resource (unless that registered agent is an administrator).

1
grunt registeragent:SomeGuy:someguy@example.com:secretpassword123:false

Friendo agent

A friendo is an agent to whom you may assign an access token.

1
grunt friendo:SomeGuy:someguy@example.com

Set permissions

The someactionorresource parameter may also specify a database collection name. The boolean parameters below correspond to read/write/execute. Here, the SomeGuy agent has permission to execute on someactionorresource.

1
grunt setpermission:someguy@example.com:someactionorresource:false:false:true

Create token

This token allows an agent access to all the resources to which he’s already been granted permission.

1
grunt createtoken:myfirsthai@example.com:ThisIsMyTokenLetMeIn123

Development

The vanilla gebo agent doesn’t do much. He just sends a friendly greeting to his friendos. Eventually you will implement richer functionality…

Project directory

The gebo grunt-init template produces this directory structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
.. (up a dir)
/home/daniel/test/myfirstagent/
▾ agent/
index.js
▸ cert/
▸ node_modules/
▸ test/
gebo.json
Gruntfile.js
LICENSE-MIT
myfirstagent.js
package.json
README.md

A gebo’s behaviour is defined in agent/index.js.

Configure

Configurations are manipulated in gebo.json. By default, the configuration looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"name":"myfirstagent",
"email":"myfirstagent@example.com",
"domain":"https://localhost",
"port":3000,
"httpsPort":3443,
"docs": "docs",
"testEmail": "myfirstagent-test@example.com",
"logLevel":"trace",
"ssl": {
"key": "./cert/key.pem",
"cert": "./cert/cert.pem"
}
}

Next

Instantiate a gebo HAI…