gebo


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…


Deploy a gebo human-agent interface

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

Set up grunt

Some of these instructions may have already been executed in previous gebo tutorials.

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

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

Get the gebo-react-hai template

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

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

Create a new project

1
2
3
mkdir myfirsthai
cd myfirsthai
grunt-init gebo-react-hai

Upon execution the gebo-react-hai will prompt you for some input, with some fields prefilled:

1
2
3
4
5
6
7
8
9
10
11
12
13
Please answer the following:
[?] Project name (myfirsthai) 
  [?] Description (The best project ever.) My first gebo HAI 
  [?] Version (0.0.0) 
  [?] Project git repository (none) https://github.com/RaphaelDeLaGhetto/myfirsthai.git 
  [?] Project homepage (none) 
  [?] Project issues tracker (none) 
  [?] Licenses (MIT) 
  [?] Author name (RaphaelDeLaGhetto) 
  [?] Author email (daniel@capitolhill.ca) 
  [?] Author url (none) 
  [?] Main module/entry point (index.html) 
  [?] 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 should pass:

1
npm test

Run the development server

1
grunt server

By default, your HAI will be running at http://localhost:9000. There you will see a vanilla gebo HAI interface.

Development

Obviously, a simple Hello, world! HAI isn’t going to suffice. You’re going to want to implement your own functionality…

Project directory

The gebo-react-hai template produces this directory structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.. (up a dir)                  
/home/daniel/workspace/myfirsthai/
  ▸ __tests__/
  ▸ assets/
  ▸ node_modules/
  ▾ scripts/
    ▸ gebo/
    config.js
    HelloWorld.js
    Interface.js
  Gruntfile.js
  index.html
  oauth2callback.html
  package.json
  README.md
  robots.txt

Everything in scripts/gebo directory is critical to interfacing with the gebo-server. Monkey with it at your own risk. I like to place project-specific React components in a scripts/lib directory, which I create myself. Use scripts/HelloWorld.js and scripts/Interface.js as launch points for your own gebo HAI.

Out of the box, the HelloWorld.js interface is intended as a welcome to unauthenticated clients. The functionality defined in Interface.js is only for friendos of the corresponding gebo agent.

Configure

Your HAI needs to know what gebo agent it’s talking to. This is specified in config.js.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// ...

/**
 * This HAI's name and client ID
 */
var name = 'myfirsthai';
var clientId = 'myfirsthai@example.com';

/**
 * The agent with which this HAI interacts
 */
var gebo = 'https://localhost:3443';

// ...

Set up an Ubuntu 14.04 gebo production environment

This document provides step-by-step instructions on how to set up Ubuntu 14.04 for a gebo production and/or development environment. It is comprehensive so that you may copy, paste, and execute the commands and deploy the configurations provided, from beginning to end. Deployed correctly, this environment will host as many gebo-servers and HAIs as the host hardware will allow.

gebo is not dependent on Ubuntu specifically, but requires the same third-party software no matter the operating system you choose.

Let’s get started…

Update the OS

1
2
sudo apt-get update
sudo apt-get upgrade

git

1
sudo apt-get install git

MongoDB

Add the repository

Verify instructions here.

1
2
3
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10
echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list
sudo apt-get update

Install

1
sudo apt-get install mongodb-10gen

Start

1
sudo service mongodb start

How to remove

This is for reference. Do not execute these commands unless you want to remove MongoDB.

1
2
3
sudo apt-get purge mongodb mongodb-clients mongodb-server mongodb-dev 
sudo apt-get purge mongodb-10gen 
sudo apt-get autoremove

node

1
2
3
4
sudo apt-get install -y python-software-properties python g++ make 
sudo add-apt-repository ppa:chris-lea/node.js 
sudo apt-get update 
sudo apt-get install nodejs

This should also install the Node Package Manager (npm)

grunt-cli

1
sudo npm install -g grunt-cli

bower

1
sudo npm install -g bower

ruby 1.9.3

Newer versions of ruby probably work fine. I hope to remove this dependency in the near future, because it’s really only needed for compass, which I want to get rid of.

1
sudo apt-get install ruby1.9.3

compass

1
sudo gem install compass

forever

1
sudo npm install -g forever

nginx

1
sudo apt-get install nginx

vim

This part is optional. I include it for my own reference, and also because everyone should use vim.

pathogen.vim

1
2
3
4
mkdir -p ~/.vim/autoload ~/.vim/bundle
cd ~/.vim/autoload
wget https://raw.github.com/tpope/vim-pathogen/HEAD/autoload/pathogen.vim
vim ~/.vimrc

Add this to the .vimrc file:

1
2
3
4
5
6
call pathogen#infect()
map <C-n> :NERDTreeToggle<CR>

set softtabstop=4
set expandtab
set cindent

Save and exit.

NERDTree

1
2
cd ~/.vim/bundle 
git clone https://github.com/scrooloose/nerdtree.git

Next

Instantiate a gebo agent…