arangodep

Arango deployment tools.

Install

git clone git://github.com/kaerus/arangodep
cd arangodep
npm i -g

Since arangodep depends on program.js which is under heavy development you must make sure you have the latest/correct version until the API stabilizes. In other words, check-out frequently and report issues if you experience any problems.

Usage

Run arangodep from the terminal to see command options.

ArangoDB deployment tool version 0.5.0
Created by Kaerus <[email protected]>
Help: ?
             app: deploy application
         modules: deploy modules
          routes: configure routing

Type '?' after any command or option to get more help.

Warning: this tool can ruin you database, use with caution!

Create an application

The arangodep tool was created as a tool for deploying applications into the ArangoDB. Its purpose is to simplify the process of creating routes and deploying modules and other content into the Arango database.

bash-3.2$ arangodep app ?
ArangoDB deployment tool version 0.5.3
Created by Kaerus <[email protected]>
Help: app
                 add: Add source file
               fetch: Fetch files from remote
                init: Application init
                push: Push files to remote
             reindex: reindex
               reset: reset application

Use arangodep app init remote http://hostname:port/colleciton ./destination to initialize a working directory for your application. This creates an .indexwhere your deployed files are being tracked.

bash-3.2$ arangodep app init remote http://127.0.0.1:8529/kaerus_com
Created index for: http://127.0.0.1:8529/kaerus_com
bash-3.2$ more .index 
{
  "remote": "http://127.0.0.1:8529/kaerus_com",
  "paths": {},
  "files": {},
  "created": "2013-02-07T10:48:05.614Z"
}

Add files to the index by using the arangodep app add <source-file> command.

bash-3.2$ arangodep app add ./public 
Adding public/1290032361-thin.svg
Adding public/background.png
Adding public/chatty.html
Adding public/commonstyle.css
Adding public/css/chatty.css
.............................

Create the remote collection and push the indexed files to the database.

bash-3.2$ arangodep app push create
creating index: kaerus_com
Pushing 58 files to http://127.0.0.1:8529/kaerus_com
C public/stylesheets/kaerus.css
C public/kaerus_logo_testb.png
C public/js/tabs.js
C public/tabs.js
C public/js/jquery-1.7.min.js
..........................

You can also update a single file and deploy it by using arangodep app push ./some_file. New files must first be included into the index by arangodep app add ./file before they can be deployed.

To download an application you issue the arangodep app fetch remote http://hostname:port/collection command. That downloads all indexed files from the specified collection in to the destination directory.

You may also flush all files by using the arangodep app resetcommand. This also clears both the remote and local index. Other documents (non indexed) are preserved unless you use arangodep app reset collectionin which case the collection is removed from the database.

Configure routes

ArangoDB has a very flexible routing mechanism which yields a rich set of options for configuration.

K1:arangodep kaerus$ arangodep routes add?
ArangoDB deployment tool version 0.5.3
Created by Kaerus <[email protected]>
Help: routes add
     remote(http://127.0.0.1:8529) <url>: ArangoDB server
                         url(*) <string>: Route url
                          methods <json>: URL methods
                       constraint <json>: URL constraints
                         action <string>: Action
                     controller <string>: Action controller
                         prefix <string>: Prefix controller
                             do <string>: Action do method
                          options <json>: Action options
                             id <string>: Patch route
 

We'll only be covering some of the most useful configuration directives in these examples.

The most simple routing directive is an absolute url that directs requests to a single action controller.

arangodep routes add url /simple action /com/kaerus/simple 

By default, only the GET & HEAD requests methods are being forwarded to the action controller. To forward POST, PATCH, DELETE etc you need to specify those explicitely.

arangodep routes add url /simple methods '["GET","HEAD","POST","PATCH","DELETE","PUT"]' action /com/kaerus/test 
Route added: {"url":{"match":"/simple","methods":["GET","HEAD","POST","PATCH","DELETE","PUT"]},"action":"/com/kaerus/test"}

Routes can be wildcarded so that for example the first portion of the url (prefix) matches.

 arangodep routes add url /test/* controller /com/kaerus/test
 Route added: {"url":"/test/*","action":{"controller":"/com/kaerus/test"}}

In this case it is required to also declare which controller to use since ArangoDB would otherwise forward requests to a controller path which also includes the wildcarded-suffix part of the url <controller-path>/<url-suffix>.

ArangoDB is able to extracts parts of the matching url and offer the content of these to the controller as parameters.

arangodep routes add url /users/:uid/profile

The content of the :uid segment is extracted as a parameter for the receiving controller so that the url /users/4321/profile would in this case produce the parameter uid:4321.

It is also possible to specify constraints on named url segments to enforce a parameter format.

arangodep routes add url /users/:uid/profile constraint '{"uid":"\d{3}"}'
Route added: {"url":{"match":"/users/:uid/profile","constraint":{"uid":"[0-9]{3}"}},"action":{}}
# listing the route
    "_id": "_routing/230965671",
    "_rev": "230965671",
    "_key": "230965671",
    "action": {},
    "url": {
      "match": "/users/:uid/profile",
      "constraint": {
        "uid": "[0-9]{3}"
      }
    }

As shown above :uid must now be made up of three digits.

Action controllers (modules)

An action controller is a commonJS module that exports a set of functions to manage action requests. By convention these exported functions are named after http request methods. So for example to create an action controller that responds to GET requests you would exports a GET method in your module. It is however possible to configure the routing so that requests are destined to a specific function with the 'do' directive. Or even export a default 'do' function in the controller itself which would recieve all unhandled requests for that controller.

Use the modules add sub-command to deploy or update modules.

bash-3.2$ arangodep modules add?
ArangoDB deployment tool version 0.5.3
Created by Kaerus <[email protected]>
Help: modules add
     remote(http://127.0.0.1:8529) <url>: ArangoDB server
                        path(*) <string>: undefined
                autoload(true) <boolean>: undefined
                         force <boolean>: undefined

To deploy a module you only need to specify module path and source file provided that ArangoDB also runs on localhost.

bash-3.2$ arangodep modules add path /com/kaerus/render ./render.js 
Deployed module to path /com/kaerus/render with id _modules/231096743

The path is in this case is only a name in the form of an URI /path/for/the/module. Arangodep verifies the module by using a lexical parser (Esprima) to validate the syntax before deploying it to the server.

To list the modules use the list sub-command.

bash-3.2$ arangodep modules list
{"_id":"_modules/8929703","_rev":"11813287","_key":"8929703","autoload":true,"path":"/com/kaerus/forms"}
{"_id":"_modules/231096743","_rev":"231096743","_key":"231096743","autoload":true,"path":"/com/kaerus/render"} 

You can view the contents of the module by using arangodep modules list view and select a specific module by including the id arangodep modules list id _modules/231096743 view.

License

Copyright (c) 2012 Kaerus (kaerus.com), <anders elo @ kaerus com>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.